The monorepo

Kept is one pnpm workspace (pnpm-workspace.yaml: apps/* and packages/*). Node 24 and pnpm 11 are required (engines and packageManager in the root package.json). Dependencies are pinned to exact versions. TypeScript is shared through tsconfig.base.json.

Packages

Package	Path	What it is
`@kept/server`	`apps/server`	The Fastify server, the job worker and the `kept` CLI (`bin: dist/cli/index.js`)
`@kept/web`	`apps/web`	The React web app and PWA, built by Vite into `apps/web/dist`, which the server serves
`@kept/docs`	`apps/docs`	This site: Starlight, built to static files
`@kept/shared`	`packages/shared`	Code both sides import: error codes, the role matrix (`roles.ts`), ids, money, modules, the sync contract, normalisation
`@kept/mcp`	`packages/mcp`	MCP tool definitions, their output shapes and vocabulary

Inside the workspace @kept/shared and @kept/mcp resolve to their TypeScript sources; Node’s --conditions=kept-dist selects their compiled dist/ instead (the end-to-end server runs that way).

Outside the packages: charts/kept (the Helm chart), docker/ (database bootstrap scripts, the Caddyfile, the image’s health check), compose.yaml and compose.dev.yaml, Dockerfile, docs/ (specs, plans, spikes, runbooks, performance reports) and scripts/.

`apps/server/src`

One directory per feature. Most hold routes.ts (Fastify routes), service.ts (the rules, on a scoped transaction), view.ts (response shapes) and undo.ts (in-app undo handlers).

Directory	What it holds
`accounts`	`ensureAccount()`, sign-up, `/me`
`admin`	Instance-admin routes and the account operations the CLI shares
`agenda`	Every reminder source as one list
`ai`	Providers, the call door, budgets and caps, the ledger, the mock
`alerts`	Conditions an instance admin must hear about
`assistant`	The in-app assistant: threads, turns, proposals
`audit`	`audited()`, field classes, rendering and undo
`auth`	Better Auth setup, the session and CSRF hooks, two-factor gate, OIDC, managed accounts, rate limiting
`backup`	restic snapshots, the readable copy, verify, drill, restore
`boxcheck`	Box checks
`calendar`	The private iCal feed
`capture`	Capture batches and their undo
`cli`	The `kept` command: `migrate` and `admin …`
`codes`	A location’s own codes and their format rule
`config`	The environment schema (`env.ts`) and its generated reference
`consumables`	Stock rules for consumables
`crypto`	Envelope encryption, the keyring, Crockford base32
`currencies`	The currency list and its settings
`db`	Pools, `withScope()`/`withSystem()`, migrations, the release guard, the Drizzle schema (`db/schema/`)
`embeddings`	Semantic search’s embeddings and their backfill
`enrich`	AI alias enrichment
`exports`	Location exports
`extraction`	AI extraction jobs, checks, duplicates, prompts
`files`	Uploads, attachments, signed file serving, PDF text
`fuel`	Fuel and charging entries
`history`	History and the activity feed
`home`	The home screen’s checklist, attention counts, overview (cards, tiles, Insights teaser) and hints
`http`	`buildApp()`, conventions, errors, module gating, health, the web bundle
`imports`	CSV, Homebox and Kept archive imports
`inbox`	The review inbox and bulk actions
`incidents`	Incidents and claim packs
`invites`	Invites to a location
`jobs`	pg-boss setup, the job registry and policies
`labels`	Label batches and claiming blank labels
`lending`	Loans
`lists`	CSV export of the things list
`locations`	Locations, members, membership jobs
`mail`	Outgoing mail and its messages
`managed`	Managed accounts
`mcp`	`/mcp`: its bearer verification and server
`meters`	Meters, readings and their checks
`money`	Exchange rates, valuations, conversions
`net`	The SSRF guard for outbound requests
`notices`	Configuration-change notices to every user
`notify`	The notification centre, channels, web push
`oauth`	Kept as an OAuth server for MCP connectors (CIMD, consent)
`observability`	Optional tracing and error reporting
`paperwork`	Expiring documents
`places`	The place tree
`portability`	Export passphrases and ZIP handling
`purchases`	Purchases and their lines
`registries`	Types, place kinds, brands, vendors, people, tags
`reminders`	The reminder scan, deliveries, digests
`reports`	Inventory, insurance and vehicle reports
`scan`	Resolving a scanned code; barcode lookup
`schedules`	Schedules and service records
`search`	Search, document search, saved views, semantic search
`secrets`	Secret field values and key rotation
`seed`	`kept admin seed` scenarios
`serialize`	Response gates for money and secret values
`services`	Service drafts from an invoice
`setup`	The setup code and the recovery kit
`storage`	The blob store: local and S3 drivers, derivatives, signed URLs
`sync`	The phone’s snapshot, cursor and offline ops
`templates`	Templates and quick add
`things`	Things, moves, custom fields
`tokens`	Personal tokens: routes, verification, rate limit, which routes they may call
`tools`	`runTool()` and the tool handlers the assistant and MCP share
`trash`	The trash and the daily purge
`types`	Type changes and field conversion
`undo`	The undo registry and route
`updates`	The opt-in update check
`vehicles`	Vehicle costs, lists and series
`warranties`	Warranties and claims
`webhooks`	Location webhooks and their delivery

Next to src/: migrations/ (SQL and drizzle-kit’s snapshots), test/ (the leak test, the route catalogue, shared fixtures), bench/ (the RLS benchmark), eval/ (extraction, assistant and search evaluations) and assets/ (report fonts).

`apps/web/src`

Directory	What it holds
`api`	The fetch client, query hooks, and the request and response types per area
`assistant`	The assistant panel, composer and confirm cards
`camera`	The camera, barcode and QR scanner (zxing wasm)
`components`	Screens’ building blocks, by feature, and the shared UI kit
`i18n`	Lingui setup
`lib`	Formatting, bidi isolation, preferences, small helpers
`locales`	The `en`, `ar`, `fr`, `de` and `it` catalogues (`messages.po`)
`offline`	The Dexie database, the queue, the sync engine, app lock
`pwa`	Service-worker registration, install, push, share target, diagnostics
`routes`	TanStack Router file routes (`routeTree.gen.ts` is generated)
`styles`	Design tokens and the global stylesheet
`test`	Test setup and helpers

sw.ts is the service worker’s source and demo.ts the fixture mode (?demo=…). End-to-end tests are in apps/web/e2e (Playwright).

Root scripts

Script	What it runs
`pnpm lint`	`biome check .`, then `check-logical-css`, `check-i18n` and `check-no-local-paths`
`pnpm format`	`biome format --write .`
`pnpm typecheck`	`tsc` on the root project, then every package’s `typecheck`
`pnpm test`	`vitest run` over the projects `packages/*`, `apps/server`, `apps/web` and `scripts`
`pnpm ci`	`bash scripts/ci-local.sh`, the full gate
`pnpm bench:rls`	The RLS benchmark: the server’s `bench`, then `bench:pi` with a 512 MB heap
`pnpm eval:extraction`, `eval:assistant`, `eval:search`	The AI evaluations (mock provider unless told otherwise)
`pnpm docs:dev`, `docs:build`	This site

Package scripts worth knowing: pnpm --filter @kept/server dev (tsx watch src/main.ts), pnpm --filter @kept/server kept <command> (the CLI from source), pnpm --filter @kept/web dev (Vite), pnpm --filter @kept/web build (the bundle, then its size check), pnpm --filter @kept/web e2e, and pnpm --filter @kept/docs gen:config (regenerates the configuration reference from config/env.ts).

Checks

Tool	What it checks
Biome (`biome.json`)	Lint and format
`tsc`	Types, per package
Vitest	Unit and integration tests; server tests clone a database per worker. See testing
Lingui	`scripts/check-i18n.mjs`: every source message is in all five catalogues; `check-i18n-extract.mjs`: a real `lingui extract` finds nothing new
`scripts/check-logical-css.mjs`	No physical-side CSS in `apps/web/src`, so Arabic mirrors
`scripts/check-no-local-paths.mjs`	No home directories, private addresses or tailnet names in tracked files
`scripts/check-licences.mjs`	Every dependency’s licence is on the allowlist
`scripts/check-attribution.sh`	No AI attribution in commits (also the commit-msg hook in `.githooks/`)
`scripts/check-dco.sh`	Every commit is signed off by its author
`scripts/check-helm.sh`	The chart: lint, golden renders, kubeconform, image pins
`apps/web/scripts/check-bundle.mjs`	The web bundle and precache size budget

bash scripts/ci-local.sh --list prints the gate’s steps: install, lint, catalogues, typecheck, compose, test, drift, licences, attribution, docs, helm, prod-boot, eval, portability, backup, perf, e2e, images, release-dry-run. --fast runs lint, catalogues, typecheck, the unit tests and the evaluations, with no Docker. On a pull request GitHub Actions (.github/workflows/ci.yml) runs the fast half and the licence, attribution and sign-off checks; the steps that need Docker and the database run locally.