refactor(backend): clean up models setup, improve ip utils, add adr docs
- 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
This commit is contained in:
45
Docs/adr/ADR-002-FastAPI-Backend-Framework.md
Normal file
45
Docs/adr/ADR-002-FastAPI-Backend-Framework.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user