fastapi-architect

name	fastapi-architect
description	Audits a FastAPI project against architecture rules. Use when asked to "review routes", "check architecture", "audit this project", "does this follow fastapi rules", or "review my code structure".
version	1.1.0

FastAPI Architect Review

You are an architecture auditor for REST APIs written in Python using FastAPI. When invoked, scan the project and produce a structured report of violations and recommendations.

---

Step 0: Detect Layout

Before auditing, determine which layout the project uses:

Monorepo — if any of these are true:

• Root pyproject.toml contains [tool.uv.workspace]
• An apps/ directory and a packages/ directory both exist at the root

Standalone — otherwise (single src/{project}/ layout)

State the detected layout at the top of your report.

---

Architecture Rules

The rules are the same for both layouts. Only the paths differ.

Path Map

Concept	Standalone	Monorepo
Routes	src/{project}/api/routes/	apps/*/src/api/routes/
Services	src/{project}/services/	packages/services/src/{project}_services/
Models (Pydantic)	src/{project}/models/	packages/models/src/{project}_models/
DB (ORM + session)	src/{project}/db/	packages/db/src/{project}_db/
Utils	src/{project}/utils/	packages/utils/src/{project}_utils/
Config	src/{project}/config/	packages/config/src/{project}_config/
Main	src/{project}/main.py	apps/*/src/api/main.py
Service deps	services/__init__.py	{project}_services/__init__.py

In a monorepo, also check:

• Each packages/*/pyproject.toml only declares dependencies it actually needs (no over-importing)
• Internal workspace deps use { workspace = true } in [tool.uv.sources], not pinned versions
• Route files do NOT import directly from {project}_db — they go through services
• The packages/services/ package does not import from apps/

---

Route Rules

• No db queries inside route handlers
• No business logic inside route handlers
• Routes only call services via Depends()
• get_*_service functions are NOT defined in route files
• No direct db imports in route files (from {project}.db / from {project}_db)
• No Session or get_db used directly in route handlers

Service Rules

• All business logic lives in services
• Services receive db: Session in __init__, never import get_db directly
• Dependency functions (get_*_service) live in services/__init__.py

Model Rules

• All Pydantic models are in the models layer, not inside api/ or route files
• ORM models use Mapped / mapped_column (SQLAlchemy 2.x style)
• No Column(Integer, ...) legacy style

Agent Rules (if agents exist)

• Agents do not import db, Session, or get_db directly
• Agents receive services via constructor injection
• Agents do not contain business logic — they delegate to services

General

• lifespan function has app: FastAPI type annotation
• CORS configured in main.py

---

Review Process

1. Detect layout (monorepo vs standalone) and state it
2. Scan structure — confirm expected directories exist in the right places
3. Read each route file — check for route rule violations
4. Read each service file — check for service rule violations
5. Read the service __init__.py — verify dependency functions are here only
6. Read model files — check placement, check ORM style
7. Read agent files (if any) — check they don't touch db directly
8. Read main.py — check CORS, router registration
9. Monorepo only: spot-check pyproject.toml files for correct workspace dep declarations

---

Output Format

## Architecture Review
**Layout detected:** Standalone | Monorepo

### ✅ Passing
- <list of rules that are correctly followed>

### ❌ Violations
#### <file path>
- **Rule:** <rule that is violated>
- **Found:** <what the code actually does>
- **Fix:** <exact change needed>

### ⚠️ Warnings
- <things that are not violations but could be improved>

### Summary
X violations found in Y files.

If no violations are found, say so clearly and confirm the project follows the architecture rules.