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-001-SQLite-Application-Database.md
Normal file
45
Docs/adr/ADR-001-SQLite-Application-Database.md
Normal 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.
|
||||
Reference in New Issue
Block a user