Fastapi Agent Blueprint
FastAPI backend blueprint for AI agent apps: DDD, SQLAlchemy, Taskiq, admin UI, RAG infra, and Claude/Codex collaboration harness.
Install / Use
npx skills add Mr-DooSun/fastapi-agent-blueprintInstalls into whichever agent you are using.
Quality Score
Category
Development & EngineeringSupported Platforms
README
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
Full integration walkthrough (auth · RBAC · worker · admin · RAG · OTEL): docs/canonical-demo.md
Why this blueprint
<table> <tr> <td width="60%" valign="top">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 withQueryFilterincluded - 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_ENABLEDenv 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.roleadmin gating - AI Usage Ledger — per-call LLM accounting,
ai_usagedomain, 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 orderor$new-domain orderscaffolds 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)
</td> </tr> </table>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.mddefines 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
Related Skills
node-connect
385.5kDiagnose OpenClaw Android, iOS, or macOS node pairing, QR/setup code, route, auth, and connection failures.
python-debugpy
385.5kDebug Python with pdb, breakpoint(), post-mortem inspection, and debugpy remote attach.
skill-creator
385.5kCreate, edit, audit, tidy, validate, or restructure AgentSkills and SKILL.md files.
claude-opus-4-5-migration
140.7kMigrate prompts and code from Claude Sonnet 4.0, Sonnet 4.5, or Opus 4.1 to Opus 4.5
