Development

Parallel worktrees

make worktree-add WORKTREE_PATH=/tmp/champagne-example WORKTREE_BRANCH=feat/example

From the new worktree, run make worktree-up. Each worktree gets a unique .localhost hostname, port allocation, and Compose project. Stack identity is recorded under .local/, so shutdown cannot target a different checkout.

• make worktree-logs: inspect this stack.
• make worktree-down: stop it without deleting volumes.
• make worktree-clean: explicitly delete this stack's volumes and identity.
• make worktree-remove WORKTREE_PATH=/tmp/champagne-example: remove a clean, stopped worktree from a retained checkout.

Do not run all-worktree stop or cleanup commands while other sessions are working.

Quality checks

make check runs code generation drift checks, type checking, formatting, linting, tooling tests, and unused-code detection. make test runs backend and frontend tests plus a disposable PostgreSQL integration suite. The database tests verify autocommit, rollback, seeding, and GraphQL persistence. CI additionally builds and smoke-tests the production Docker image against its own PostgreSQL instance. The former E2E job is commented out; its suite, configuration, and dependencies have been removed.

Documentation

make docs
make docs-check

Fumadocs runs on Next.js for authoring and exports static HTML, assets, and a client-side search index. Content lives in docs/content/docs/; source and navigation configuration live in docs/source.config.ts and the collection's meta.json. make docs-check typechecks, builds, and validates internal links and heading anchors without crawling external sites.

Dockerfile.docs serves the export with Caddy at docs.champagne.dev-ukab.fr. Terraform owns its separate Scaleway container, DNS, and custom-domain binding. Main-branch CI/CD builds and deploys both the app and docs when the documentation container ID is configured. No Fumadocs account, API key, or Node.js runtime is required on the documentation container.

Production image

docker build -t champagne:local .
# Terraform supplies production runtime connection settings and secrets.

Caddy serves the built frontend and React Router fallback on port 8080, and proxies /api/* to Elysia on internal port 3000. The backend serves GraphQL only. A supervisor shuts down both processes together. Terraform supplies production connection settings and generated credentials. Startup runs drizzle-kit push; no SQL files are needed. See Database.

Frontend data and navigation

React Query executes the generated people operation, owns caching and request cancellation, and exposes loading/error/refresh state to the HeroUI table. Fresh results are reused for 30 seconds. React Router redirects / to /people and shows a not-found page for unknown routes. Caddy serves the HTML entrypoint for browser deep links while missing assets and unknown API routes stay 404s.

The codegen configuration is scripts/codegen.ts. Project-specific testing and observability guidance is in robot-docs/testing.md and robot-docs/observability.md; it is adapted to this starter rather than assuming Medals' Vue, Storybook, or local LGTM infrastructure exists.