Synapse is a study workspace. Organize courses read and annotate the material, train with generated exercises and watch your progress forked from denishovart.com/synapse
synapse docs contributing.md
9.9 kB · 194 lines
Markdown
at main

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.

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:

rm -rf node_modules apps/*/node_modules packages/*/node_modules
pnpm install

For the desktop shell:

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.

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 for the provider details and Authentication 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 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.

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 #

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 covers deploying either one, running the API as a service and putting TLS in front of it.

Conventions #

  • Commits follow Conventional Commits: 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.