# Contributing ## Getting a dev environment You need Node.js 20.19 or newer (the project is developed on 22, which is the version `flake.nix` and `.nvmrc` pin) and pnpm. A Rust toolchain (`rustup`) is only needed if you work on the desktop or mobile shells. ```bash pnpm install pnpm dev # API on :3000 + web app on :5173, with hot reload pnpm seed # optional: demo courses and study fixtures ``` If you use Nix, run `nix develop` for the pinned toolchain: Node, pnpm, Rust, and on Linux the Tauri webkit2gtk libraries. With direnv it activates on its own through the checked-in `.envrc`. See `flake.nix`. Stick to one Node version across install and run. The API depends on `better-sqlite3`, a native module compiled against the Node that ran `pnpm install`, so starting the API or the tests under a different major version fails with a `NODE_MODULE_VERSION` mismatch error from `better-sqlite3`. The simplest fix is to run everything inside `nix develop`, which gives you the pinned Node 22. Otherwise switch to Node 22 by hand and reinstall, so the module is rebuilt against it: ```bash rm -rf node_modules apps/*/node_modules packages/*/node_modules pnpm install ``` For the desktop shell: ```bash cd apps/shell pnpm tauri dev ``` ## Configuring the API The API reads its configuration from `apps/api/.env`. Copy the example and set a `SESSION_SECRET`, which is the only variable required in production. ```bash cp apps/api/.env.example apps/api/.env ``` `.env.example` documents every variable with its default. The ones worth knowing about: | Variable | Role | Default | | ------------------------------ | -------------------------------------------------------- | -------------------------- | | `PORT` / `HOST` | where the API listens | 3000, `127.0.0.1` | | `SESSION_SECRET` | signs the session cookie, required in production | none | | `AUTH_DISABLED` | turns the login gate off (single user on localhost only) | `false` | | `DB_DIALECT` | `sqlite` or `postgres` | `sqlite` | | `DB_PATH` | SQLite file when the dialect is sqlite | `apps/api/data/synapse.db` | | `DATABASE_URL` | connection string, required for postgres | none | | `OPENAI_API_KEY` | generation and OCR, works on the free tier | none | | `ANTHROPIC_API_KEY` | alternative provider | none | | `PANDOC_PATH` / `SOFFICE_PATH` | conversion binaries when they are not on `PATH` | looked up on `PATH` | | `CORS_ORIGINS` | origins allowed to call the API with credentials | none, same-origin | The AI provider, model and key can also be set from `Settings > AI` in the app. That is stored server-side and takes precedence over the env vars. See [AI setup](ai.md) for the provider details and [Authentication](auth.md) for the `AUTH_*` variables. Uploads beyond PDF need converters on the machine running the API. pandoc plus a PDF engine handles the markup formats; `pandoc.adapter.ts` probes typst, tectonic, weasyprint, wkhtmltopdf and xelatex in that order and takes the first one it finds, so installing typst alone is enough. LibreOffice handles the office formats and renders pptx faithfully. Both are optional. Without them docx, odt and rtf fall back to pandoc when it is there, and the office-only formats are rejected with a message naming the tool that is missing. ## Repo layout ``` apps/web Svelte 5 SPA, where all the study features live apps/api NestJS API: auth, files, AI proxy, sync log apps/shell Tauri shell (desktop and mobile) with the LAN sync plumbing (Rust) packages/ai-core provider-agnostic AI calls packages/design-system UI components and tokens docs this documentation (mkdocs) ``` Read the [architecture page](architecture.md) before touching the data layer. The local-first model, with the CRDT documents as the source of truth and the server as an optional peer, shapes almost every design decision here, and the "where to start reading" table on that page maps the important files. ## Quality gates All of the following must pass before a change lands. Run them locally: there is no CI in this repository, so nothing else will catch a failure. ```bash pnpm lint # eslint across the monorepo pnpm --filter @synapse/web check # svelte-check + i18n compile pnpm --filter @synapse/web test # vitest (unit) pnpm --filter @synapse/api test # jest (unit + integration) pnpm --filter @synapse/web test:e2e # playwright, seeds its own db cd apps/shell/src-tauri && cargo test ``` The root package wraps those in aggregate scripts. `pnpm test` runs every unit and integration suite. `pnpm test:e2e` builds the API and the web app first, then hands over to Playwright. `pnpm test:coverage` enforces the coverage thresholds and `pnpm test:mutation` runs Stryker over the unit layers. `pnpm lint` already runs knip and the dependency-cruiser layer checks, so a stray export or an import that crosses a layer boundary fails there. The API suites are Jest. Unit specs sit next to the services with their ports mocked. The `apps/api/test/*.integration-spec.ts` suites boot the whole Nest app on a throwaway SQLite database and drive every endpoint through supertest, with doubles standing in for the AI provider, pandoc and LibreOffice, so those specs make no network call at all. A handful of specs do want a real pandoc or LibreOffice, and they skip themselves when the binary is not installed. The web e2e suite is the only one that opens a browser. `playwright.config.ts` starts both servers itself, the API on :3100 and the Vite preview on :4173 proxying `/api` to it. Before the API boots, `apps/web/e2e/prepare-db.mjs` creates a fresh database at a disposable path and applies the migrations to it, then the seed writes the study fixtures. The suite never reads or writes your dev database, and its data is exactly what the seed put there, which is what keeps the runs deterministic. Specs drive the UI through accessibility roles rather than ids or pixel clicks on the canvas, and one spec runs axe WCAG scans over every main page. The design system has its own Vitest specs and a Storybook catalogue, served by `pnpm storybook` from the root. ## Building for production ```bash pnpm build # ai-core, then the API into apps/api/dist, then the web app into apps/web/dist pnpm start # builds, then starts the API on :3000 serving the web build ``` The API serves `apps/web/dist` and `/vendor/pdfjs` itself, falls back to `index.html` for any non-`/api` route, and compresses what it sends. Hashed assets get immutable one-year caching while the shell stays `no-cache`. Migrations apply themselves at boot, so there is no migrate step; after a schema change, regenerate them with `pnpm --filter @synapse/api db:generate`. The web app has two other build targets. `build:tauri` produces the bundle the desktop and mobile shells embed, and `build:web-client` produces a browser build that runs with no server at all. [Install a server](setup.md) covers deploying either one, running the API as a service and putting TLS in front of it. ## Conventions - Commits follow [Conventional Commits](https://www.conventionalcommits.org): `type(scope): summary`, where type is one of feat, fix, docs, style, refactor, perf, test, build, ci, chore or revert, and scope is optional (`web`, `api`, `shell`, `design-system`). Keep the summary short, lowercase and imperative. - User-facing strings go through Paraglide (inlang). The catalogs are `apps/web/messages/en.json`, `fr.json` and `pt-BR.json`; add every new message to all three. Paraglide compiles them into typed functions under `src/paraglide/` (this runs automatically with `check`, `test` and the dev server), and components call them as `m.your_message_key()`. A key missing from a locale fails the compile, so forgetting a translation is caught early. - E2E selectors are role-based (`getByRole`) rather than CSS classes. - The web app never reads study data over HTTP. Pages call the repositories in `apps/web/src/lib/data/repos/`. If a feature seems to need a new server endpoint, check the architecture first, because it usually needs a document field instead. - Errors surface as `neverthrow` results on the client, and unhandled rejections are treated as bugs. - Documentation lives in `docs/`. When you change behaviour, update the page that covers it. Install the tooling once with `pip install -r docs/requirements.txt`, then preview the site with `pnpm docs:serve` (and build it with `pnpm docs:build`). These wrap `mkdocs`. The browser demo is not part of the docs site: it is the web-client build deployed to Netlify with `pnpm demo:build` then `pnpm demo:deploy` (log in once with `pnpm --package=netlify-cli dlx netlify login`). ## AI assistance AI tools were used to help build this project, and they are welcome for contributions too, under the same discipline the codebase was built with: plan first, then generate, then review. Concretely, AI here automates boilerplate and test scaffolding after a carefully crafted plan, and every produced result is read, questioned and tested by a person before it lands, with quality, security and accessibility in mind. The decisions that shape the project, such as the data model, the security model, the dependencies and the UX, are made by humans. Nothing is merged blindly.