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-001: SQLite as the Application Database
## Status
Accepted
## Context
BanGUI needs a database to store application state: configuration, session records,
blocklist sources, import logs, and ban history archives.
## Decision
Use **SQLite** (via `aiosqlite`) as BanGUI's application database, persisted to a
volume mounted from the host or a named Docker volume.
## Rationale
### Why SQLite over PostgreSQL?
- **Zero-infrastructure:** No separate DB server process, no connection pooling,
no credentials to manage. Ships in the Docker container with no additional
configuration.
- **Fail2ban-compatible:** The fail2ban database itself is SQLite. BanGUI already
depends on SQLite; adding a second database engine would increase operational
complexity for no benefit.
- **Single-instance deployment:** BanGUI runs as a single service with one
background scheduler (enforced by `BANGUI_WORKERS=1`). Horizontal scaling is not
a design goal.
- **Async I/O:** `aiosqlite` provides full async support, avoiding blocking I/O in
the FastAPI async request handlers.
### Why not PostgreSQL?
- Requires a separate service or sidecar container.
- Adds connection overhead (TCP, connection pools, auth).
- Over-engineered for a single-instance web app.
### Trade-offs
- **Not suitable for multi-worker deployments.** SQLite's file-level locking means
only one process can write at a time. This is explicitly enforced:
`BANGUI_WORKERS=1` is validated at startup, and `scheduler_lock` prevents
duplicate schedulers in restarts.
- For future multi-instance deployments, BanGUI would need to migrate to
PostgreSQL or add a distributed lock layer (Redis + job store).
## Consequences
- Application database is a single file (`bangui.db`) in the container's data volume.
- Backup is a file copy. No `pg_dump` equivalent needed.
- Schema migrations managed via `app/startup.py` startup DAG.