# BanGUI — Architecture

This document describes the system architecture of BanGUI, a web application for monitoring, managing, and configuring fail2ban. It defines every major component, module, and data flow so that any developer can understand how the pieces fit together before writing code.

---

## 1. High-Level Overview

BanGUI is a two-tier web application with a clear separation between frontend and backend, connected through a RESTful JSON API.

```
┌──────────────────────────────────────────────────────────────────┐
│                          Browser                                 │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │                   Frontend (React + Fluent UI)             │  │
│  │  TypeScript · Vite · Single-Page Application               │  │
│  └──────────────────────────┬─────────────────────────────────┘  │
└─────────────────────────────┼────────────────────────────────────┘
                              │  HTTP / JSON (REST API)
┌─────────────────────────────┼────────────────────────────────────┐
│                          Server                                  │
│  ┌──────────────────────────┴─────────────────────────────────┐  │
│  │                   Backend (FastAPI)                        │  │
│  │  Python 3.12+ · Async · Pydantic v2 · structlog            │  │
│  └─────┬──────────────┬──────────────┬────────────────────────┘  │
│        │              │              │                           │
│  ┌─────┴─────┐  ┌─────┴─────┐  ┌────┴─────┐                      │
│  │  SQLite   │  │ fail2ban  │  │ External │                      │
│  │  (App DB) │  │  (Socket) │  │   APIs   │                      │
│  └───────────┘  └───────────┘  └──────────┘                      │
└──────────────────────────────────────────────────────────────────┘
```

### Component Summary

| Component | Technology | Purpose |
|---|---|---|
| **Frontend** | TypeScript, React, Fluent UI v9, Vite | User interface — displays data, captures user input, communicates with the backend API |
| **Backend** | Python 3.12+, FastAPI, Pydantic v2, aiosqlite | Business logic, data persistence, fail2ban communication, scheduling |
| **Application Database** | SQLite (via aiosqlite) | Stores BanGUI's own data: configuration, session state, blocklist sources, import logs |
| **fail2ban** | Unix domain socket | The monitored service — BanGUI reads status, issues commands, and reads the fail2ban database |
| **MaxMind GeoLite2** | Offline MMDB file (mounted into container) | IP geolocation (primary resolver) — local, encrypted |
| **External APIs** | HTTP (via aiohttp) | Blocklist downloads; IP geolocation fallback (only if MMDB unavailable and HTTP fallback enabled) |

---

## 2. Backend Architecture

The backend follows a **layered architecture** with strict separation of concerns. Dependencies flow inward: routers depend on services, services depend on repositories — never the reverse.

```
                ┌─────────────────────────────────┐
                │        FastAPI Application       │
                │          (main.py)               │
                └──────────┬──────────────────────-┘
                           │
          ┌────────────────┼────────────────┐
          │                │                │
    ┌─────┴──────┐  ┌─────┴──────┐  ┌──────┴──────┐
    │  Routers   │  │   Tasks    │  │   Config    │
    │  (HTTP)    │  │ (Scheduled)│  │ (Settings)  │
    └─────┬──────┘  └─────┬──────┘  └─────────────┘
          │               │
    ┌─────┴───────────────┴──────┐
    │         Services           │
    │     (Business Logic)       │
    └─────┬──────────────┬───────┘
          │              │
    ┌─────┴──────┐ ┌─────┴──────┐
    │Repositories│ │  External  │
    │ (Database) │ │  Clients   │
    └─────┬──────┘ └─────┬──────┘
          │              │
    ┌─────┴──────┐ ┌─────┴──────┐
    │  SQLite    │ │fail2ban /  │
    │            │ │HTTP APIs   │
    └────────────┘ └────────────┘
```

### 2.1 Project Structure

```
backend/
├── app/
│   ├── __init__.py
│   ├── `main.py`                # FastAPI app factory, lifespan, exception handlers
│   ├── `config.py`              # Pydantic settings (env vars, .env loading)
│   ├── `db.py`                  # Database connection and initialization
│   ├── `exceptions.py`          # Shared domain exception classes; all services and routers import from here
│   ├── `dependencies.py`        # FastAPI Depends() providers (DB, services, auth)
│   ├── `models/`                # Pydantic schemas
│   │   ├── auth.py            #   Login request/response, session models
│   │   ├── ban.py             #   Ban request/response/domain models
│   │   ├── jail.py            #   Jail request/response/domain models
│   │   ├── config.py          #   Configuration view/edit models
│   │   ├── blocklist.py       #   Blocklist source/import models
│   │   ├── history.py         #   Ban history models
│   │   ├── server.py          #   Server status, health check models
│   │   └── setup.py           #   Setup wizard models
│   ├── routers/               # FastAPI routers (HTTP layer only)
│   │   ├── auth.py            #   POST /api/auth/login, POST /api/auth/logout
│   │   ├── setup.py           #   POST /api/setup (first-run configuration)
│   │   ├── dashboard.py       #   GET /api/dashboard/status, GET /api/dashboard/bans
│   │   ├── jails.py           #   CRUD + controls for jails
│   │   ├── bans.py            #   Ban/unban actions, currently banned list
│   │   ├── config.py          #   View/edit fail2ban configuration
│   │   ├── history.py         #   Historical ban queries
│   │   ├── blocklist.py       #   Blocklist source management, manual import trigger
│   │   ├── geo.py             #   IP geolocation and lookup
│   │   └── server.py          #   Server settings (log level, DB purge, etc.)
│   ├── services/              # Business logic (one service per domain)
│   │   ├── auth_service.py    #   Password verification, session creation/validation
│   │   ├── setup_service.py   #   First-run setup logic, configuration persistence
│   │   ├── jail_service.py    #   Jail listing, start/stop/reload, status aggregation
│   │   ├── ban_service.py     #   Ban/unban execution, currently-banned queries
│   │   ├── config_service.py  #   Read/write fail2ban config, regex validation
│   │   ├── config_file_service.py #   Shared config parsing and file-level operations
│   │   ├── raw_config_io_service.py #   Raw config file I/O wrapper
│   │   ├── jail_config_service.py #   jail config activation/deactivation logic
│   │   ├── filter_config_service.py #   filter config lifecycle management
│   │   ├── action_config_service.py #   action config lifecycle management
│   │   ├── log_service.py     #   Log preview and regex test operations
│   │   ├── fail2ban_metadata_service.py #   Resolve and cache the fail2ban SQLite DB path via the fail2ban socket
│   │   ├── history_service.py #   Historical ban queries, per-IP timeline
│   │   ├── blocklist_service.py # Orchestration: source CRUD, scheduling, import triggers
│   │   ├── blocklist_downloader.py #   HTTP download with retry logic
│   │   ├── blocklist_parser.py #   Parse and validate IP addresses
│   │   ├── blocklist_ban_executor.py #   Ban execution with error handling
│   │   ├── blocklist_import_workflow.py #   Import orchestration (coordinates components)
│   │   ├── geo_service.py     #   IP-to-country resolution, ASN/RIR lookup
│   │   ├── server_service.py  #   Server settings, log management, DB purge
│   │   └── health_service.py  #   fail2ban connectivity checks, version detection
│   ├── repositories/          # Data access layer (raw queries only)
│   │   ├── settings_repo.py   #   App configuration CRUD in SQLite
│   │   ├── session_repo.py    #   Session storage and lookup
│   │   ├── blocklist_repo.py  #   Blocklist sources and import log persistence│  │   ├── fail2ban_db_repo.py #   fail2ban SQLite ban history read operations
│  │   ├── geo_cache_repo.py  #   IP geolocation cache persistence│   │   └── import_log_repo.py #   Import run history records
│   ├── tasks/                 # APScheduler background jobs
│   │   ├── blocklist_import.py#   Scheduled blocklist download and application
│   │   ├── geo_cache_flush.py #   Periodic geo cache persistence (dirty-set flush to SQLite)│  │   ├── geo_cache_cleanup.py #   Periodic purge of stale geo cache entries
│   │   ├── geo_re_resolve.py  #   Periodic re-resolution of stale geo cache records│   │   └── health_check.py   #   Periodic fail2ban connectivity probe
│   └── utils/                 # Helpers, constants, shared types
│       ├── fail2ban_client.py #   Async wrapper around the fail2ban socket protocol
│       ├── fail2ban_response.py #   Canonical response parsing: ok(), to_dict(), ensure_list(), is_not_found_error()
│       ├── fail2ban_db_utils.py #   fail2ban database query helpers
│       ├── ip_utils.py        #   IP/CIDR validation and normalisation
│       ├── time_utils.py      #   Timezone-aware datetime helpers
│       ├── config_file_utils.py #   fail2ban config file I/O
│       ├── conffile_parser.py #   fail2ban config file parser/serializer
│       ├── config_parser.py   #   Structured config object parser
│       ├── config_writer.py   #   Atomic config file write operations
│       ├── jail_config.py     #   Jail config helper
│       └── constants.py       #   Shared constants (default paths, limits, etc.)
├── tests/
│   ├── conftest.py            # Shared fixtures (test app, client, mock DB)
│   ├── test_routers/          # One test file per router
│   ├── test_services/         # One test file per service
│   └── test_repositories/     # One test file per repository
├── pyproject.toml
└── .env.example
```

### 2.2 Module Purposes

#### Routers (`app/routers/`)

The HTTP interface layer. Each router maps URL paths to handler functions. Routers parse and validate incoming requests using Pydantic models, delegate all logic to services, and return typed responses. They contain **zero business logic**.

| Router | Prefix | Purpose |
|---|---|---|
| `auth.py` | `/api/auth` | Login (password check), logout, session validation |
| `setup.py` | `/api/setup` | First-run wizard — save initial configuration |
| `dashboard.py` | `/api/dashboard` | Server status bar data, recent bans for the dashboard |
| `jails.py` | `/api/jails` | List jails, jail detail, start/stop/reload/idle controls |
| `bans.py` | `/api/bans` | Ban an IP, unban an IP, unban all, list currently banned IPs |
| `config.py` | `/api/config` | Read and write fail2ban jail/filter/server configuration via the socket; also serves the fail2ban log tail and service status for the Log tab |
| `file_config.py` | `/api/config` | Read and write fail2ban config files on disk (jail.d/, filter.d/, action.d/) — list, get, and overwrite raw file contents, toggle jail enabled/disabled |
| `history.py` | `/api/history` | Query historical bans, per-IP timeline |
| `blocklist.py` | `/api/blocklists` | CRUD blocklist sources, trigger import, view import logs |
| `geo.py` | `/api/geo` | IP geolocation lookup, ASN and RIR data |
| `server.py` | `/api/server` | Log level, log target, DB path, purge age, flush logs |
| `health.py` | `/api/health` | fail2ban connectivity health check and status |

#### Services (`app/services`)

The business logic layer. Services orchestrate operations, enforce rules, and coordinate between repositories, the fail2ban client, and external APIs. Each service covers a single domain.

**Service Layer Responsibilities:**

Services **must be independent of HTTP concerns**. They work with domain models (DTOs), not response models. This ensures:
- Domain logic can evolve without affecting API shape
- Services are reusable across different frontends
- Testing is simpler (no mocking HTTP response types)
- Changes to endpoint responses don't require service changes

