Skip to main content

Development Workflow

Tome of Sessions is a full-stack app with a Vite/React frontend, FastAPI backend, PostgreSQL database, and AI/RAG services. Most changes cross at least two boundaries, so keep the API contract and feature ledger in sync.

Local Setup​

From the repository root:

docker compose up -d
cp server/.env.example server/.env
npm run install:all

Run the app in watch mode:

./start.sh

The app runs on http://localhost:5559 by default and proxies API/upload requests to the FastAPI server on :4000. The launcher also serves this docs site with the Docusaurus dev server on http://localhost:3050 (override with DOCS_PORT). ./stop.sh frees all three ports.

Branching & Pull Requests​

Direct pushes to main are not allowed. Every change lands through the same flow:

  1. Branch off the latest main (feat/…, fix/…, docs/…, chore/…).
  2. Commit on the branch and push it to the remote (git push -u origin <branch>).
  3. Open a pull request against main and wait for CI to pass. The PR description follows the What / Why / How template in .github/PULL_REQUEST_TEMPLATE.md (GitHub pre-fills it), and the PR title follows the Conventional Commits format — type(scope): imperative lowercase summary, with type one of feat / fix / docs / test / refactor / chore / ci / perf (e.g. fix(encounters): carry statBlockRef through AI suggestions).
  4. Merge through the PR.

Continuous Integration​

.github/workflows/ci.yml runs on every pull request (and on main after a merge) with three jobs:

  • server — uv sync, uv run ruff check ., uv run pytest against an ephemeral pgvector Postgres service on :5433 (the integration conftest creates the tome_py_test database itself).
  • web — npm ci, npm run build (type-check + production build), npm test.
  • docs-site — npm ci, npm run build (broken links fail the build).

A PR must be green on all three jobs before merging.

Verification Commands​

Run these before considering a code change complete:

cd server
uv run pytest
uv run ruff check .

cd ../web
npm run build

For docs-only changes, run the docs build too:

npm install --prefix docs-site
npm run docs:build

Feature Ledger Rule​

Every feature addition, change, or removal must update the Features page in the same change. Move items between planned, in-progress, and done when relevant, add new entries, and keep the _Last updated_ date current.

The practical rule: if a user can notice it, a developer depends on it, or an API contract changed, the Features page should mention it.

Change Flow​

  1. Read the existing code and nearby tests first.
  2. If request/response shapes change, update backend schemas/serializers and frontend DTO/API helpers together.
  3. Add or adjust tests around the behavior you changed.
  4. Run backend tests, backend lint, and frontend build.
  5. Update README.md, this docs site, and the Features page when the workflow, architecture, API, or user-facing behavior changes.

Common Working Areas​

AreaStart Here
Backend routeserver/app/routers/, server/app/schemas.py, server/app/serializers.py
Authorizationserver/app/deps.py, server/app/lib/access.py
Database schemaserver/app/models.py, server/alembic/versions/
Frontend API callweb/src/lib/api.ts, web/src/types.ts
Campaign UIweb/src/screens/CampaignDetail.tsx, campaign sub-screens, shared components
Sage AIserver/app/lib/rag/, server/app/lib/tools/, server/evals/