FastAPI Agent Blueprint

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 user domain 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" }

→ Create a user
{ "success": true, "data": { "id": 1, "username": "alice",
                             "fullName": "Alice Liddell", ... } }

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

→ Update the user    → Delete the user
→ Done. Swagger UI: http://127.0.0.1:8001/docs-swagger

• Swagger: http://127.0.0.1:8001/docs-swagger
• Admin UI: http://127.0.0.1:8001/admin (admin / admin)
• Full walkthrough: docs/quickstart.md
• Real dev stack (PostgreSQL + migrations): docs/reference.md

• Write domain logic once, expose it everywhere. HTTP (FastAPI) + worker (Taskiq) + admin (NiceGUI) share a single domain layer. MCP server is on the roadmap.
• Zero-boilerplate CRUD. Inherit BaseRepository[DTO] and BaseService[Create, Update, DTO] to get 7 async methods — including paginated list with QueryFilter — for free.
• Auto domain discovery. Drop a folder into src/{name}/, it auto-registers. No container edits, no bootstrap edits.
• Pluggable infra, env-switchable. PostgreSQL / MySQL / SQLite · DynamoDB · S3 / MinIO · S3 Vectors · SQS / RabbitMQ / InMemory · OpenAI / Bedrock for both LLM and embeddings.
• Architecture enforced at commit time. A pre-commit hook blocks Domain → Infrastructure imports so the DDD contract cannot rot.
• AI-native workflows. 14 Claude Code skills + 15 Codex CLI skills sharing one AGENTS.md rules file — scaffold a domain, add a route, or audit architecture with a single command.

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.

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.

Same flow, different base classes:

One business logic, multiple surfaces:

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.

Both Claude Code and OpenAI Codex CLI are first-class. They share one rules file (AGENTS.md) and one workflow reference layer (docs/ai/shared/); tool-specific harnesses layer on top.

/onboard            # adaptive walkthrough — beginner to advanced
/new-domain product # scaffolds 15 source files + 25 __init__.py + 4 tests
/add-api "add GET /product/top-selling to product"
/review-architecture product

Swap / for $ if you are on Codex CLI. Prefer no harness at all? The "Your first domain in 10 minutes" tutorial walks both paths side-by-side — one harness command vs. 9 Python files — and ends with a passing pytest run plus curl against the real server.

Selected skills (all available in both tools): onboard, new-domain, add-api, add-worker-task, add-admin-page, review-architecture, security-review, review-pr, plan-feature, fix-bug. Full table and setup guide: docs/ai-development.md.

• MCP server interface — expose domain services as agent tools via FastMCP (#18)
• pgvector — additional vector backend alongside S3 Vectors (#11)
• JWT authentication (#4) · Structured logging (#9)

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.

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