Skip to content
Public template

About

FastAPI + Next.js fullstack template with auth, users, security hardening, E2E tests and agent tooling

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

fullstack-template

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.

What's in the box

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

Quickstart — Docker Compose

Requires Docker with Compose v2+. From the repo root:

AUTH_JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))") docker compose up --build

AUTH_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]

Quickstart — local development

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 dev

Tests and checks

Backend (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.

Architecture

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:

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.

Agent tooling

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.sh

See 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.

License

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.

About

FastAPI + Next.js fullstack template with auth, users, security hardening, E2E tests and agent tooling

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages