README.md

August 6, 2026 · View on GitHub

FastAPI Agent Blueprint

FastAPI backend blueprint for AI agent applications.
DDD domains · SQLAlchemy/Alembic · Taskiq workers · admin UI · RAG infrastructure · Claude/Codex collaboration harness.

60s Quickstart · Why · AI Collaboration · Comparison · Architecture · 한국어

Try it in 60 seconds

No Docker, no PostgreSQL, no cloud credentials — SQLite + in-memory broker.

git clone https://github.com/Mr-DooSun/fastapi-agent-blueprint.git
cd fastapi-agent-blueprint
make setup        # one-time: venv + deps via uv
make quickstart   # FastAPI on :8001, SQLite schema auto-created

In a second terminal, make demo exercises the auth + user domains across both token realms (customer register → seed a demo admin → admin login → user CRUD → refresh → logout) and make demo-rag exercises the docs domain (end-to-end RAG: upload → chunk → embed → retrieve → answer with citations, zero credentials):

→ Health check
{ "status": "ok" }

→ Register
{ "success": true, "data": { "accessToken": "...", "refreshToken": "..." } }

→ Create a user
{ "success": true, "data": { "id": 2, "username": "bob", ... } }

→ List users (page=1, pageSize=10)
{ "data": [ { "id": 1, "username": "alice" }, { "id": 2, "username": "bob" } ],
  "pagination": { "currentPage": 1, "totalItems": 2, "hasNext": false } }

→ Update the user    → Delete the user
→ Refresh token      → Logout
→ Done. API docs: http://127.0.0.1:8001/docs

API docs: http://127.0.0.1:8001/docs (Stoplight Elements & Scalar recommended; spec download + frontend handoff link on the same page)
Admin UI: http://127.0.0.1:8001/admin (admin / admin)
Full walkthrough: docs/quickstart.md
Frontend handoff: docs/frontend-handoff.md
Real dev stack (PostgreSQL + migrations): docs/reference.md

Platform in action

Clone → quickstart → CRUD → JWT auth → background worker → RAG query:

make quickstart && make demo && make demo-rag

API demo: health check → register → JWT → admin realm → user CRUD

Full integration walkthrough (auth · RBAC · worker · admin · RAG · OTEL): docs/canonical-demo.md

Why this blueprint

Production rigor

DDD layers (4-tier) — Interface · Domain · Infrastructure · Application, enforced by pre-commit import guard
Zero-boilerplate CRUD — 8 async methods via BaseService + BaseRepository, paginated list with QueryFilter included
Auto domain discovery — drop a folder into src/{name}/, it auto-registers. No container edits, no bootstrap edits
Agent backend surfaces — REST API, async worker, admin UI, and a planned MCP interface over the same domain logic
Pluggable infra — PostgreSQL / MySQL / SQLite · DynamoDB · S3 / MinIO · S3 Vectors · SQS / RabbitMQ · OpenAI / Bedrock
OpenTelemetry — [otel] extra, OTEL_ENABLED env flag, Jaeger/Tempo/Phoenix recipe
Error notifications — optional Slack/Discord webhook alerts from the exception handlers and from worker task failures, severity + cooldown gated, with optional per-severity channel routing (runbook)
JWT + RBAC — HS256 auth domain, DB-backed refresh rotation, User.role admin gating
AI Usage Ledger — per-call LLM accounting, ai_usage domain, admin + API surfaces
Taskiq smart retry — task-scoped structured logging, permanent-aware retry policy
Frontend handoff — OpenAPI download, Bruno/Postman/Hey API/Orval recipes, JWT flow, camelCase contract (docs/frontend-handoff.md)

AI-assisted acceleration

Claude/Codex collaboration harness — shared AGENTS.md, mirrored skills, and hook-backed workflow reminders
/new-domain order or $new-domain order scaffolds 44 files (15 source + 25 __init__.py + 4 tests) in one command
15 Claude Code + 15 Codex CLI skills sharing the same architecture and review rules
AI-assisted development (AIDD) — humans keep product judgment; agents follow repeatable domain, test, review, and drift-check workflows
Full setup: docs/ai-development.md
Manual path: docs/tutorial/first-domain.md (Path B)

/new-domain order → 44 files scaffolded → tests pass

Works as a normal FastAPI blueprint. With Claude Code or Codex CLI, the same production workflow becomes AI-assisted and repeatable.

AI collaboration harness

Most templates stop at generated files. This blueprint also ships the collaboration layer that keeps AI coding agents useful after the first scaffold:

Shared source of truth — AGENTS.md defines the architecture, DTO rules, logging rules, security constraints, and default coding flow.
Claude Code + Codex parity — tool-specific harnesses point back to the same shared rules instead of drifting into separate playbooks.
Repo-local skills — domain scaffolding, API work, admin pages, worker tasks, migrations, tests, architecture review, security review, and guideline sync.
Governed changes — pre-commit checks, import guards, language policy, and review workflows catch architecture drift before it becomes team debt.

The result is a backend starter that can be used by hand, then accelerated by AI tools without asking every contributor to remember the whole architecture from scratch.

How it compares

Feature	FastAPI Agent Blueprint	tiangolo/full-stack	s3rius/template	teamhide/boilerplate
Zero-boilerplate CRUD (8 methods)	Yes	No	No	No
Auto domain discovery	Yes	No	No	No
Architecture enforcement (pre-commit)	Yes	No	No	No
AI workflow skills (Claude + Codex)	15 + 15	0	0	0
Vector infrastructure (S3 Vectors)	Yes	No	No	No
Multi-interface (API + Worker + Admin + MCP)	3 + 1 planned	2	1	1
Architecture Decision Records	29 active · 30 archived	0	0	0
Type-safe generics across layers	Yes	Partial	Partial	No
IoC container DI	Yes	No	No	No

Full comparison including Litestar, Robyn, cookiecutter, and adoption paths: docs/comparison.md

AI use case: document QA (`src/docs/`)

The blueprint ships a worked RAG example — upload documents, ask questions, get structured answers with citations. It proves the building blocks (vectors, embeddings, LLM agent, worker, admin) compose end-to-end.

make quickstart   # terminal 1
make demo-rag     # terminal 2 — seeds 3 docs, runs a query

POST /v1/docs/documents   # chunk → embed → upsert
POST /v1/docs/query       # embed question → top-k retrieval → agent answer
GET  /admin/docs          # browse + query playground

Under the hood, the RAG orchestration is a reusable _core pattern (ADR 040), not a domain. src/docs/ is one consumer; future AI domains (support_bot, product_qa) inject the same RagPipeline instead of duplicating chunking + retrieval code:

# src/_core/domain/services/rag_pipeline.py
class RagPipeline(Generic[TChunk]):
    async def answer(self, question, top_k=5, filters=None) -> tuple[QueryAnswer, list[TChunk]]:
        ...  # embed → vector_store.search → answer_agent.answer

Zero-config path uses a stub embedder (keyword bag-of-words) and stub answer agent (templated response from retrieved chunks), both in src/_core/infrastructure/rag/. Set EMBEDDING_PROVIDER + LLM_PROVIDER in .env to swap in real providers — the pipeline is the same.

Architecture at a glance

Every domain under src/{domain}/ has four DDD layers. Arrows mean "depends on". Application (use cases) is optional — the dotted line is the common path for simple CRUD (Router → Service directly).

flowchart LR
    subgraph domain["src/{domain}/  (4 DDD layers)"]
        I["Interface<br/>routers · admin · worker · schemas"]
        A["Application<br/>use cases — optional"]
        D["Domain<br/>services · protocols · DTOs · value objects"]
        Inf["Infrastructure<br/>repositories · models · DI container"]
        I --> A
        A --> D
        Inf --> D
        I -. direct when no UseCase .-> D
    end

    Core["src/_core/<br/>Base classes · CoreContainer · shared VOs"]
    I --> Core
    A --> Core
    D --> Core
    Inf --> Core

    Other["Another domain"] -. via Protocol-based DIP .-> D

Layer	Role	Base class
Interface	Router · Request/Response · Admin · Worker task	—
Domain	Service · Protocol · DTO · Exceptions	`BaseService[CreateDTO, UpdateDTO, ReturnDTO]`
Infrastructure	Repository · Model · DI container	`BaseRepository[ReturnDTO]`
Application	UseCase — optional orchestrator	—

Full set of diagrams (Layer · Write · Read) plus RDB / DynamoDB / S3 Vectors variants lives in docs/ai/shared/architecture-diagrams.md. Non-Mermaid viewers: SVG exports.

Data flow — Write (`POST` / `PUT` / `DELETE`)

flowchart LR
    C[Client] -->|"HTTP + JSON"| R[Router]
    R -->|"Request schema"| S[Service]
    S -->|"entity"| Re["Repository<br/>BaseRepository[DTO]"]
    Re -->|"Model(**dto.model_dump())"| M[ORM Model]
    M -->|"SQLAlchemy"| DB[(Database)]

Request → Service directly when fields match (no intermediate DTO — ADR 004).
Model ↔ DTO conversion happens only inside the Repository.
Read flow is the mirror image; the Router strips sensitive fields on the way out.

Storage variants

Same flow, different base classes:

Storage	Service base	Repository / Store base	List return
RDB (default)	`BaseService[Create, Update, DTO]`	`BaseRepository[DTO]`	`(list[DTO], PaginationInfo)`
DynamoDB	`BaseDynamoService[…]`	`BaseDynamoRepository[DTO]`	`CursorPage[DTO]`
S3 Vectors	domain-specific	`BaseS3VectorStore[DTO]`	`VectorSearchResult[DTO]`

Interfaces

One business logic, multiple surfaces:

Interface	Tech	Status	Purpose
HTTP API	FastAPI	Stable	REST endpoints
Async worker	Taskiq + SQS / RabbitMQ / InMemory	Stable	Background jobs
Admin UI	NiceGUI	Stable	Auto-generated admin CRUD
MCP server	FastMCP	Planned (#18)	AI agent tool interface

Learn more

I want to…	Read
Spin it up and poke around	`docs/quickstart.md`
See everything work end-to-end (auth · RBAC · worker · RAG · OTEL)	`docs/canonical-demo.md`
Build a real domain, end-to-end	`docs/tutorial/first-domain.md`
See small, pattern-focused example apps	`examples/`
Understand the architecture in depth	`docs/ai/shared/architecture-diagrams.md` · `AGENTS.md`
Set up Claude Code or Codex CLI	`docs/ai-development.md`
Add a domain by hand (no AI tools)	`docs/tutorial/first-domain.md` (Path B)
Adopt into an existing FastAPI project	`docs/adoption.md`
Check Python / FastAPI / tool version support	`docs/compatibility.md`
See detailed env vars, tech stack, project tree	`docs/reference.md`
Understand why a decision was made	ADR index (29 active · 30 archived)
Follow what's next	Roadmap · issue tracker

Roadmap

MCP server interface — expose domain services as agent tools via FastMCP (#18)
pgvector — additional vector backend alongside S3 Vectors (#11)

See full roadmap · open issues

Contributing

See CONTRIBUTING.md for dev setup, coding guidelines, and the PR workflow. Newcomers — check the good first issue label; the small apps tracked under examples/ are a low-friction place to land your first PR.

License

MIT — free for commercial use, modification, and distribution.