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:
2026-05-03 18:04:45 +02:00
parent 2f9fc8076d
commit 5f0ab40816
17 changed files with 517 additions and 48 deletions

View 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`.