**Domain Models and Response Mapping:**

Services return **domain models** (e.g., `DomainActiveBanList`, `DomainBansByCountry`) that represent pure business logic. Response models (e.g., `ActiveBanListResponse`, `BansByCountryResponse`) are defined in `app/models/` and used only by routers.

Conversion happens at the **router boundary**:
1. Router calls service → receives domain model
2. Router calls mapper function to convert domain model → response model
3. Router returns response model to HTTP client

Example:
```python
# In ban_service.py
async def get_active_bans(...) -> DomainActiveBanList:
    """Service returns domain model (not HTTP-aware)."""
    ...

# In routers/bans.py (router boundary)
domain_result = await ban_service.get_active_bans(...)
return map_domain_active_ban_list_to_response(domain_result)
```

Mapper functions live in `app/mappers/` and are thin, mechanical translations between structures.

**Motivation:**
- The Fail2ban domain doesn't care about field names like `country_code` (snake_case) vs `countryCode` (camelCase)
- If the API needs pagination metadata added to the response, only the mapper changes
- If repositories change their output schema, only services need updating (routers are unaffected)
- Services can be tested with simple dataclasses; no need for Pydantic serialization overhead

| Service | Purpose |
|---|---|
| `auth_service.py` | Hashes and verifies the master password, creates and validates session tokens, enforces session expiry |
| `setup_service.py` | Validates setup input, persists initial configuration, ensures setup runs only once |
| `jail_service.py` | Retrieves jail list and details from fail2ban, aggregates metrics (banned count, failure count), sends start/stop/reload/idle commands |
| `ban_service.py` | Executes ban and unban commands via the fail2ban socket, queries the currently banned IP list, validates IPs before banning |
| `config_service.py` | Reads active jail and filter configuration from fail2ban, writes configuration changes, validates regex patterns, triggers reload; reads the fail2ban log file tail and queries service status for the Log tab |
| `file_config_service.py` | Reads and writes raw fail2ban config files on disk (jail.d/, filter.d/, action.d/); lists files, reads content, overwrites files, toggles enabled/disabled |
| `jail_config_service.py` | Discovers inactive jails by parsing jail.conf / jail.local / jail.d/*; writes .local overrides to activate/deactivate jails; triggers fail2ban reload; validates jail configurations |
| `filter_config_service.py` | Discovers available filters by scanning filter.d/; reads, creates, updates, and deletes filter definitions; assigns filters to jails |
| `action_config_service.py` | Discovers available actions by scanning action.d/; reads, creates, updates, and deletes action definitions; assigns actions to jails |
| `config_file_service.py` | Shared utilities for configuration parsing and manipulation: parses config files, validates names/IPs, manages atomic file writes, probes fail2ban socket |
| `raw_config_io_service.py` | Low-level file I/O for raw fail2ban config files |
| `fail2ban_metadata_service.py` | Resolves the fail2ban SQLite database path by querying the fail2ban socket and caches the result for reuse across services |
| `log_service.py` | Log preview and regex test operations (extracted from config_service) |
| `history_service.py` | Queries the fail2ban database for historical ban records, builds per-IP timelines, computes ban counts and repeat-offender flags, and syncs new records into BanGUI's archive table |
| `blocklist_service.py` | Orchestration layer for blocklist imports. Delegates to focused components: `BlocklistDownloader` (HTTP download with retry), `BlocklistParser` (IP validation), `BanExecutor` (fail2ban integration), and `BlocklistImportWorkflow` (orchestrates the flow). Maintains public API for source CRUD, preview, scheduling, and import triggers. |
| `geo_cache.py` | **GeoCache** class that encapsulates all IP geolocation caching: resolves IP addresses to country, ASN, and organization using a primary local MaxMind GeoLite2-Country database (if available) with optional HTTP fallback to ip-api.com (disabled by default for security). Maintains in-memory and persistent caches with negative cache support, and manages background re-resolution. Instantiated once at startup with allow_http_fallback flag and stored on `app.state.geo_cache` |
| `geo_service.py` | (Deprecated) Backward-compatibility wrappers that delegate to the `GeoCache` instance. Kept for compatibility with existing code. New code should use `GeoCache` directly or via dependency injection |
| `server_service.py` | Reads and writes fail2ban server-level settings (log level, log target, syslog socket, DB location, purge age) |
| `health_service.py` | Probes fail2ban socket connectivity, retrieves server version and global stats, reports online/offline status |

##### Blocklist Import Architecture

The blocklist import flow has been refactored to separate concerns into focused components:

```
blocklist_service.py (Public API)
    │
    ├─ import_source() ──┐
    │                    │
    └─ import_all()      ├──> BlocklistImportWorkflow (Orchestrator)
                         │         │
                         │         ├──> BlocklistDownloader
                         │         │       • HTTP GET with retry logic
                         │         │       • Exponential backoff (429, 5xx)
                         │         │       • Timeout handling
                         │         │
                         │         ├──> BlocklistParser
                         │         │       • Parse text to IP lines
                         │         │       • Validate IPv4/IPv6 addresses
                         │         │       • Skip CIDRs and malformed entries
                         │         │
                         │         ├──> BanExecutor
                         │         │       • Ban each IP via fail2ban socket
                         │         │       • Abort on JailNotFoundError
                         │         │       • Continue on individual ban failures
                         │         │
                         │         └──> Geo pre-warming
                         │               (optional batch lookup for newly banned IPs)
                         │
                         └──> Result logging (import_log_repo)
```

**Component Responsibilities:**

- **BlocklistDownloader**: Handles HTTP transport concerns (retries, timeouts, backoff)
- **BlocklistParser**: Handles parsing and validation logic (clean, testable, no I/O)
- **BanExecutor**: Handles fail2ban integration with error aggregation
- **BlocklistImportWorkflow**: Coordinates the flow, handles result aggregation and geo pre-warming
- **blocklist_service.py**: Maintains public API (source CRUD, scheduling, import triggers)

**Benefits of This Architecture:**

- Each component is independently testable with mock dependencies
- Error handling is clear: JailNotFoundError stops processing, JailOperationError continues
- Components can be evolved independently (e.g., replace HTTP client, add batch validation)
- Logging is contextual and tied to the appropriate layer
- Retry logic and transient error handling are isolated

#### DNS-Rebinding Protection

**The Vulnerability:**

A DNS-rebinding attack exploits a time-of-check-to-time-of-use (TOCTOU) window between when a blocklist URL is validated and when it is actually fetched:

1. User adds blocklist URL `http://attacker.com/blocklist.txt`
2. `blocklist_service.create_source()` calls `validate_blocklist_url()` which performs DNS resolution
3. `attacker.com` resolves to a public IP (attacker's real server) — validation passes ✓
4. Later, when `BlocklistDownloader` fetches the URL, the attacker's DNS server responds with `192.168.1.1`
5. The HTTP client connects to the private IP, potentially accessing internal services

**The Protection:**

BanGUI closes this window by adding a second DNS-rebinding check at **connection time**:

1. **Create-time validation** (`app/utils/ip_utils.py:validate_blocklist_url`): Confirms the URL resolves to a public IP when created
2. **Connection-time validation** (`app/services/dns_validated_connector.py`): Validates that all resolved IPs are public when the actual HTTP connection is made

The HTTP session is created with a custom **socket factory** that intercepts DNS resolution results before socket creation. If any resolved IP is private or reserved, the connection is rejected with a clear error.

**Implementation:**

- `app/services/dns_validated_connector.py`: Provides `create_dns_validated_socket_factory()` which returns a socket factory that validates IPs using `is_private_ip()`
- `app/startup.py:_create_http_session()`: Passes the socket factory to `aiohttp.TCPConnector`, protecting all HTTP requests globally
- All blocklist imports automatically inherit this protection through the shared session

**Protected IP Ranges:**

The validation blocks all RFC 1918 private ranges, loopback, link-local, ULA, multicast, and reserved addresses:
- IPv4: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `127.0.0.0/8`, `224.0.0.0/4`, `240.0.0.0/4`, `255.255.255.255/32`
- IPv6: `::1/128`, `fe80::/10`, `fc00::/7`, `ff00::/8`, and others (via `ipaddress.IPv6Address.is_private`, etc.)

**Reference:**

- [OWASP SSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html)
- Tests: `backend/tests/test_services/test_dns_validated_connector.py`

#### Startup DAG (`app/startup_dag.py`, `app/startup.py`)

The startup process is orchestrated by an explicit **Directed Acyclic Graph (DAG)** that defines all resource initialization stages, their dependencies, health checks, and rollback strategy. This replaces implicit ordering with explicit, documented prerequisites.

**Why This Exists:**

Previously, startup resources were created in a procedural sequence without documented dependencies. If a stage was reordered or a prerequisite was missed, initialization could fail in non-obvious ways. Partial failures could leave stale resources (open database connections, HTTP sessions, running schedulers) that prevented clean rollback.

**Startup Stages (in order):**

```
1. WORKER_MODE
   └─ Validates that BANGUI_WORKERS=1 (scheduler cannot run in multiple workers)

2. DATABASE
   ├─ Prerequisite: WORKER_MODE
   ├─ Creates database directory
   ├─ Initializes database schema
   ├─ Caches setup completion state
   └─ Loads persisted runtime settings

3. GEO_CACHE
   ├─ Prerequisite: DATABASE
   ├─ Loads IP geolocation cache from database
   ├─ Counts unresolved IPs
   ├─ Initializes MaxMind GeoLite2 database
   └─ Configures HTTP fallback (if enabled)

4. HTTP_SESSION
   ├─ Prerequisite: GEO_CACHE
   ├─ Creates aiohttp.ClientSession
   └─ Configures timeouts and connection limits

5. SCHEDULER
   ├─ Prerequisite: HTTP_SESSION
   ├─ Creates APScheduler AsyncIOScheduler
   └─ Starts the scheduler

6. TASKS
   ├─ Prerequisite: SCHEDULER
   ├─ Registers health_check task (fail2ban connectivity probe)
   ├─ Registers blocklist_import task (scheduled imports)
   ├─ Registers geo_cache_cleanup task (stale entry purge)
   ├─ Registers geo_cache_flush task (periodic persistence)
   ├─ Registers geo_re_resolve task (stale record re-resolution)
   ├─ Registers history_sync task (ban history sync)
   └─ Registers session_cleanup task (expired session purge)
```

**Failure Mode & Rollback:**

If any stage fails:

1. All completed stages are rolled back **in reverse order** (Tasks → Scheduler → HTTP_SESSION → GEO_CACHE → DATABASE → WORKER_MODE)
2. Each rollback suppresses exceptions to ensure all resources are cleaned up
3. Database connections are closed
4. HTTP sessions are closed
5. The scheduler is shut down
6. The application startup fails with a clear error message

**Health Checks:**

After all stages complete, a final health check verifies:
- All resources have initialized successfully
- Resources pass their individual health_check() methods
- No failures occurred during any stage

**Implementation:**

- **StartupDAG**: Orchestrates the entire flow, manages prerequisites, and handles failures
- **StartupStage**: Enum defining the 6 startup stages
- **StageDependency**: Defines stage metadata (description, prerequisites, rollback policy)
- **StartupContext**: Tracks registered resources, completed stages, and failure state
- **startup_shared_resources()**: Main entry point that builds and executes the DAG
- **_stage_*()**: Functions that implement each stage's initialization logic

**Example Usage in Tests:**

```python
# Test that a stage with missing prerequisites fails
dag = StartupDAG()
dag.register_stage(StartupStage.HTTP_SESSION, "Create HTTP session", 
                   prerequisites=frozenset([StartupStage.DATABASE]))
dag.register_stage(StartupStage.SCHEDULER, "Create scheduler")

async def http_session_func():
    return aiohttp.ClientSession()

# This will raise RuntimeError because DATABASE hasn't completed
await dag.execute_stage(StartupStage.HTTP_SESSION, http_session_func)
```

#### Mappers (`app/mappers/`)

The response mapping layer. Mappers convert domain models (returned by services) to response models (consumed by HTTP routers). This layer enforces the separation between business logic and API shape.

**Location:** `app/mappers/`

**Responsibilities:**
- Convert service domain models to API response models
- Mechanical, thin translation — no business logic
- Used exclusively at the router boundary

**Pattern:**

Each domain model has a corresponding mapper function:

```python
# Domain model (from service)
DomainActiveBan → map_domain_active_ban_to_response() → ActiveBan (response)

# Service returns domain models:
async def get_active_bans(...) -> DomainActiveBanList

# Router converts at the boundary:
domain_result = await ban_service.get_active_bans(...)
return map_domain_active_ban_list_to_response(domain_result)
```

**Why separate?**

When API requirements change (e.g., new field added, field renamed), only:
1. Response model in `app/models/` changes
2. Mapper function in `app/mappers/` updates
3. Routers stay the same
4. Services don't change

Without this layer, changes to API shape would require modifying services and their tests.

#### Repositories (`app/repositories/`)

The data access layer. Repositories execute raw SQL queries against the application SQLite database. They return plain data or domain models — they never raise HTTP exceptions or contain business logic.

| Repository | Purpose |
|---|---|
| `settings_repo.py` | CRUD operations for application settings (master password hash, DB path, fail2ban socket path, preferences) |
| `session_repo.py` | Store, retrieve, and delete session records for authentication |
| `blocklist_repo.py` | Persist blocklist source definitions (name, URL, enabled/disabled) |
| `fail2ban_db_repo.py` | Read historical ban records from the fail2ban SQLite database |
| `geo_cache_repo.py` | Persist and query IP geo resolution cache |
| `import_log_repo.py` | Record import run results (timestamp, source, IPs imported, errors) for the import log view |

Every repository in `app/repositories/` has a corresponding protocol in `app/repositories/protocols.py`, including `settings_repo.py` and `history_archive_repo.py`.

#### Models (`app/models/`)

Pydantic schemas that define data shapes and validation. Models are split into three categories per domain.

| Model file | Purpose |
|---|---|
| `auth.py` | Login/request and session models |
| `ban.py` | Ban creation and lookup models |
| `blocklist.py` | Blocklist source and import log models |
| `config.py` | Fail2ban config view/edit models |
| `file_config.py` | Raw config file read/write models |
| `geo.py` | Geo and ASN lookup models |
| `history.py` | Historical ban query and timeline models |
| `jail.py` | Jail listing and status models |
| `server.py` | Server status and settings models |
| `setup.py` | First-run setup wizard models |

**Model Layering Rules:** Models are pure data classes (leaf nodes) in the dependency graph. They must not import from application-layer modules (`app.services`, `app.config`, `app.utils`). Models may import from:
- Standard library and third-party packages (Pydantic, typing)
- Other models in `app.models/` (sibling models)
- `app.models.response` (response envelopes)

**Critical Constraint — No I/O or Side Effects:** Pydantic validators, field defaults, and computed fields must be **pure functions with no side effects**:
- ❌ NO imports from `app.config`, `app.services`, `app.utils`, or `app.routers` (these are application-layer modules)
- ❌ NO calls to `get_settings()`, file I/O, database queries, network calls, or any runtime-dependent functions
- ❌ NO `default_factory` that calls app-layer functions

These constraints ensure that **importing a model file does not trigger application initialization** and prevents hidden circular dependencies.

**Validation that requires access to app-level state** (e.g., allowed log directories, settings, database) must be moved to the **router or service layer**, not in model validators. Validation occurs at the boundary — where settings and services are already available.

#### Tasks (`app/tasks/`)

APScheduler background jobs that run on a schedule without user interaction.

| Task | Purpose |
|---|---|
| `blocklist_import.py` | Downloads all enabled blocklist sources, validates entries, applies bans, records results in the import log |
| `geo_cache_cleanup.py` | Periodically removes entries from the `geo_cache` table that have not been referenced in the configured retention period (default: 90 days). Prevents unbounded database growth. |
| `geo_cache_flush.py` | Periodically flushes newly resolved IPs from the in-memory dirty set to the `geo_cache` SQLite table (default: every 60 seconds). GET requests populate only the in-memory cache; this task persists them without blocking any request. |
| `geo_re_resolve.py` | Periodically re-resolves stale entries in `geo_cache` to keep geolocation data fresh |
| `health_check.py` | Periodically pings the fail2ban socket and updates the cached server status so the frontend always has fresh data |
| `history_sync.py` | Periodically copies new records from the fail2ban SQLite database into BanGUI's `history_archive` table; delegates the sync algorithm to `history_service.py` |
| `session_cleanup.py` | Periodically removes expired sessions from the `sessions` SQLite table (default: every 6 hours). Without this cleanup, the table grows unbounded and degrades query performance. |

#### Utils (`app/utils/`)

Pure helper modules with no framework dependencies.

| Module | Purpose |
|---|---|
| `fail2ban_client.py` | Async client that communicates with fail2ban via its Unix domain socket — sends commands and parses responses using the fail2ban protocol. Modelled after [`./fail2ban-master/fail2ban/client/csocket.py`](../fail2ban-master/fail2ban/client/csocket.py) and [`./fail2ban-master/fail2ban/client/fail2banclient.py`](../fail2ban-master/fail2ban/client/fail2banclient.py). |
| `jail_socket.py` | Low-level jail reload operations (`reload_all`) extracted to break service dependencies. Used by `jail_service`, `jail_config_service`, `action_config_service`, and `filter_config_service` to avoid circular imports between sibling services. |
| `ip_utils.py` | Validates IPv4/IPv6 addresses and CIDR ranges using the `ipaddress` stdlib module, normalises formats |
| `jail_utils.py` | Jail helper functions for configuration and status inference |
| `jail_config.py` | Jail config parser and serializer for fail2ban config manipulation |
| `time_utils.py` | Timezone-aware datetime construction, formatting helpers, time-range calculations |
| `log_utils.py` | Structured log formatting and enrichment helpers |
| `conffile_parser.py` | Parses Fail2ban `.conf` files into structured objects and serialises back to text |
| `config_parser.py` | Builds structured config objects from file content tokens |
| `config_writer.py` | Atomic config file writes, backups, and safe replace semantics |
| `config_file_utils.py` | Common file-level config utility helpers |
| `fail2ban_db_utils.py` | Fail2ban DB path discovery and ban-history parsing helpers |
| `setup_utils.py` | Setup wizard helper utilities |
| `constants.py` | Shared constants: default socket path, default database path, time-range presets, parser truthy values, limits |

#### Configuration (`app/config.py`)

A single Pydantic settings model that loads all configuration from environment variables (prefixed `BANGUI_`) and an optional `.env` file. Validated at startup — the application refuses to start if required values are missing.

#### Dependencies (`app/dependencies.py`)

FastAPI `Depends()` providers that inject shared resources into route handlers: the database connection, service instances, the authenticated session, and the fail2ban client. This is the wiring layer that connects routers to services without tight coupling.

#### Application Entry Point (`app/main.py`)

The FastAPI app factory. Responsibilities:

- Creates the `FastAPI` instance with metadata (title, version, docs URL)
- Registers the **lifespan** context manager (startup: open DB, create aiohttp session, start scheduler; shutdown: close all)
- Mounts all routers
- Registers global exception handlers that map domain exceptions to HTTP status codes with a hierarchical fallback chain
- Applies the setup-redirect middleware (returns `423 Locked` for all API requests when no configuration exists, except for `/api/setup` and `/api/health`)

**Exception Handler Hierarchy:**

Exception handlers are registered in order of specificity to ensure each exception type is caught by the most appropriate handler:

1. **Specific network errors** (Fail2BanConnectionError, Fail2BanProtocolError) → HTTP 502 Bad Gateway
2. **Specific auth/rate errors** (AuthenticationError, RateLimitError) → HTTP 401 Unauthorized / 429 Too Many Requests
3. **Category handlers** (NotFoundError, BadRequestError, ConflictError, OperationError, ServiceUnavailableError) → HTTP 404/400/409/500/503
4. **DomainError catch-all** → HTTP 500 (catches any unregistered DomainError subclass, ensuring proper error_code and metadata are returned)
5. **HTTPException** → HTTP status from exception (FastAPI built-in validation and routing errors)
6. **ValueError** → HTTP 400 Bad Request (Pydantic validation errors)
7. **Exception catch-all** → HTTP 500 Internal Server Error (absolute fallback for unexpected errors)

The DomainError catch-all handler (step 4) is critical: it ensures that any new DomainError subclass automatically gets the correct HTTP status (500), error_code, and metadata through its inherited `error_code` attribute and `get_error_metadata()` method, even if the developer forgot to create an explicit handler for it. This prevents silent failures where an unhandled exception would return a generic "internal_error" code instead of the specific error code defined by the exception class.

### 2.3 Dependency Wiring and Service Composition

BanGUI uses a **lightweight dependency injection (DI) pattern** based on FastAPI's `Depends()` framework. There is no heavy container library — the composition root is implicit and managed through simple provider functions in `app/dependencies.py`.

#### The DI Pattern

Every injectable dependency follows this structure:

1. **Provider Function** — An async function in `app/dependencies.py` that creates and returns a dependency:
   ```python
   async def get_settings(app_context: ...) -> Settings:
       """Provide application settings."""
       return app_context.runtime_settings or app_context.settings
   ```

2. **Type Alias** — An `Annotated` alias that decorates the provider for use in route signatures:
   ```python
   SettingsDep = Annotated[Settings, Depends(get_settings)]
   ```

3. **Injection Point** — Routers declare their dependencies using the type alias:
   ```python
   async def my_route(settings: SettingsDep) -> Response:
       # FastAPI automatically calls get_settings() and injects the result
       ...
   ```

**Module-Level Imports:**

All repository and service modules are imported at module level in `app/dependencies.py`. These imports are safe at the top because no circular dependencies exist — repositories and services do not import from `dependencies.py`. This follows the principle of importing dependencies early and consistently:

```python
# app/dependencies.py (top of file)
from app.repositories import (
    blocklist_repo,
    fail2ban_db_repo,
    session_repo,
    # ... other repository modules
)
from app.services import auth_service, health_service
from app.services.fail2ban_metadata_service import default_fail2ban_metadata_service

# Provider functions simply return the module
async def get_session_repo() -> SessionRepository:
    return session_repo
```

**Exception**: The `from app.db import open_db` import remains local to `get_db()` because it is only used within that specific function and the module load overhead is avoided.

#### Service Composition Root

Services are **not instantiated by a container**. Instead, they are **composed by routers and tasks through explicit parameter passing**. This keeps dependencies visible and avoids implicit side effects.

**Example: How `ban_service.get_active_bans()` is wired:**

```python
# Step 1: Router declares what it needs (dependencies.py)
async def get_ban_service_context(
    db: Annotated[aiosqlite.Connection, Depends(get_db)],
    fail2ban_db_repo: Annotated[Fail2BanDbRepository, Depends(get_fail2ban_db_repo)],
) -> BanServiceContext:
    """Combine database connection and repository."""
    return BanServiceContext(db=db, fail2ban_db_repo=fail2ban_db_repo)

BanServiceContextDep = Annotated[BanServiceContext, Depends(get_ban_service_context)]

# Step 2: Router uses the context and calls the service
@router.get("/active")
async def get_active_bans(
    ban_ctx: BanServiceContextDep,
    socket_path: Fail2BanSocketDep,
    geo_cache: GeoCacheDep,
) -> ActiveBanListResponse:
    # Router explicitly passes everything the service needs
    domain_result = await ban_service.get_active_bans(
        socket_path,
        geo_cache=geo_cache,
        app_db=ban_ctx.db,  # ← Explicit, no magic
    )
    return map_domain_active_ban_list_to_response(domain_result)

# Step 3: Service function accepts dependencies as parameters
async def get_active_bans(
    socket_path: str,
    geo_cache: GeoCache,
    app_db: aiosqlite.Connection,
) -> DomainActiveBanList:
    """Retrieve active bans. All dependencies are explicit parameters."""
    # Service logic here
    ...
```

**Why this pattern?**
- **Explicit**: No hidden coupling. Every dependency is visible in function signatures.
- **Testable**: Easy to mock dependencies by passing test doubles.
- **Lightweight**: No heavyweight DI container library needed. FastAPI's `Depends()` is sufficient.
- **Debuggable**: Stack traces and type checkers understand the full dependency chain.

#### Service Context Dependencies

For convenience, related repositories and the database connection are bundled into **context objects**. These prevent routers from depending on the raw database connection (which violates the repository boundary).

**Available Service Contexts:**

| Context | Includes | Used By |
|---------|----------|---------|
| `SessionServiceContext` | `db`, `session_repo` | auth router |
| `BlocklistServiceContext` | `db`, `blocklist_repo`, `import_log_repo`, `settings_repo` | blocklist router |
| `SettingsServiceContext` | `db`, `settings_repo` | server settings router |
| `BanServiceContext` | `db`, `fail2ban_db_repo` | ban router |
| `HistoryServiceContext` | `db`, `fail2ban_db_repo`, `history_archive_repo` | history router |

Each context is created by a provider function:
```python
async def get_ban_service_context(
    db: Annotated[aiosqlite.Connection, Depends(get_db)],
    fail2ban_db_repo: Annotated[Fail2BanDbRepository, Depends(get_fail2ban_db_repo)],
) -> BanServiceContext:
    return BanServiceContext(db=db, fail2ban_db_repo=fail2ban_db_repo)
```

#### Adding a New Service

Follow this checklist when creating a new service:

1. **Create the service module** — `app/services/my_service.py`
2. **Define the service functions** — Each function takes its dependencies as explicit parameters (no imports of other services at the same layer)
3. **Export key functions** — Only the public API functions are called by routers
4. **If database access is needed:**
   - Routers depend on the appropriate `ServiceContextDep` (e.g., `BanServiceContextDep`)
   - Pass `context.db` and `context.repository` to the service function
5. **If a new context is needed:**
   - Create a `@dataclass` in `app/dependencies.py` to hold the related resources
   - Create a provider function `get_<service>_context()` that combines them
   - Create a type alias `<Service>ContextDep` for router injection
6. **Register the service** — No registration step; FastAPI discovers it via `Depends()`

**Example: Adding a new service that needs blocklist and settings repos:**

```python
# app/services/my_new_service.py
async def do_something(
    db: aiosqlite.Connection,
    blocklist_repo: BlocklistRepository,
    settings_repo: SettingsRepository,
) -> MyResult:
    """Do something with blocklist and settings data."""
    sources = await blocklist_repo.list_sources(db)
    settings = await settings_repo.load(db)
    # Business logic
    return ...

# app/routers/my_router.py
from app.dependencies import BlocklistServiceContextDep
from app.services import my_new_service

@router.get("/something")
async def my_endpoint(
    ctx: BlocklistServiceContextDep,  # ← Already has db, blocklist_repo, settings_repo
) -> MyResponse:
    result = await my_new_service.do_something(
        db=ctx.db,
        blocklist_repo=ctx.blocklist_repo,
        settings_repo=ctx.settings_repo,
    )
    return MyResponse(...)
```

#### The Repository Boundary

Services **must not** depend on raw database connections. The repository boundary is enforced by **not exporting `DbDep` to routers**. Instead:

- Routers declare a `ServiceContextDep` which includes both the `db` and the needed repositories
- Services receive the `db` connection and repositories as parameters
- Repositories are the **only modules** that execute SQL; services never call SQL directly

This ensures:
- Queries are centralized and testable
- Changes to the database layer don't leak into business logic
- Repositories can be mocked independently for testing

#### Lifecycle and Scope

- **Request-scoped**: Database connections are created fresh for each request and closed after the response is sent. This prevents contention and locking issues with SQLite.
- **Application-scoped**: Shared resources like `aiohttp.ClientSession`, the scheduler, and the `GeoCache` are created at startup and reused across all requests.
- **Singleton**: Some services (e.g., `Fail2BanMetadataService`) are instantiated once and cached in `app.state` or imported as module-level instances.

---

## 3. Frontend Architecture

The frontend is a React single-page application built with TypeScript, Vite, and Fluent UI v9. It communicates exclusively with the backend REST API — it never accesses fail2ban, the database, or external services directly.

```
┌──────────────────────────────────────────────────────────────┐
│                     React Application                        │
│                                                              │
│   ┌──────────┐    ┌────────────┐    ┌──────────────────┐    │
│   │  Pages   │───▶│ Components │───▶│   Fluent UI v9   │    │
│   └────┬─────┘    └────────────┘    └──────────────────┘    │
│        │                                                     │
│   ┌────┴─────┐    ┌────────────┐    ┌──────────────────┐    │
│   │  Hooks   │───▶│  API Layer │───▶│  Backend (REST)  │    │
│   └──────────┘    └────────────┘    └──────────────────┘    │
│                                                              │
│   ┌──────────┐    ┌────────────┐    ┌──────────────────┐    │
│   │Providers │    │   Types    │    │     Theme        │    │
│   │(Context) │    │(Interfaces)│    │(Tokens, Styles)  │    │
│   └──────────┘    └────────────┘    └──────────────────┘    │
└──────────────────────────────────────────────────────────────┘
```

### 3.1 Project Structure

```
frontend/
├── public/
├── src/
│   ├── api/                   # API client and per-domain request functions
│   │   ├── client.ts          #   Central fetch wrapper (typed GET/POST/PUT/DELETE)
│   │   ├── endpoints.ts       #   API path constants
│   │   ├── auth.ts            #   Login, logout, session check
│   │   ├── dashboard.ts       #   Dashboard status and ban list
│   │   ├── jails.ts           #   Jail CRUD and controls
│   │   ├── bans.ts            #   Ban/unban actions, banned list
│   │   ├── config.ts          #   Configuration read/write
│   │   ├── history.ts         #   Ban history queries
│   │   ├── blocklist.ts       #   Blocklist source management
│   │   ├── geo.ts             #   IP lookup / geolocation
│   │   └── server.ts          #   Server settings
│   ├── assets/                # Static images, fonts, icons
│   ├── components/            # Reusable UI components
│   │   ├── BanTable.tsx       #   Data table for ban entries
│   │   ├── JailCard.tsx       #   Summary card for a jail
│   │   ├── StatusBar.tsx      #   Server status indicator strip
│   │   ├── TimeRangeSelector.tsx # Quick preset picker (24h, 7d, 30d, 365d)
│   │   ├── IpInput.tsx        #   IP address input with validation
│   │   ├── RegexTester.tsx    #   Side-by-side regex match preview
│   │   ├── WorldMap.tsx       #   Country-outline map with ban counts
│   │   ├── ImportLogTable.tsx #   Blocklist import run history
│   │   ├── ConfirmDialog.tsx  #   Reusable confirmation modal
│   │   ├── RequireAuth.tsx    #   Route guard: redirects unauthenticated users to /login
│   │   ├── SetupGuard.tsx     #   Route guard: redirects to /setup if setup incomplete
│   │   └── ...                #   (additional shared components)
│   ├── hooks/                 # Custom React hooks (stateful logic + API calls)
│   │   ├── useAuth.ts         #   Login state, login/logout actions
│   │   ├── useBans.ts         #   Fetch ban list for a time range
│   │   ├── useJails.ts        #   Fetch jail list and details
│   │   ├── useConfig.ts       #   Fetch and update configuration
│   │   ├── useHistory.ts      #   Fetch historical ban data
│   │   ├── useBlocklists.ts   #   Fetch and manage blocklist sources
│   │   ├── useServerStatus.ts #   Poll server health / status
│   │   └── useGeo.ts          #   IP lookup hook
│   ├── layouts/               # Page-level layout wrappers
│   │   └── AppLayout.tsx      #   Sidebar navigation + header + content area
│   ├── pages/                 # Route-level page components (one per route)
│   │   ├── SetupPage.tsx      #   First-run wizard
│   │   ├── LoginPage.tsx      #   Password prompt
│   │   ├── DashboardPage.tsx  #   Ban overview, status bar
│   │   ├── WorldMapPage.tsx   #   Geographical ban map
│   │   ├── JailsPage.tsx      #   Jail list, detail, controls, ban/unban
│   │   ├── ConfigPage.tsx     #   Configuration viewer/editor
│   │   ├── HistoryPage.tsx    #   Ban history browser
│   │   └── BlocklistPage.tsx  #   Blocklist source management + import log
│   ├── providers/             # React context providers
│   │   ├── AuthProvider.tsx   #   Authentication state and guards
│   │   └── ThemeProvider.tsx  #   Light/dark theme switching
│   ├── theme/                 # Fluent UI theme definitions
│   │   ├── customTheme.ts     #   Brand colour ramp, light and dark themes
│   │   └── tokens.ts          #   Spacing, sizing, and z-index constants
│   ├── types/                 # Shared TypeScript interfaces
│   │   ├── auth.ts            #   LoginRequest, SessionInfo
│   │   ├── ban.ts             #   Ban, BanListResponse, BanRequest
│   │   ├── jail.ts            #   Jail, JailDetail, JailListResponse
│   │   ├── config.ts          #   ConfigSection, ConfigUpdateRequest
│   │   ├── history.ts         #   HistoryEntry, IpTimeline
│   │   ├── blocklist.ts       #   BlocklistSource, ImportLogEntry
│   │   ├── geo.ts             #   GeoInfo, AsnInfo
│   │   ├── server.ts          #   ServerStatus, ServerSettings
│   │   └── api.ts             #   ApiError, PaginatedResponse
│   ├── utils/                 # Pure helper functions
│   │   ├── formatDate.ts      #   Date/time formatting with timezone support
│   │   ├── formatIp.ts        #   IP display formatting
│   │   ├── crypto.ts          #   Browser-native SHA-256 helper (SubtleCrypto)
│   │   └── constants.ts       #   Frontend constants (time presets, etc.)
│   ├── App.tsx                # Root: FluentProvider + BrowserRouter + routes
│   ├── main.tsx               # Vite entry point
│   └── vite-env.d.ts          # Vite type shims
├── tsconfig.json
├── vite.config.ts
└── package.json
```

### 3.2 Module Purposes

#### Pages (`src/pages/`)

Top-level route components. Each page composes layout, components, and hooks to create a full screen. Pages contain **no business logic** — they orchestrate what is displayed and delegate data fetching to hooks.

| Page | Route | Purpose |
|---|---|---|
| `SetupPage` | `/setup` | First-run wizard: set master password, database path, fail2ban connection, preferences |
| `LoginPage` | `/login` | Single-field password prompt; redirects to requested page after success |
| `DashboardPage` | `/` | Server status bar, ban list table, time-range selector |
| `WorldMapPage` | `/map` | World map with per-country ban counts, country filter |
| `JailsPage` | `/jails` | Jail overview list, jail detail panel, controls (start/stop/reload), ban/unban forms, IP lookup, whitelist management |
| `ConfigPage` | `/config` | View and edit jail parameters, filter regex, server settings, regex tester, add log observation |
| `HistoryPage` | `/history` | Browse all past bans, filter by jail/IP/time, per-IP timeline drill-down |
| `BlocklistPage` | `/blocklists` | Manage blocklist sources, schedule configuration, import log, manual import trigger |

#### Components (`src/components/`)

Reusable UI building blocks. Components receive data via props, emit changes via callbacks, and never call the API directly. Built exclusively with Fluent UI v9 components.

| Component | Purpose |
|---|---|
| `StatusBar` | Displays fail2ban server status (online/offline, version, jail count, total bans) |
| `BanTable` | Sortable data table for ban entries with columns for time, IP, jail, country, etc. |
| `JailCard` | Summary card showing jail name, status badge, key metrics |
| `TimeRangeSelector` | Quick-preset picker for filtering data (24h, 7d, 30d, 365d) |
| `IpInput` | IP address text field with inline validation |
| `WorldMap` | SVG/Canvas country-outline map with count overlays and click-to-filter |
| `RegexTester` | Side-by-side sample log + regex input with live match highlighting |
| `ImportLogTable` | Table displaying blocklist import history |
| `ConfirmDialog` | Reusable Fluent UI Dialog for destructive action confirmations |
| `RequireAuth` | Route guard: renders children only when authenticated; otherwise redirects to `/login?next=<path>` |
| `SetupGuard` | Route guard: checks `GET /api/setup` on mount and redirects to `/setup` if not complete; shows a spinner while loading |
| `config/ConfigListDetail` | Reusable two-pane master/detail layout used by the Jails, Filters, and Actions config tabs. Left pane lists items with active/inactive badges (active sorted first, keyboard navigable); right pane renders the selected item's detail content. Collapses to a dropdown on narrow screens. |
| `config/RawConfigSection` | Collapsible section that lazily loads the raw text of a config file into a monospace textarea. Provides a Save button backed by a configurable save callback; shows idle/saving/saved/error feedback. Used by all three config tabs. |
| `config/AutoSaveIndicator` | Small inline indicator showing the current save state (idle, saving, saved, error) for form fields that auto-save on change. |

#### Hooks (`src/hooks/`)

Encapsulate all stateful logic, side effects, and API calls. Components and pages consume hooks to stay declarative.

| Hook | Purpose |
|---|---|
| `useAuth` | Manages login state, provides `login()`, `logout()`, and `isAuthenticated` |
| `useBans` | Fetches ban list for a given time range, returns `{ bans, loading, error }` |
| `useJails` | Fetches jail list and individual jail detail |
| `useConfig` | Reads and writes fail2ban jail configuration via the socket-based API |
| `useFilterConfig` | Fetches and manages a single filter file's parsed configuration |
| `useActionConfig` | Fetches and manages a single action file's parsed configuration |
| `useJailFileConfig` | Fetches and manages a single jail.d config file |
| `useConfigActiveStatus` | Derives active status sets for jails, filters, and actions by correlating the live jail list with the config file lists; returns `{ activeJails, activeFilters, activeActions, loading, error, refresh }` |
| `useAutoSave` | Debounced auto-save hook: invokes a save callback after the user stops typing, tracks saving/saved/error state |
| `useHistory` | Queries historical ban data with filters |
| `useBlocklists` | Manages blocklist sources and import triggers |
| `useServerStatus` | Polls the server status endpoint at an interval |
| `useGeo` | Performs IP geolocation lookups on demand |

#### API Layer (`src/api/`)

A thin typed wrapper around `fetch`. All HTTP communication is centralised here — components and hooks never construct HTTP requests directly.

| Module | Purpose |
|---|---|
| `client.ts` | Central `get<T>`, `post<T>`, `put<T>`, `del<T>` functions with error handling and credentials |
| `endpoints.ts` | All API path constants in one place — no hard-coded URLs anywhere else |
| `auth.ts` | `login()`, `logout()`, `checkSession()` |
| `dashboard.ts` | `fetchStatus()`, `fetchRecentBans()` |
| `jails.ts` | `fetchJails()`, `fetchJailDetail()`, `startJail()`, `stopJail()`, `reloadJail()` |
| `bans.ts` | `banIp()`, `unbanIp()`, `unbanAll()`, `fetchBannedIps()` |
| `config.ts` | Socket-based config: `fetchJailConfigs()`, `updateJailConfig()`, `testRegex()`. File-based config: `fetchJailFiles()`, `fetchJailFile()`, `writeJailFile()`, `setJailFileEnabled()`, `fetchFilterFiles()`, `fetchFilterFile()`, `writeFilterFile()`, `fetchActionFiles()`, `fetchActionFile()`, `writeActionFile()`, `reloadConfig()` |
| `history.ts` | `fetchHistory()`, `fetchIpTimeline()` |
| `blocklist.ts` | `fetchSources()`, `addSource()`, `removeSource()`, `triggerImport()`, `fetchImportLog()` |
| `geo.ts` | `lookupIp()` |
| `server.ts` | `fetchServerSettings()`, `updateServerSettings()` |

#### Types (`src/types/`)

Shared TypeScript interfaces and type aliases. Purely declarative — no runtime code. Grouped by domain. Any type used by two or more files lives here.

#### Providers (`src/providers/`)

React context providers for application-wide concerns.

**Provider Ordering and Compile-Time Validation**

Provider order is **order-sensitive** and enforced at compile-time through TypeScript discriminated unions. The required order (outermost to innermost) is:

1. `ThemeProvider` — must be outermost; provides theme context to `AppContents`
2. `FluentProvider` — supplies Fluent UI theme and design tokens to all Fluent UI consumers
3. `NotificationProvider` — provides notification service; must wrap error boundaries
4. `ErrorBoundary` — catches catastrophic errors at the top level
5. `BrowserRouter` — enables client-side routing
6. `NavigationCancellationProvider` — manages route-aware request cancellation using `useLocation()`
7. `AuthProvider` — validates session on mount; must be inside BrowserRouter (uses `useNavigate()`)
8. `TimezoneProvider` — fetches timezone after auth; wraps protected routes only

**Compile-Time Validation:**

A type-safe builder pattern (`ProviderCompositionBuilder`) in `providerComposition.tsx` enforces this order using TypeScript's discriminated unions. The builder prevents adding providers out of order at compile-time:

```tsx
const tree = createProviderComposition()
  .withTheme({ children })
  .withFluent(theme)          // ✓ Must come after withTheme
  .withNotification()         // ✓ Must come after withFluent
  .withErrorBoundary()        // ✓ Correct order enforced
  .withBrowserRouter()
  .withNavigationCancellation()
  .withAuth()
  .build(routes);
```

Attempting to add providers out of order results in TypeScript errors (no runtime overhead).

**Runtime Validation (Development):**

A runtime validator (`providerOrderValidator.tsx`) provides fallback validation for development:

- `validateProviderPosition()` — checks if a provider is correctly nested
- `validateProvidersExist()` — ensures required providers are in the tree
- `hasProvider()` — queries provider presence
- `useProviderValidation()` — development-only hook that warns if required providers are missing

See `src/providers/PROVIDER_ORDER.md` for detailed dependency rationale.

**Provider Reference:**

| Provider | Purpose |
|---|---|
| `AuthProvider` | Holds authentication state; exposes `isAuthenticated`, `login()`, and `logout()` via `useAuth()`. Synchronizes logout events across browser tabs in real-time using the BroadcastChannel API (with storage event fallback for older browsers). When a user logs out in any tab, all other open tabs immediately reflect the logout state without requiring a page refresh. |
| `TimezoneProvider` | Reads the configured IANA timezone from the backend and supplies it to all children via `useTimezone()` |
| `ThemeProvider` | Manages light/dark theme selection, supplies the active Fluent UI theme to `FluentProvider` |
| `NotificationProvider` | Provides notification service via `useNotification()` hook; must wrap error boundaries so they can display error notifications |
| `NavigationCancellationProvider` | Detects route changes and automatically aborts pending API requests; call `useNavigationAbortSignal()` to get an `AbortSignal` that lives for the current route |

#### Theme (`src/theme/`)

Fluent UI custom theme definitions and design token constants. No component logic — only colours, spacing, and sizing values.

#### Utils (`src/utils/`)

Pure helper functions with no React or framework dependency. Date formatting, IP display formatting, shared constants, and cryptographic utilities.

| Utility | Purpose |
|---|---|
| `formatDate.ts` | Date/time formatting with IANA timezone support |
| `formatIp.ts` | IP address display formatting |
| `crypto.ts` | `sha256Hex(input)` — SHA-256 digest via browser-native `SubtleCrypto` API; used to hash passwords before transmission |
| `constants.ts` | Frontend constants (time presets, etc.) |

---

## 4. Data Flow

### 4.1 Request Lifecycle

Every user action follows this flow through the system:

```
User Action (click, form submit)
       │
       ▼
   Page / Component
       │  calls hook
       ▼
   Hook (useXxx)
       │  calls API function
       ▼
   API Layer (src/api/)
       │  HTTP request
       ▼
   FastAPI Router (app/routers/)
       │  validates input (Pydantic)
       │  calls Depends() for auth + services
       ▼
   Service (app/services/)
       │  enforces business rules
       │  calls repository or fail2ban client
       ▼
   Repository (app/repositories/)     or     fail2ban Client (app/utils/)
       │  executes SQL query                       │  sends socket command
       ▼                                           ▼
   SQLite Database                             fail2ban Server
       │                                           │
       └──────────── response bubbles back up ─────┘
```

### 4.2 Authentication Flow

```
┌─────────┐     POST /api/auth/login      ┌─────────────┐
│  Login   │ ─────────────────────────────▶│ auth router  │
│  Page    │     { password: "***" }       │              │
└─────────┘                                └──────┬───────┘
                                                  │
                                           ┌──────┴───────┐
                                           │ auth_service  │
                                           │ - verify hash │
                                           │ - create token│
                                           └──────┬───────┘
                                                  │
                                           ┌──────┴───────┐
                                           │ session_repo  │
                                           │ - store token │
                                           └──────┬───────┘
                                                  │
  Set-Cookie: session=<token>                     │
◀─────────────────────────────────────────────────┘
```

- The master password is hashed and stored during setup.
- On login, the submitted password is verified against the stored hash.
- A session token is created, stored in the database, and returned as an HTTP-only cookie.
- Every subsequent request is authenticated via the session cookie using a FastAPI dependency.
- The `AuthProvider` on the frontend guards all routes except `/setup` and `/login`.

### 4.3 fail2ban Communication

BanGUI communicates with fail2ban through its **Unix domain socket** using the fail2ban client-server protocol.

```
┌────────────────────┐          ┌──────────────────┐
│  ban_service.py    │          │  fail2ban server  │
│  jail_service.py   │──socket──│                   │
│  config_service.py │          │  /var/run/fail2ban│
│  health_service.py │          │  /fail2ban.sock   │
└────────────────────┘          └──────────────────┘
```

The `fail2ban_client.py` utility module wraps this communication:

- Opens an async connection to the Unix socket
- Serialises commands using the fail2ban protocol (pickle-based, see [`./fail2ban-master/fail2ban/client/csocket.py`](../fail2ban-master/fail2ban/client/csocket.py))
- Parses responses into typed Python objects
- Handles connection errors gracefully (timeout, socket not found, permission denied)

> **Reference source:** The vendored fail2ban source at [`./fail2ban-master`](../fail2ban-master) is included in the repository as an authoritative protocol reference. When implementing or debugging socket communication, consult:
>
> | File | What it documents |
> |---|---|
> | [`./fail2ban-master/fail2ban/client/csocket.py`](../fail2ban-master/fail2ban/client/csocket.py) | `CSocket` class — low-level Unix socket connection, pickle serialisation, `CSPROTO.END` framing |
> | [`./fail2ban-master/fail2ban/client/fail2banclient.py`](../fail2ban-master/fail2ban/client/fail2banclient.py) | `Fail2banClient` — command dispatch, argument handling, response beautification |
> | [`./fail2ban-master/fail2ban/client/beautifier.py`](../fail2ban-master/fail2ban/client/beautifier.py) | Response parser — converts raw server replies into human-readable / structured output |
> | [`./fail2ban-master/fail2ban/protocol.py`](../fail2ban-master/fail2ban/protocol.py) | `CSPROTO` constants and the full list of supported commands with descriptions |
> | [`./fail2ban-master/fail2ban/client/configreader.py`](../fail2ban-master/fail2ban/client/configreader.py) | Config file parsing used by fail2ban — reference for understanding jail/filter structure |

**Key commands used:**

| Command | Purpose |
|---|---|
| `status` | Get global server status (number of jails, fail2ban version) |
| `status <jail>` | Get jail detail (banned IPs, failure count, filter info) |
| `set <jail> banip <ip>` | Ban an IP in a specific jail |
| `set <jail> unbanip <ip>` | Unban an IP from a specific jail |
| `set <jail> idle on/off` | Toggle jail idle mode |
| `start/stop <jail>` | Start or stop a jail |
| `reload <jail>` | Reload a single jail configuration |
| `reload` | Reload all jails |
| `get <jail> ...` | Read jail settings (findtime, bantime, maxretry, filter, actions, etc.) |
| `set <jail> ...` | Write jail settings |
| `set loglevel <level>` | Change server log level |
| `set logtarget <target>` | Change server log target |
| `set dbpurgeage <seconds>` | Set database purge age |
| `flushlogs` | Flush and re-open log files |

### 4.4 fail2ban Database Access

In addition to the live socket, BanGUI reads the **fail2ban SQLite database** directly for historical data that the socket protocol does not expose (ban history, past log matches). This is read-only access.

```
history_service.py ──read-only──▶ fail2ban.db (SQLite)
```

The fail2ban database contains:

- `bans` table — historical ban records (IP, jail, timestamp, ban data)
- `jails` table — jail definitions
- `logs` table — matched log lines per ban

BanGUI queries these tables to power the Ban History page and the per-IP timeline view.

### 4.5 External API Communication

```
geo_service.py ──aiohttp──▶ IP Geolocation API (country, ASN, RIR)
blocklist_service.py ──aiohttp──▶ Blocklist URLs (plain-text IP lists)
```

All external HTTP calls go through a shared `aiohttp.ClientSession` created during startup and closed during shutdown. External data is validated before use (IP format, response structure).

---

## 5. Database Design

BanGUI maintains its **own SQLite database** (separate from the fail2ban database) to store application state.

### 5.1 Application Database Tables

| Table | Purpose |
|---|---|
| `settings` | Key-value store for application configuration (master password hash, fail2ban socket path, database path, timezone, session duration) |
| `sessions` | Active session token hashes with expiry timestamps. Tokens are stored as one-way SHA256 hashes to prevent token hijacking if the database is exposed. |
| `geo_cache` | Resolved IP geolocation results (ip, country_code, country_name, asn, org, cached_at, last_seen). Tracks the last time each IP address was referenced to enable retention policies. Entries older than 90 days are automatically purged by the `geo_cache_cleanup` task to prevent unbounded growth. Loaded into memory at startup via `load_cache_from_db()`; new entries are flushed back by the `geo_cache_flush` background task. |
| `blocklist_sources` | Registered blocklist URLs (id, name, url, enabled, created_at, updated_at) |
| `import_logs` | Record of every blocklist import run (id, source_id, timestamp, ips_imported, ips_skipped, errors, status) |

### 5.2 Database Boundaries

| Database | Owner | BanGUI Access |
|---|---|---|
| BanGUI application DB (`bangui.db`) | BanGUI | Read + Write |
| fail2ban DB (`fail2ban.db`) | fail2ban | Read-only (for history queries) |

---

## 6. Setup & Configuration Persistence

### 6.1 Initial Setup Wizard & One-Time Configuration

The setup wizard (`POST /api/setup`) runs once during first-time startup to configure:
- Master password (bcrypt-hashed)
- Runtime database path (where BanGUI stores operational state)
- fail2ban Unix socket path
- IANA timezone
- Session duration (in minutes)
- Map color thresholds for geolocation visualization

**Atomicity & Crash-Safety:**

Setup is implemented with explicit transaction boundaries across two SQLite databases (bootstrap config DB and runtime app DB) to ensure atomicity:

1. **Phase 1 (Bootstrap DB transaction)**: Set `setup_state = "in_progress"` and persist `database_path`. On commit, this is the first checkpoint — if process crashes here, the next setup attempt will detect and clean up.

2. **Phase 2 (Filesystem + Runtime DB)**: Initialize runtime database schema outside a transaction (idempotent via `CREATE TABLE IF NOT EXISTS`).

3. **Phase 3 (Runtime DB transaction)**: Batch-write all runtime settings (password hash, paths, config) atomically in a single `BEGIN IMMEDIATE ... COMMIT` transaction. Either all settings are persisted or none are.

4. **Phase 4 (Bootstrap DB transaction)**: Set `setup_state = "complete"` and `setup_completed = "1"`. This is the final commit point — only when this succeeds is setup considered complete.

**Password Hash Idempotency:**

The bcrypt password hash is computed early (before any DB writes) to ensure that if setup is retried after a crash, the same hash is used throughout all retry attempts. This prevents divergent hashes due to bcrypt's random salt generation.

**State Machine:**

| State | Meaning | Recovery |
|-------|---------|----------|
| `null` | Setup not started | Normal flow: begin setup |
| `"in_progress"` | Bootstrap DB marked, runtime DB being initialized | Retry from beginning (runtime DB may be partial) |
| `"complete"` | All settings persisted, setup finished | Skip setup (already done) |

If a crash is detected in `"in_progress"` state on the next startup, cleanup logic can detect this and either retry or remove the partial runtime database before retrying.

**Backward Compatibility:**

The `setup_completed = "1"` key is still written for backward compatibility with cache detection. Modern code checks `setup_state = "complete"` for clearer semantics.

---

## 8. Authentication & Session Management

- **Single-user model** — one master password, no usernames.
- Password is hashed with a strong algorithm (e.g., bcrypt or argon2) and stored in the application database during setup.
- Sessions are token-based, stored server-side in the `sessions` table as one-way SHA256 hashes, and delivered to the browser as HTTP-only secure cookies.
- **Session token hashing** — Session tokens are hashed before storage to prevent token hijacking if the database file is exposed. Only the hash (`token_hash`) is stored in the database; the raw token is never persisted. When validating a session, the incoming token is hashed before the database lookup. This ensures the database alone is not sufficient to usurp a session — an attacker would also need knowledge of the original token value.
- Session expiry is configurable (set during setup, stored in `settings`).
- The frontend `AuthProvider` checks session validity on mount and redirects to `/login` if invalid.
- The backend `dependencies.py` provides an `authenticated` dependency that validates the session cookie on every protected endpoint.
- **Session validation cache** (`InMemorySessionCache` in `app.utils.session_cache`) — validated session tokens are cached in memory for 10 seconds (configurable via `session_cache_ttl_seconds`) to avoid a SQLite round-trip on every request from the same browser. The cache is invalidated immediately on logout. **⚠️  This cache is process-local and not safe for multi-worker or distributed deployments.** In single-worker mode (enforced by TASK-002), this is safe and improves performance. For multi-worker deployments, replace `InMemorySessionCache` with a shared backend (Redis, database, shared memory) implementing the `SessionCache` protocol. See `app/utils/session_cache.py` module docstring for implementation details.
- **GeoCache** — `GeoCache` instance is created at startup with a configurable `allow_http_fallback` flag and stored on `app.state.geo_cache`. It implements a primary + fallback resolution strategy: (1) try local MaxMind GeoLite2-Country MMDB database (primary, encrypted, no network traffic), (2) if unavailable/no result and allowed, fall back to ip-api.com HTTP API (unencrypted, disabled by default for security). Encapsulates in-memory lookup cache, negative cache for unresolvable IPs (5-minute TTL), dirty set for persistence, and thread-safe async locking. Cache is loaded from the `geo_cache` SQLite table on startup. New resolutions are accumulated in memory and periodically flushed to the database by the `geo_cache_flush` background task. Stale entries are re-resolved by the `geo_re_resolve` task. Injected into routes and tasks via FastAPI's dependency system. See Backend-Development.md § IP Geolocation Resolution for setup and security details.
- **Runtime state** (`RuntimeState` in `app.utils.runtime_state`) — stores mutable application state: `server_status` (fail2ban online/offline), `last_activation` (jail activation tracking), `pending_recovery` (crash detection), `runtime_settings` (effective configuration), and service-specific state holders like `jail_service_state` (`JailServiceState` for jail capability detection cache). RuntimeState fields are managed through dedicated functions (e.g., `record_activation()`, `clear_pending_recovery()`) and via dependency injection to services. Service-specific state (like `JailServiceState`) is nested within `RuntimeState` to keep all mutable state in one controlled location. **⚠️  RuntimeState is process-local and only safe when BanGUI runs as a single asyncio worker.** Mutations must not span `await` points (cooperative scheduling within a single event loop is safe). In multi-worker deployments, each process has its own copy — logouts from worker A don't affect worker B's cache, health status updates are per-worker, and activation tracking is unreliable. BanGUI enforces single-worker mode (TASK-002) to prevent this issue. For future multi-worker support, replace RuntimeState with a shared coordination backend (Redis, shared memory, database). See `app/utils/runtime_state.py` module docstring for details.
- **Setup-completion flag** — once `is_setup_complete()` returns `True`, the result is stored in `app.state._setup_complete_cached`. The `SetupRedirectMiddleware` skips the DB query on all subsequent requests, removing 1 SQL query per request for the common post-setup case. The completion flag is only written after the runtime database is successfully initialized and all initial setup settings are persisted, preventing a failed setup from permanently bypassing the setup wizard.
### 8.1 CSRF Protection

State-mutating endpoints (POST, PUT, DELETE, PATCH) that use cookie-based authentication are protected against Cross-Site Request Forgery (CSRF) attacks via a **custom header check middleware**.

**Design:**
- For requests authenticated via the session cookie (not Bearer token), the `CsrfMiddleware` requires the custom header `X-BanGUI-Request: 1` to be present.
- The frontend API client automatically includes this header on all requests.
- Cross-site `fetch()` calls cannot set custom headers without CORS preflight, which the backend rejects for non-allowed origins, providing defense-in-depth.
- Safe HTTP methods (GET, HEAD, OPTIONS) bypass the check.
- Bearer token authentication (via `Authorization: Bearer` header) bypasses the check because tokens are not CSRF-vulnerable (they are not automatically sent on cross-origin requests).
- Requests missing the CSRF header receive a `403 Forbidden` response with detail: `"CSRF validation failed. Request rejected."`.

This mechanism complements the existing `SameSite=Lax` cookie policy, which blocks traditional `<form>` POST requests but does not protect against JavaScript-initiated requests on a subdomain or same-origin XSS injection.

---
## 9. Scheduling

APScheduler 4.x (async mode) manages recurring background tasks.

```
┌──────────────────────┐
│     APScheduler      │
│  (async, in-process) │
├──────────────────────┤
│  blocklist_import    │  ── runs on configured schedule (default: daily 03:00)
│  geo_cache_cleanup   │  ── runs every 24 hours (nightly)
│  geo_cache_flush     │  ── runs every 60 seconds
│  health_check        │  ── runs every 30 seconds
└──────────────────────┘
```

- The scheduler is started during the FastAPI lifespan startup and stopped during shutdown.
- Job schedules are persisted in the application database so they survive restarts.
- Users can modify the blocklist import schedule through the web interface.
- A manual "Run Now" button triggers the blocklist import job outside the schedule.

---

## 10.1 Background Tasks and Database Access

- APScheduler jobs run outside FastAPI request/response scope and therefore cannot rely on ``Depends(get_db)``.
- Background tasks must open their own application database connection via ``app.db.open_db`` and close it when the work completes.
- Use a shared task helper (``app.tasks.db.task_db``) so every task follows the same async context manager pattern and avoids connection leaks.
- This pattern is intentional: task code is structurally separate from request-handling dependencies and should not attempt to reuse request-scoped DB connections.

---

## 9. API Design

### 9.1 Conventions

- All endpoints are grouped under `/api/` prefix.
- JSON request and response bodies, validated by Pydantic models.
- Authentication via session cookie on all endpoints except `/api/setup` and `/api/auth/login`.
- Setup-redirect middleware: while no configuration exists, all API endpoints (except `/api/setup` and `/api/health`) return `423 Locked` with `{"detail": "Setup not complete.", "setup_required": true}`. This ensures API consumers can detect setup as a distinct condition rather than transparently following redirects.
- Standard HTTP status codes: `200` success, `201` created, `204` no content, `400` bad request, `401` unauthorized, `404` not found, `422` validation error, `423` locked, `500` server error.
- Error responses follow a consistent shape: `{ "detail": "Human-readable message" }`.

### 9.2 Endpoint Groups

| Group | Endpoints | Description |
|---|---|---|
| **Auth** | `POST /login`, `POST /logout` | Session management |
| **Setup** | `POST /setup` | First-run configuration |
| **Dashboard** | `GET /status`, `GET /bans` | Overview data for the main page |
| **Jails** | `GET /`, `GET /:name`, `POST /:name/start`, `POST /:name/stop`, `POST /:name/reload`, `POST /reload-all` | Jail listing and controls |
| **Bans** | `POST /ban`, `POST /unban`, `POST /unban-all`, `GET /banned` | Ban management |
| **Config** | `GET /`, `PUT /`, `POST /test-regex` | Configuration viewing and editing |
| **History** | `GET /`, `GET /ip/:ip` | Historical ban browsing |
| **Blocklists** | `GET /sources`, `POST /sources`, `DELETE /sources/:id`, `POST /import`, `GET /import-log` | Blocklist management |
| **Geo** | `GET /lookup/:ip` | IP geolocation and enrichment |
| **Server** | `GET /settings`, `PUT /settings`, `POST /flush-logs` | Server-level settings |

---

## 9. Deployment Architecture

```
┌──────────────────────────────────────────────────┐
│                   Host Machine                   │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │  Reverse Proxy (nginx / caddy)              │ │
│  │  - TLS termination                          │ │
│  │  - /api/* → backend (uvicorn)               │ │
│  │  - /*     → frontend (static files)         │ │
│  └──────────────┬───────────────┬──────────────┘ │
│                 │               │                 │
│  ┌──────────────┴───┐  ┌───────┴──────────────┐  │
│  │ Backend           │  │ Frontend             │  │
│  │ uvicorn + FastAPI │  │ Static build (Vite)  │  │
│  │ (port 8000)       │  │ (served by proxy)    │  │
│  └────────┬──────────┘  └──────────────────────┘  │
│           │                                       │
│  ┌────────┴──────────────────────────────────┐    │
│  │  fail2ban (systemd service)               │    │
│  │  Socket: /var/run/fail2ban/fail2ban.sock  │    │
│  │  Database: /var/lib/fail2ban/fail2ban.db  │    │
│  └───────────────────────────────────────────┘    │
└──────────────────────────────────────────────────┘
```

- The backend runs as an ASGI server (uvicorn) behind a reverse proxy.
- The frontend is built to static files by Vite and served directly by the reverse proxy.
- The backend process needs read access to the fail2ban socket and the fail2ban database.
- Both the application database and the fail2ban database reside on the same host.

---

## 10.2 nginx Routing Rules

The reverse proxy (nginx) must route requests correctly to prevent frontend SPA fallback rules from hiding backend 404 errors. The following location blocks ensure proper behavior:

### Location Block Priority

nginx uses **longest-prefix matching** to determine which location block handles a request:
1. Exact matches (`location =`) — highest priority
2. Regular expression matches (`location ~`) — second priority
3. Prefix matches (`location /prefix`) — matched in order of specificity (longest first)
4. Catch-all (`location /`) — lowest priority

### Routing Configuration

| Location Block | Rule | Purpose |
|---|---|---|
| `location /api/` | `proxy_pass http://backend:8000;` — **no `try_files`** | Proxy all API requests to FastAPI backend. Any unmatched API route (typos, invalid paths) returns 404 from the backend. |
| `location /assets/` | `try_files $uri =404;` | Serve static assets with long-term caching. Return 404 if file doesn't exist. |
| `location /` | `try_files $uri $uri/ /index.html;` | SPA fallback: serve `index.html` for all unmatched routes (client-side routing). |

### Routing Behavior

```
Request → /api/some-endpoint
    ↓
    nginx matches location /api/ (longest prefix)
    ↓
    proxy_pass → backend:8000
    ↓
    Backend returns 404 if endpoint doesn't exist (✓ correct)
    Client sees 404, not SPA HTML

Request → /some-page
    ↓
    nginx matches location / (catch-all)
    ↓
    try_files looks for file, then directory, then /index.html
    ↓
    Serves /index.html (React Router handles client-side routing)
    ↓
    Client sees 200 with HTML (✓ correct for SPA)

Request → /api/typos
    ↓
    nginx matches location /api/ (longest prefix, NOT catch-all)
    ↓
    proxy_pass → backend:8000
    ↓
    FastAPI returns 404 (✓ correct, not caught by SPA fallback)
```

### Critical Implementation Notes

- **Never add `try_files` to the `/api/` location block** — this would hide backend 404s.
- **The `/api/` location must come before the `/` catch-all** in the config (this is automatically respected via longest-prefix matching).
- **No inherited `try_files` rules** — the `/api/` location has no global `try_files` that could affect it.
- **Backend 404 responses pass through nginx unchanged** — nginx does not rewrite 404 responses from the backend.

---

## 9.2a nginx Security Headers

nginx adds the following OWASP-recommended security headers to all responses:

| Header | Value | Purpose |
|---|---|---|
| **Content-Security-Policy** | `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-ancestors 'none';` | Prevents XSS attacks by restricting script execution to same-origin. `style-src 'unsafe-inline'` is required for Fluent UI v9's inline styles. |
| **X-Frame-Options** | `DENY` | Prevents clickjacking by disallowing iframe embedding. |
| **X-Content-Type-Options** | `nosniff` | Prevents MIME-sniffing; browsers must respect the declared Content-Type. |
| **Referrer-Policy** | `no-referrer` | Prevents leaking internal URLs in the `Referer` header to third-party resources. |
| **Permissions-Policy** | `geolocation=(), microphone=(), camera=()` | Disables access to browser APIs not needed by the application. |
| **Strict-Transport-Security** | *Commented out* | Must only be enabled after HTTPS is fully configured. Uncomment when TLS termination is production-ready. |

All headers use the `always` directive, ensuring they are included in error responses (4xx, 5xx) as well.

### CSP and Fluent UI

Fluent UI v9 applies styles via inline `style` attributes on DOM elements. To support this, `style-src 'unsafe-inline'` is required. A stricter CSP using nonces would require server-side rendering of the HTML shell, which is outside the current architecture.

---

## 9.3 Deployment Constraints

### Single-Executor Scheduler Requirement

**BanGUI's background scheduler must run with exactly one executor process.**

The application uses APScheduler's `AsyncIOScheduler`, which is bound to a single asyncio event loop and cannot be safely shared across multiple worker processes. If the app is deployed with `--workers N` (where N > 1), the following failures occur:

- Each worker process creates its own independent scheduler instance.
- All background jobs execute **N times simultaneously** (once per worker).
- Results:
  - **Duplicate blocklist imports** — the same IP ranges are banned N times.
  - **Duplicate history entries** — the same historical events are recorded N times.
  - **Duplicate ban operations** — bans are executed multiple times, with potential state conflicts.
  - **SQLite lock contention** — concurrent writes to the same database from N workers cause lock timeouts.

### Enforcement Mechanism

BanGUI enforces single-executor safety through a **database-backed lock** that works reliably in container orchestration environments:

1. **Fast check (env var):** On startup, the `BANGUI_WORKERS` environment variable is checked (if set). If explicitly set to a value > 1, startup fails immediately with a clear error.

2. **Authoritative check (database lock):** During startup, BanGUI acquires an atomic database lock in the `scheduler_lock` table. This lock:
   - Uses a singleton row (id=1) to prevent race conditions across simultaneously starting instances
   - Stores the PID, hostname, creation timestamp, and heartbeat timestamp of the lock holder
   - Is considered stale if the heartbeat hasn't been updated for 60 seconds
   - Is automatically cleaned up on stale instance detection, allowing failover in rolling deployments

3. **Lock acquisition (startup):**
   - Clean up any stale locks (heartbeat older than 60 seconds)
   - Attempt to insert a new lock row with this instance's PID and hostname
   - If the INSERT fails (row already exists), reject startup with a clear error
   - If the INSERT succeeds, this instance holds the lock and will start the scheduler

4. **Lock maintenance (runtime):** A periodic background task (`scheduler_lock_heartbeat`) updates the lock's heartbeat timestamp every 10 seconds, keeping it alive and preventing false positives from temporary load spikes.

5. **Lock release (shutdown):** On graceful shutdown, the lock is released, allowing other instances to acquire it.

**Why database-backed instead of filesystem?**

Database-backed locking is more reliable in container orchestration because:
- **Atomicity:** SQLite transactions are atomic — no race condition window between checking and inserting
- **Container-safe:** Works across containers with shared database volumes (no NFS/SMB edge cases)
- **Stale detection:** Heartbeat-based TTL is simpler and more reliable than PID-based checks (PID reuse is common in containers)
- **No false positives:** Timestamp-based expiration eliminates issues with PID reuse

### Startup Sequence with Scheduler Lock

```
1. DATABASE stage
   └─ Initialize SQLite schema (including scheduler_lock table)

2. WORKER_MODE stage (formerly first, now depends on DATABASE)
   ├─ Fast check: Verify BANGUI_WORKERS env var if explicitly set
   └─ Authoritative check: Acquire scheduler lock in database
      → If lock held by another instance: Fail with clear error
      → If lock acquired: Continue to GEO_CACHE stage

3. (rest of startup continues as normal)
```

### Troubleshooting

**Problem:** Startup fails with "Could not acquire scheduler lock"

**Solution:**
1. Verify no other BanGUI instances are running
2. Inspect the lock: `sqlite3 bangui.db "SELECT * FROM scheduler_lock;"`
3. Check who holds the lock (hostname, PID, heartbeat time)
4. If stale (heartbeat older than 60 seconds), clean it:
   ```sql
   sqlite3 bangui.db "DELETE FROM scheduler_lock WHERE (strftime('%s', 'now') - heartbeat_at) > 60;"
   ```
5. Retry the failed instance

**Problem:** Stale lock after instance crash

BanGUI handles this automatically:
- The next instance to start will detect the stale lock (heartbeat older than 60 seconds)
- It will clean it up and acquire the lock
- The new instance starts the scheduler as normal

No manual intervention is required.

### Environment Variables

- **`BANGUI_WORKERS`** (optional, default: unset)
  - If set to `1` or unset: Normal operation (any number of instances may start, but only one holds the lock)
  - If set to > `1`: Startup fails immediately with an error (fast check)
  - Reason: Legacy env var for explicitly forbidding multi-worker deployments

### Container Orchestration Examples

**Docker Compose:**
- Single service instance (no scaling) — scheduler runs normally

**Kubernetes:**
- Single Pod replica — scheduler runs normally
- Multiple Pod replicas (during rolling update) — old Pod releases lock on shutdown, new Pod acquires it
  - No duplicate jobs, no startup failures
  - Health check should allow 30-60 seconds for lock handoff

**systemd / process manager:**
- Single process — scheduler runs normally
- Accidental multi-process restart — lock prevents duplicate jobs, other processes fail to start scheduler

### Future Multi-Worker Support

To safely support multiple workers in the future:

1. **External job store:** Move APScheduler from in-memory to a persistent store (e.g., SQLAlchemy-backed job store with PostgreSQL or Redis).
2. **Distributed locking:** Use a distributed lock (Redis, etcd) instead of database lock for better performance.
3. **Process coordination:** Implement a process-to-worker pool communication mechanism so the scheduler runs only on one designated worker.

Currently, the single-executor approach is simple, maintainable, and sufficient for BanGUI's operational requirements. The database lock provides reliable enforcement across all deployment scenarios.

---

## 10. Observability & Distributed Tracing

BanGUI implements **distributed tracing** via **correlation IDs** to correlate errors and requests across frontend and backend systems.

### Architecture

```
┌─────────────────────────────────────────────────────────────┐
│ Frontend (React + TypeScript)                               │
├─────────────────────────────────────────────────────────────┤
│ • API Client generates session-scoped UUID4 (correlation ID)│
│ • Telemetry service records structured events               │
│ • Error boundaries catch render errors                      │
│ • All telemetry events include correlation ID for tracing   │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ├─ Every request includes
                     │  X-Correlation-ID header
                     │
┌────────────────────┴────────────────────────────────────────┐
│ Backend (Python + FastAPI + structlog)                      │
├─────────────────────────────────────────────────────────────┤
│ • CorrelationIdMiddleware extracts/generates correlation ID │
│ • All logs automatically include correlation ID              │
│ • Error responses include correlation_id field              │
│ • structlog outputs JSON with correlation ID in all events  │
└─────────────────────────────────────────────────────────────┘
```

### Correlation ID Flow

1. **Frontend → Backend:**
   - API client generates/retrieves session-scoped UUID4
   - UUID4 sent in `X-Correlation-ID` request header
   - All requests use same session UUID (set once, reused)

2. **Backend Processing:**
   - CorrelationIdMiddleware extracts/generates correlation ID
   - ID stored in structlog contextvars
   - All structured log entries include correlation ID automatically
   - Error responses include `correlation_id` field in JSON

3. **Backend → Frontend:**
   - Response includes `X-Correlation-ID` header
   - Error responses include `correlation_id` in response body
   - Frontend error handlers extract correlation ID

4. **Frontend Error Logging:**
   - Error handlers extract correlation ID from API response
   - Telemetry service logs error with correlation ID
   - Browser console and telemetry backends receive linked events

### Example: Correlating an Error Across Systems

**Scenario:** User clicks "Ban IP" button → API returns 500 error → error logged and displayed

**Frontend telemetry event:**
```json
{
  "event": "api_error",
  "severity": "error",
  "message": "Server error banning IP",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "context": {
    "status": 500,
    "endpoint": "/api/bans"
  },
  "timestamp": "2025-04-30T18:30:00.000Z"
}
```

**Backend structured log:**
```json
{
  "event": "ban_service_error",
  "severity": "error",
  "message": "Failed to ban IP",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
  "context": {
    "ip": "192.168.1.1",
    "jail": "sshd",
    "error": "fail2ban socket error"
  },
  "timestamp": "2025-04-30T18:30:00.000Z"
}
```

**Troubleshooting:** Engineer searches logs for correlation ID `550e8400-e29b-41d4-a716-446655440000` and finds all related events (request received, jail lookup, fail2ban call, error response) in order.

### Implementation Details

**Backend:**
- Middleware: `app/middleware/correlation.py`
  - Generates UUID4 if `X-Correlation-ID` header missing
  - Stores in structlog contextvars for automatic inclusion in all logs
  - Adds correlation ID to response header and error responses
- All error handlers include `correlation_id` in `ErrorResponse`
- See `backend/app/models/response.py` for `ErrorResponse.correlation_id` field

**Frontend:**
- API client: `frontend/src/api/client.ts`
  - Generates session-scoped UUID4 on first use
  - Includes in `X-Correlation-ID` header for all requests
  - Extracts from response headers and stores in `ApiError`
- Telemetry service: `frontend/src/utils/telemetry.ts`
  - Structured event logging with correlation ID support
  - Redaction utilities for privacy/security
  - Handlers for custom backends (console logger by default)
- Error handlers: `frontend/src/utils/fetchError.ts`
  - Extract correlation ID from API errors
  - Log with telemetry for distributed tracing
- Error boundaries: `frontend/src/components/{Error,Page,Section}ErrorBoundary.tsx`
  - Catch render-time exceptions
  - Log with telemetry for observability
  - **Note:** `ErrorBoundary.componentDidCatch()` accesses `errorInfo.componentStack` which is not part of the public React.ErrorInfo type definition. This is a React DevTools implementation detail accessed via type casting (`as any`). It captures the React component hierarchy for debugging but may change in future React versions. See [React issue #3623](https://github.com/facebook/react/issues/3623) for context.

### Privacy & Security

- **No sensitive data logged:**
  - Passwords, tokens, session IDs never logged
  - PII (names, emails, IPs) logged only with explicit intent and redaction
  - Redaction utilities: `telemetry.redact()`, `telemetry.redactObject()`

- **Backend:** Correlation IDs use opaque UUID4 (no user data embedded)
- **Frontend:** Same session UUID for all requests (safe to expose in logs)

### Future Enhancements

1. **Backend error telemetry aggregation:**
   - Send structured logs to observability platform (DataDog, Grafana Loki, etc.)
   - Query by correlation ID to trace entire request flow

2. **Frontend error reporting:**
   - Send frontend telemetry to backend `/api/telemetry` endpoint
   - Store alongside backend logs for unified view

3. **Metrics & dashboards:**
   - Error rates by endpoint, severity, error type
   - Latency percentiles and distribution
   - Request success/failure trends

---

## 11. Design Principles

These principles govern all architectural decisions in BanGUI.

| Principle | Application |
|---|---|
| **Separation of Concerns** | Frontend and backend are independent. Backend layers (router → service → repository) never mix responsibilities. |
| **Service Independence** | Services must not import other services at the same layer (e.g., `jail_config_service` must not import `jail_service`). Shared logic belongs in the utils layer (`app/utils/`). This prevents circular dependencies, improves testability, and keeps each service focused on its domain. |
| **Single Responsibility** | Each module, service, and component has one well-defined job. |
| **Dependency Inversion** | Services depend on abstractions (protocols), not concrete implementations. FastAPI `Depends()` wires everything. |
| **Async Everything** | All I/O is non-blocking. No synchronous database, HTTP, or socket calls anywhere in the backend. |
| **Validate at the Boundary** | Pydantic models validate all data entering the backend. TypeScript types enforce structure on the frontend. |
| **Fail Fast** | Configuration is validated at startup. Invalid input is rejected immediately with clear errors. |
| **Composition over Inheritance** | Small, focused objects are composed together rather than building deep class hierarchies. |
| **DRY** | Shared logic lives in utils, hooks, or base services — never duplicated across modules. |
| **KISS** | The simplest correct solution wins. No premature abstractions or over-engineering. |
| **YAGNI** | Only build what is needed now. Extend when a real requirement appears. |

