Fastapi Agent Blueprint

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 (JWT register → 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

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
• 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
• 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

• /new-domain order scaffolds 44 files (15 source + 25 __init__.py + 4 tests) in one command
• 14 Claude Code + 14 Codex CLI skills sharing one AGENTS.md rules file
• Both tools supported equally — swap / for $ to switch between them
• Full setup: docs/ai-development.md
• Manual path: docs/tutorial/first-domain.md (Path B)

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

How it compares

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

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:

Interfaces

One business logic, multiple surfaces:

Learn more

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.