# ADR-002: FastAPI over Django

## Status
Accepted

## Context
The backend requires a Python async web framework with strong typing, validation,
and OpenAPI support.

## Decision
Use **FastAPI** as the backend framework.

## Rationale

### Why FastAPI over Django?
- **Async-first:** FastAPI is built on Starlette with native `async def` route
  handlers. Django's ORM and request handling are synchronous, requiring thread
  pools for I/O-bound work.
- **Modern Python 3.12+:** FastAPI embraces modern Python idioms — type annotations,
  structural pattern matching, dataclasses. Django maintains broad Python 3.8+
  compatibility and shows its age.
- **Pydantic v2 integration:** FastAPI natively uses Pydantic for request/response
  validation. Automatic OpenAPI schema generation from Pydantic models is seamless.
- **Dependency injection:** FastAPI's `Depends()` system provides a lightweight,
  explicit DI pattern without a separate container library.
- **Performance:** FastAPI + Uvicorn consistently benchmarks as one of the fastest
  Python web frameworks, comparable to Node.js and Go for JSON APIs.

### Why not Django?
- Django's synchronous ORM creates thread-pool bottlenecks with SQLite.
- Django's "batteries-included" philosophy is overkill for BanGUI's scope.
  We need REST endpoints and background tasks, not a full CMS.
- Less flexible dependency injection — Django's middleware and view system is
  less composable than FastAPI's routing layers.

### Trade-offs
- **Smaller ecosystem:** Django has decades of third-party packages. FastAPI's
  ecosystem is younger but covers BanGUI's needs (structlog, aiosqlite, APScheduler,
  aiohttp) completely.
- **No built-in admin UI:** BanGUI is its own admin UI; Django's admin is irrelevant.

## Consequences
- FastAPI routes are defined in `app/routers/`.
- Request/response models live in `app/models/`.
- Dependency injection via `app/dependencies.py`.