A fullstack template: a FastAPI backend and a Next.js frontend, wired together with one worked domain — authentication and user management — and nothing else. It exists to be extended: the auth + users vertical is the reference pattern for every layer, and the repo ships lint rules, AST-based architecture tests, and a set of agent skills/reviewers that hold new code to the same shape.
Scope, honestly: there is no billing, no tenancy, no catalog, no second domain. If you need a
"real" business entity to copy from, copy the users vertical (backend) and the features/users
vertical (frontend) — see the recipes in AGENTS.md.
| Backend | FastAPI + SQLAlchemy 2.0 (async) + asyncpg + Alembic + PostgreSQL 16, Argon2id password hashing (off the event loop), JWT access tokens + rotating opaque refresh tokens, double-submit CSRF, RBAC (admin/member) |
| Frontend | Next.js 16.4.6 (App Router, RSC-first) + React 19 + TypeScript (strict) + Tailwind CSS 4 + TanStack Query + react-hook-form/zod, an orval-generated API client, a small accessible UI kit and a responsive app shell |
| Security | Origin/Referer checks on cookie-authenticated mutations, login rate limits stored in Postgres, a security-event audit log, idle and absolute session lifetimes with silent renewal, a nonce-based Content Security Policy, API docs only in development, non-root digest-pinned images |
| Operations | Structured JSON logs with request IDs, throttled alerts for unhandled errors (log or any webhook), dependency and image scanning with uv audit, npm audit and Trivy, Dependabot, an optional single-VPS deploy with Caddy and backups |
| Agent tooling | Claude and Codex skills for grooming, delivery, orchestration and deploys, three shared review rubrics, and a vendored security-audit skill — see below |
Requires Docker with Compose v2+. From the repo root:
AUTH_JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))") docker compose up --buildAUTH_JWT_SECRET is required — Compose refuses to start the api service without it
(docker compose config fails fast with required variable AUTH_JWT_SECRET is missing a value),
and it must decode to at least 32 bytes. Export it in your shell or put it in a root .env file
that Compose reads automatically; do not commit it.
This brings up Postgres 16, the API (migrated automatically on container start via
backend/entrypoint.sh, which runs alembic upgrade head before serving), and the frontend,
proxying /api/* from the frontend to the API container. Frontend: http://localhost:3000. API:
http://localhost:8000. Every published port binds to 127.0.0.1 only. The stack runs with
ENVIRONMENT=production by default, so /docs is off; set ENVIRONMENT=development to get it.
Create the first admin (the password is prompted, never echoed):
docker compose exec api python -m app.commands.bootstrap_admin [email protected]Backend (from backend/, requires Python 3.12 and uv):
uv sync
cp .env.example .env
uv run alembic upgrade head
uv run python main.py.env.example sets DATABASE_URL to postgresql+asyncpg://app:app@localhost:5432/app
— point it at a real reachable Postgres 16 (e.g. docker compose up db, or edit the URL) before
running the commands above; without it, both alembic upgrade head and main.py crash with a
pydantic ValidationError. AUTH_JWT_SECRET is required and has no default — set it to at least 32
random bytes before anything will start; the placeholder in .env.example is refused. Generate one with
python -c 'import secrets; print(secrets.token_urlsafe(48))'.
Frontend (from frontend/, requires Node 22 exactly — engine-strict refuses any other major;
needs backend/openapi.json present, which is committed):
npm ci
cp .env.example .env.local
npm run devBackend (backend/) |
Frontend (frontend/) |
|
|---|---|---|
| Test | uv run pytest -n 4 |
npm run test |
| Lint | uv run ruff check . |
npm run lint |
| Format check | uv run ruff format --check . |
npm run format |
| Typecheck | uv run mypy app |
npm run typecheck |
| Build/verify | uv run alembic check |
npm run build |
Run the backend suite with DATABASE_URL set: without it the integration tier skips silently
and the suite still exits 0 (see CONTRIBUTING.md). -n 4 gives each
pytest-xdist worker its own migrated database. scripts/audit-deps.sh --strict scans every
lockfile, committed secrets and the Docker/compose/workflow configuration (add --images to scan
the built images too). .githooks/pre-commit (enable with git config core.hooksPath .githooks)
runs format and lint on the staged files before every commit; the suites run in CI.
Backend: router -> service -> repository -> model, with the transaction boundary centralized in
app/core/transactions.py and enforced by AST-parsing architecture tests. Frontend:
app -> features -> components/ui -> lib, enforced by eslint-plugin-boundaries, with a strict
server/client split (RSC by default; 'use client' only where genuinely needed).
Full write-ups, including the response envelopes, the error contract, the schema-per-bounded- context Alembic setup, and the enforcement mechanisms themselves:
docs/architecture/backend.mddocs/architecture/frontend.mddocs/development/backend.md— PR checklistdocs/development/frontend.md— PR checklistdocs/development/dependencies.md— scanning and updating dependenciesdocs/development/security-audit.md— running the security-audit skilldocs/deploy/vps.md— the optional single-VPS production deploy
Agent-facing rules live in two places: AGENTS.md holds what every session needs
(exact versions, commands, env vars, the always-on rules and a Rules index), and
.agents/rules/ holds path-scoped rules that load only when matching files are
touched. Every CLAUDE.md is a one-line @AGENTS.md pointer, so both Claude Code and Codex read
the same text.
This template ships a small pipeline for agent-driven development, maintained once under
.agents/: path-scoped rules in .agents/rules/, skills in .agents/skills/, reviewer rubrics in
.agents/agents/, hook scripts in .agents/hooks/ and scaffold generators in .agents/scaffold/.
Claude Code reaches them through the .claude/rules and .claude/skills symlinks and thin
.claude/agents/*.md files (/name commands); Codex reads .agents/skills/ natively ($name
commands) and its .codex/agents/*.toml point at the same rubrics. .agents/skills/fastapi is a
symlink into the fastapi package's own bundled skill, so it resolves only after uv sync has
created backend/.venv. Ask either harness to delegate a
review to backend-reviewer, frontend-reviewer, or uncle-bob by name.
| Claude / Codex | Purpose |
|---|---|
/groom <idea> / $groom <idea> |
Turns a product idea into a reviewed PRD under docs/prds/ and the GitHub issues that implement it. |
/task #123 / $task #123 |
Takes one issue through a worktree, implementation, checks, review, QA, and a PR. |
/orchestrate --label backend / $orchestrate --label backend |
Runs an eligible backlog with bounded concurrency, dependency ordering, and per-task isolation. |
backend-reviewer agent |
Reviews a backend diff against the layering, migration, DI, auth, and error-contract rules, running the real checks as evidence. |
frontend-reviewer agent |
Reviews a frontend diff against import boundaries, server/client rules, auth, and forms, running the real checks as evidence. |
uncle-bob agent |
Clean-code/design review — naming, function size, duplication, and the no-comments rule — across both stacks. |
/scaffold-crud / $scaffold-crud |
Generates a rule-compliant backend slice and frontend feature from .agents/scaffold/. |
/security-audit / $security-audit |
Cloudflare's source-first security audit, scoped and budgeted (see docs/development/security-audit.md). |
/deploy / $deploy |
Ships a main commit to the optional VPS deploy; human-invoked only. |
AGENTS.md is the shared project guide, and CLAUDE.md points to it. The Claude
workflow files hold the detailed repository contracts; Codex skills are short
adapters for their host-specific commands. Review criteria stay in the Claude
Markdown rubrics and are loaded by the Codex reviewer agents at review time.
Update a shared rule in its maintained file, then check whether the small Codex
adapter needs a matching change. Run the agent contract tests after either side
changes.
The loop is idea -> PRD -> issues -> PRs. A PRD in docs/prds/ holds the reasoning and is
reviewed as a diff like any other file; a GitHub issue holds one mergeable unit of work and closes
with its PR. The issue forms in .github/ISSUE_TEMPLATE/ are not decoration — /task parses
their sections, and a test fails if a form and the parser ever disagree.
Start here:
git config core.hooksPath .githooks
scripts/sync-labels.shSee CONTRIBUTING.md for the contribution standards that apply to humans and
agents alike, docs/prds/README.md for why PRDs are files and not
issues, and AGENTS.md for the full index, exact commands, and mechanical recipes
for extending either stack.
MIT — see LICENSE. Vendored third-party material keeps its own license; see
THIRD_PARTY_NOTICES.md.
Security issues: please report them privately, as described in SECURITY.md.