Contributing

The full guide is .github/CONTRIBUTING.md, and it is the one kept current. This page is the shape of the cycle, so you know what you are walking into before you clone. Code, comments and documentation are written in English; the interface ships in French and English, French being the source language.

Get it running

You need Node 22.12 or newer, pnpm 12.5.1, and Docker for the local PostgreSQL.

1. pnpm install, then docker compose -f docker-compose.dev.yml up -d for the database. That stack runs under its own compose project, so it sits beside a self-hosted instance.

2. Copy apps/api/.env.example to apps/api/.env and fill in its secrets, or the next step stops on an empty database URL.

3. pnpm --filter @badlen/shared build, before anything else typechecks: the API reads that package through its compiled output.

4. pnpm --filter @badlen/api exec prisma migrate dev for the schema, then pnpm dev, which serves the API on :3001 and the web app on :5173.

The workspace is five packages: apps/api (NestJS, Prisma), apps/web (React, Vite, Tailwind), packages/shared (domain types, the import schema, Decimal money), packages/mcp, and docs (Astro and Starlight), which is this site; tools/ beside them holds the sweeps run against a live instance.

This site is written in the same repository as the code it describes. Its pages are the Markdown files under docs/src/content/docs/, nested one level deeper than that path suggests: the documentation is in docs/src/content/docs/docs/, its French counterpart in docs/src/content/docs/fr/docs/, and pnpm --filter @badlen/docs dev serves the lot. English is the master and French follows it; pnpm translations says which pages have fallen behind. The guide has the rest, under The documentation site.

The gate

The same checks CI runs, from the repository root:

pnpm format:check
pnpm -r lint
pnpm -r typecheck
pnpm -r test
pnpm -r build

The suites needing a real PostgreSQL skip themselves out of that run, and CI asserts none of them did. Replay them as CI does, on a port of your own: PG_PORT=55613 pnpm live.

Two things are generated, not written

The REST API reference comes from the controller, both language versions of it, and a test re-runs the generator and fails on any difference, so a route or a scope you change reddens the API suite until pnpm api:reference rewrites them. The Prisma client is generated too, so after editing schema.prisma re-run it with pnpm --filter @badlen/api prisma:generate.

Opening a pull request

A schema change ships its generated migration under apps/api/prisma/migrations, a new user-facing string exists in both locales/fr and locales/en with the same keys, and no real figures, account numbers or secrets go in the diff. Commit subjects are concise and imperative, as in Add cost basis to positions view. Keep prose in English, keep dashes out of it, and add no co-author trailer.

Contributions are licensed under AGPL-3.0. You keep the copyright on what you write, and you also grant the maintainer a non-exclusive right to distribute your contribution under other license terms, including commercial ones, so that a hosted offering remains possible; Badlen itself will continue to be available under a free software license. The code of conduct applies. A security problem goes through SECURITY.md, never a public pull request.