Lukas
5f0ab40816
- Extract ADR documents for architectural decisions (SQLite, FastAPI, React, APScheduler, Scheduler) - Refactor setup.py: improve code structure and readability - Add IP validation utilities with test coverage - Update frontend components (BanTable, HistoryPage) - Add pre-commit hooks and CONTRIBUTING.md - Add .editorconfig for consistent coding standards
1.9 KiB
1.9 KiB
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 defroute 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.