Architecture and development

Fahrtenbuch consists of the server (cheinisch/fahrtenbuch) and the Android app (cheinisch/Fahrtenbuch-Android). Both are licensed under the GNU AGPL v3.

Server

An npm workspaces monorepo (Node.js 22 or newer):

Directory	Contents
backend/	Express 5 REST API (/api/v1), PostgreSQL via pg, a Redis job queue and worker, PDF export with pdfkit
frontend/	React + Vite web dashboard, maps with MapLibre GL JS
shared/	Shared package
api/openapi.yml	The public API contract the Android app is built against

Database migrations are plain SQL files in backend/src/database/migrations/, applied in order on server start. Released migrations are never changed.

Local development

git clone https://github.com/cheinisch/fahrtenbuch.git
cd fahrtenbuch
npm install
npm run dev                         # backend + frontend

The backend needs a PostgreSQL database (POSTGRES_*), JWT_SECRET and the DEFAULT_ADMIN_* variables.

Command	Purpose
npm run migrate --workspace backend	Run migrations manually
npm run check --workspace backend	Check that every documented endpoint is implemented (OpenAPI coverage)
npm test	Tests in all workspaces
npm run build	Build the frontend

Conventions

• API changes go into api/openapi.yml (copied byte-identical to backend/openapi.yml) and should be backwards compatible, so existing app versions keep working.
• Time zones: timestamps are stored in UTC; trips keep the IANA zone where they started. Day and month grouping always uses the local time of the trip.
• Translations: one JSON file per language in frontend/src/i18n/locales/<language>/translation.json, nested camelCase keys, split into sections per page. German is the reference language. Comments are allowed, so the files are read with a JSONC parser.
• Preview features can be limited to the :dev image via config.features and FEATURE_<NAME>.

The repository's AGENTS.md describes all conventions in detail; INTEGRATION.md and README_API.md cover the API.

Documentation

This documentation lives in its own repository, cheinisch/fahrtenbuch-docs (Docusaurus). /docs/ always shows the current state; when a release is published, the current state is frozen as a version and stays available in the version dropdown.