Contributing

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

A question rather than a change goes to Discussions, and so does an installation you cannot get working. The issue tracker takes reproducible defects and feature requests; Getting help explains where each kind of request goes.

Get it running

You need Node, pnpm, and Docker for the local PostgreSQL. The repository pins the versions: engines in package.json sets the oldest Node it accepts, and packageManager names the pnpm, which Corepack installs for you.

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 can run 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 eight packages: apps/api (NestJS, Prisma), apps/web (React, Vite, Tailwind), apps/demo (the online demo), packages/shared (domain types, the import schema, Decimal money), packages/mcp, docs (Astro and Starlight), which is this site, site, the front page at badlen.fr, and packages/brand, what those two share; 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/, the French counterpart under docs/src/content/docs/fr/, and pnpm --filter @badlen/docs dev serves both. 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

One command, from the repository root:

pnpm check

It runs format:check, lint, typecheck, test, build and knip in the order the check job runs them, stops at the first one that fails and names it on the last line: check failed at: pnpm <step>.

The suites needing a real PostgreSQL skip themselves in that run, and CI checks that none of them was skipped there. 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 fails the API suite until pnpm api:reference rewrites them. The Prisma client is generated too, so after editing schema.prisma regenerate 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.