Contributing

We build Sifa ID in the open. The SDK and the lexicons carry the MIT licence, and they are open to anybody. The core service (sifa-api, sifa-web) is source-available, and contributions arrive by invitation. This page gets you from "I would like to help" to a merged pull request.

The canonical rules live in the org guide: CONTRIBUTING in singi-labs/.github and the engineering harness. This page is the practical on-ramp.

What we build toward

Sifa ID builds toward a professional reputation that you earn and own. It comes from real work. The people who know you vouch for it. It travels across the open web, so no single company can gate it or switch it off. Professional life is where we start, not where we stop.

Earned, not claimed. Owned by you, built for the open web.

The principles, and the list of things we will not build, live on the about page. They decide what belongs in Sifa. A change that works against one of them does not belong. When you propose a feature and you are not sure that it fits, open an issue and name the principle that it serves.

The stack

Sifa is TypeScript end to end: Fastify, PostgreSQL, and Valkey behind sifa-api, Next.js with React and Tailwind in sifa-web, all built on AT Protocol. The credits page has the full list, down to the infrastructure, editors, and open datasets we build on.

Finding something to work on

Start with issues labelled good first issue, which are small, well-scoped, and a good way to learn the codebase:

• Across all of Sifa: open good first issues in singi-labs
• By repo: sifa-sdk · sifa-api · sifa-web
• Want more depth? Swap the label for help wanted.

You see issues only in the repos that you can reach. The SDK and the lexicons are public. The core repos appear after we add you.

Claim it first: comment on the issue to say that you take it, so two people do not build the same thing. No issue for your idea? Open one. Agree the scope before you write code.

Local setup

You will need Node (current LTS), Docker + Docker Compose, and Git. The exact commands (package manager, services, env vars) live in each repo's README.md and AGENTS.md, which are the source of truth:

• sifa-sdk: TypeScript library. Clone, install, test.
• sifa-api: backend. Clone, pnpm install, pnpm services:up (PostgreSQL + Valkey), pnpm db:migrate, pnpm dev.
• sifa-web: frontend. Clone, pnpm install, pnpm dev (needs sifa-api running).

AT Protocol auth is OAuth, never app passwords, an org-wide rule with no exceptions.

Before you open a PR, run the repo's checks locally:

pnpm test
pnpm lint
pnpm typecheck

The workflow

1. Branch from main: git checkout -b feat/short-description. One branch, one change. Never push to main.
2. Build it with tests. The test suite is the contract.
3. Open a PR, link the issue (Closes #NN), fill the checklist.
4. Sign the CLA on your first PR. A bot asks you in a comment. Reply once, and the signature covers all your later PRs.
5. Automated gates run: a secret scan, and a blocking AI reviewer that posts a comment. Address anything it flags and push (it re-runs).
6. A maintainer reviews and merges (squash). You cannot merge your own PR.

Commits follow Conventional Commits: type(scope): description (feat, fix, docs, test, refactor, chore, ci).

The standards

The AI reviewer and maintainers both enforce the engineering standards. The essentials: strict TypeScript with no any, Zod on every input, tests with every change, sanitised user content, accessible UI, and no console.*. Reuse an existing UI primitive before you add a new one.

The accessibility baseline is WCAG 2.2 AA. On top of that we adopt WCAG 3 draft outcomes that are already testable: form errors next to the field, a reason for each disabled control, and focus indicators with 3:1 contrast.

If you use a coding agent (Claude Code or similar), drop agent-instructions.md into your clone as CLAUDE.md / AGENTS.md to keep it inside the house rules.