refactor: complete Task 2/3 geo decouple + exceptions centralization; mark as done

Docs/Refactoring.md

@@ -1,238 +1,195 @@
-# BanGUI — Refactoring Instructions for AI Agents
+# BanGUI — Architecture Issues & Refactoring Plan
 
-This document is the single source of truth for any AI agent performing a refactoring task on the BanGUI codebase.  
-Read it in full before writing a single line of code.  
-The authoritative description of every module, its responsibilities, and the allowed dependency direction is in [Architekture.md](Architekture.md). Always cross-reference it.
+This document catalogues architecture violations, code smells, and structural issues found during a full project review. Issues are grouped by category and prioritised.
 
 ---
 
-## 0. Golden Rules
+## 1. Service-to-Service Coupling (Backend)
 
-1. **Architecture first.** Every change must comply with the layered architecture defined in [Architekture.md §2](Architekture.md). Dependencies flow inward: `routers → services → repositories`. Never add an import that reverses this direction.
-2. **One concern per file.** Each module has an explicitly stated purpose in [Architekture.md](Architekture.md). Do not add responsibilities to a module that do not belong there.
-3. **No behaviour change.** Refactoring must preserve all existing behaviour. If a function's public signature, return value, or side-effects must change, that is a feature — create a separate task for it.
-4. **Tests stay green.** Run the full test suite (`pytest backend/`) before and after every change. Do not submit work that introduces new failures.
-5. **Smallest diff wins.** Prefer targeted edits. Do not rewrite a file when a few lines suffice.
+The architecture mandates that dependencies flow **routers → services → repositories**, yet **15 service-to-service imports** exist, with 7 using lazy imports to work around circular dependencies.
+
+| Source Service | Imports From | Line | Mechanism |
+|---|---|---|---|
+| `history_service` | `ban_service` | L29 | Direct import of 3 **private** functions: `_get_fail2ban_db_path`, `_parse_data_json`, `_ts_to_iso` |
+| `auth_service` | `setup_service` | L23 | Top-level import |
+| `config_service` | `setup_service` | L47 | Top-level import |
+| `config_service` | `health_service` | L891 | Lazy import inside function |
+| `config_file_service` | `jail_service` | L57–58 | Top-level import + re-export of `JailNotFoundError` |
+| `blocklist_service` | `jail_service` | L299 | Lazy import |
+| `blocklist_service` | `geo_service` | L343 | Lazy import |
+| `jail_service` | `geo_service` | L860, L1047 | Lazy import (2 sites) |
+| `ban_service` | `geo_service` | L251, L392 | Lazy import (2 sites) |
+| `history_service` | `geo_service` | L19 | TYPE_CHECKING import |
+
+**Impact**: Circular dependency risk; lazy imports hide coupling; private function imports create fragile links between services.
+
+**Recommendation**:
+- Extract `_get_fail2ban_db_path()`, `_parse_data_json()`, `_ts_to_iso()` from `ban_service` to `app/utils/fail2ban_db_utils.py` (shared utility).
+- Pass geo-enrichment as a callback parameter instead of each service importing `geo_service` directly. The router or dependency layer should wire this.
+- Where services depend on another service's domain exceptions (e.g., `JailNotFoundError`), move exceptions to `app/models/` or a shared `app/exceptions.py`.
 
 ---
 
-## 1. Before You Start
+## 2. God Modules (Backend)
 
-### 1.1 Understand the project
+Several service files far exceed a reasonable size for a single-domain module:
 
-Read the following documents in order:
+| File | Lines | Functions | Issue |
+|---|---|---|---|
+| `config_file_service.py` | **3105** | **73** | Handles jails, filters, and actions — three distinct domains crammed into one file |
+| `jail_service.py` | **1382** | **34** | Manages jail listing, status, controls, banned-IP queries, and geo enrichment |
+| `config_service.py` | **921** | ~20 | Socket-based config, log preview, regex testing, and service status |
+| `file_config_service.py` | **1011** | ~20 | Raw file I/O for jails, filters, and actions |
 
-1. [Architekture.md](Architekture.md) — full system overview, component map, module purposes, dependency rules.
-2. [Docs/Backend-Development.md](Backend-Development.md) — coding conventions, testing strategy, environment setup.
-3. [Docs/Tasks.md](Tasks.md) — open issues and planned work; avoid touching areas that have pending conflicting changes.
+**Recommendation**:
+- Split `config_file_service.py` into `filter_config_service.py`, `action_config_service.py`, and a slimmed-down `jail_config_service.py`.
+- Extract log-preview / regex-test functionality from `config_service.py` into a dedicated `log_service.py`.
 
-### 1.2 Map the code to the architecture
+---
 
-Before editing, locate every file that is in scope:
+## 3. Confusing Config Service Naming (Backend)
 
-```
-backend/app/
-  routers/          HTTP layer — zero business logic
-  services/         Business logic — orchestrates repositories + clients
-  repositories/     Data access — raw SQL only
-  models/           Pydantic schemas
-  tasks/            APScheduler jobs
-  utils/            Pure helpers, no framework deps
-  main.py           App factory, lifespan, middleware
-  config.py         Pydantic settings
-  dependencies.py   FastAPI Depends() wiring
+Three services with overlapping names handle different aspects of configuration, causing developer confusion:
 
-frontend/src/
-  api/              Typed fetch wrappers + endpoint constants
-  components/       Presentational UI, no API calls
-  hooks/            All state, side-effects, API calls
-  pages/            Route components — orchestration only
-  providers/        React context
-  types/            TypeScript interfaces
-  utils/            Pure helpers
+| Current Name | Purpose |
+|---|---|
+| `config_service` | Read/write via the fail2ban **socket** |
+| `config_file_service` | Parse/activate/deactivate jails from **files on disk** |
+| `file_config_service` | **Raw file I/O** for jail/filter/action `.conf` files |
+
+`config_file_service` vs `file_config_service` differ only by word order, making it easy to import the wrong one.
+
+**Recommendation**: Rename for clarity:
+- `config_service` → keep (socket-based)
+- `config_file_service` → `jail_activation_service` (its main job is activating/deactivating jails)
+- `file_config_service` → `raw_config_io_service` or merge into `config_file_service`
+
+---
+
+## 4. Architecture Doc Drift
+
+The architecture doc does not fully reflect the current codebase:
+
+| Category | In Architecture Doc | Actually Exists | Notes |
+|---|---|---|---|
+| Repositories | 4 listed | **6 files** | `fail2ban_db_repo.py` and `geo_cache_repo.py` are missing from the doc |
+| Utils | 4 listed | **8 files** | `conffile_parser.py`, `config_parser.py`, `config_writer.py`, `jail_config.py` are undocumented |
+| Tasks | 3 listed | **4 files** | `geo_re_resolve.py` is missing from the doc |
+| Services | `conffile_parser` listed as a service | Actually in `app/utils/` | Doc says "Services" but the file is in `utils/` |
+| Routers | `file_config.py` not listed | Exists | Missing from router table |
+
+**Recommendation**: Update the Architecture doc to reflect the actual file inventory.
+
+---
+
+## 5. Shared Private Functions Cross Service Boundary (Backend)
+
+`history_service.py` imports three **underscore-prefixed** ("private") functions from `ban_service.py`:
+
+```python
+from app.services.ban_service import _get_fail2ban_db_path, _parse_data_json, _ts_to_iso
 ```
 
-Confirm which layer every file you intend to touch belongs to. If unsure, consult [Architekture.md §2.2](Architekture.md) (backend) or [Architekture.md §3.2](Architekture.md) (frontend).
+These are implementation details of `ban_service` that should not be consumed externally. Their `_` prefix signals they are not part of the public API.
 
-### 1.3 Run the baseline
-
-```bash
-# Backend
-pytest backend/ -x --tb=short
-
-# Frontend
-cd frontend && npm run test
-```
-
-Record the number of passing tests. After refactoring, that number must be equal or higher.
+**Recommendation**: Move these to `app/utils/fail2ban_db_utils.py` as public functions and import from there in both services.
 
 ---
 
-## 2. Backend Refactoring
+## 6. Missing Error Boundaries (Frontend)
 
-### 2.1 Routers (`app/routers/`)
+No React Error Boundary component exists anywhere in the frontend. A single unhandled exception in any component will crash the entire application with a white screen.
 
-**Allowed content:** request parsing, response serialisation, dependency injection via `Depends()`, delegation to a service, HTTP error mapping.  
-**Forbidden content:** SQL queries, business logic, direct use of `fail2ban_client`, any logic that would also make sense in a unit test without an HTTP request.
-
-Checklist:
-- [ ] Every handler calls exactly one service method per logical operation.
-- [ ] No `if`/`elif` chains that implement business rules — move these to the service.
-- [ ] No raw SQL or repository imports.
-- [ ] All response models are Pydantic schemas from `app/models/`.
-- [ ] HTTP status codes are consistent with API conventions (200 OK, 201 Created, 204 No Content, 400/422 for client errors, 404 for missing resources, 500 only for unexpected failures).
-
-### 2.2 Services (`app/services/`)
-
-**Allowed content:** business rules, coordination between repositories and external clients, validation that goes beyond Pydantic, fail2ban command orchestration.  
-**Forbidden content:** raw SQL, direct aiosqlite calls, FastAPI `HTTPException` (raise domain exceptions instead and let the router or exception handler convert them).
-
-Checklist:
-- [ ] Service classes / functions accept plain Python types or domain models — not `Request` or `Response` objects.
-- [ ] No direct `aiosqlite` usage — go through a repository.
-- [ ] No `HTTPException` — raise a custom domain exception or a plain `ValueError`/`RuntimeError` with a clear message.
-- [ ] No circular imports between services — if two services need each other's logic, extract the shared logic to a utility or a third service.
-
-### 2.3 Repositories (`app/repositories/`)
-
-**Allowed content:** SQL queries, result mapping to domain models, transaction management.  
-**Forbidden content:** business logic, fail2ban calls, HTTP concerns, logging beyond debug-level traces.
-
-Checklist:
-- [ ] Every public method accepts a `db: aiosqlite.Connection` parameter — sessions are not managed internally.
-- [ ] Methods return typed domain models or plain Python primitives, never raw `aiosqlite.Row` objects exposed to callers.
-- [ ] No business rules (e.g., no "if this setting is missing, create a default" logic — that belongs in the service).
-
-### 2.4 Models (`app/models/`)
-
-- Keep **Request**, **Response**, and **Domain** model types clearly separated (see [Architekture.md §2.2](Architekture.md)).
-- Do not use response models as function arguments inside service or repository code.
-- Validators (`@field_validator`, `@model_validator`) belong in models only when they concern data shape, not business rules.
-
-### 2.5 Tasks (`app/tasks/`)
-
-- Tasks must be thin: fetch inputs → call one service method → log result.
-- Error handling must be inside the task (APScheduler swallows unhandled exceptions — log them explicitly).
-- No direct repository or `fail2ban_client` use; go through a service.
-
-### 2.6 Utils (`app/utils/`)
-
-- Must have zero framework dependencies (no FastAPI, no aiosqlite imports).
-- Must be pure or near-pure functions.
-- `fail2ban_client.py` is the single exception — it wraps the socket protocol but still has no service-layer logic.
-
-### 2.7 Dependencies (`app/dependencies.py`)
-
-- This file is the **only** place where service constructors are called and injected.
-- Do not construct services inside router handlers; always receive them via `Depends()`.
+**Recommendation**: Add an `<ErrorBoundary>` wrapper in `MainLayout.tsx` or `App.tsx` with a fallback UI that shows the error and offers a retry/reload.
 
 ---
 
-## 3. Frontend Refactoring
+## 7. Duplicated Formatting Functions (Frontend)
 
-### 3.1 Pages (`src/pages/`)
+Several formatting functions are independently defined in multiple files instead of being shared:
 
-**Allowed content:** composing components and hooks, layout decisions, routing.  
-**Forbidden content:** direct `fetch`/`axios` calls, inline business logic, state management beyond what is needed to coordinate child components.
-
-Checklist:
-- [ ] All data fetching goes through a hook from `src/hooks/`.
-- [ ] No API function from `src/api/` is called directly inside a page component.
-
-### 3.2 Components (`src/components/`)
-
-**Allowed content:** rendering, styling, event handlers that call prop callbacks.  
-**Forbidden content:** API calls, hook-level state (prefer lifting state to the page or a dedicated hook), direct use of `src/api/`.
-
-Checklist:
-- [ ] Components receive all data via props.
-- [ ] Components emit changes via callback props (`onXxx`).
-- [ ] No `useEffect` that calls an API function — that belongs in a hook.
-
-### 3.3 Hooks (`src/hooks/`)
-
-**Allowed content:** `useState`, `useEffect`, `useCallback`, `useRef`; calls to `src/api/`; local state derivation.  
-**Forbidden content:** JSX rendering, Fluent UI components.
-
-Checklist:
-- [ ] Each hook has a single, focused concern matching its name (e.g., `useBans` only manages ban data).
-- [ ] Hooks return a stable interface: `{ data, loading, error, refetch }` or equivalent.
-- [ ] Shared logic between hooks is extracted to `src/utils/` (pure) or a parent hook (stateful).
-
-### 3.4 API layer (`src/api/`)
-
-- `client.ts` is the only place that calls `fetch`. All other api files call `client.ts`.
-- `endpoints.ts` is the single source of truth for URL strings.
-- API functions must be typed: explicit request and response TypeScript interfaces from `src/types/`.
-
-### 3.5 Types (`src/types/`)
-
-- Interfaces must match the backend Pydantic response schemas exactly (field names, optionality).
-- Do not use `any`. Use `unknown` and narrow with type guards when the shape is genuinely unknown.
-
----
-
-## 4. General Code Quality Rules
-
-### Naming
-- Python: `snake_case` for variables/functions, `PascalCase` for classes.
-- TypeScript: `camelCase` for variables/functions, `PascalCase` for components and types.
-- File names must match the primary export they contain.
-
-### Error handling
-- Backend: raise typed exceptions; map them to HTTP status codes in `main.py` exception handlers or in the router — nowhere else.
-- Frontend: all API call error states are represented in hook return values; never swallow errors silently.
-
-### Logging (backend)
-- Use `structlog` with bound context loggers — never bare `print()`.
-- Log at `debug` in repositories, `info` in services for meaningful events, `warning`/`error` in tasks and exception handlers.
-- Never log sensitive data (passwords, session tokens, raw IP lists larger than a handful of entries).
-
-### Async correctness (backend)
-- Every function that touches I/O (database, fail2ban socket, HTTP) must be `async def`.
-- Never call `asyncio.run()` inside a running event loop.
-- Do not use `time.sleep()` — use `await asyncio.sleep()`.
-
----
-
-## 5. Refactoring Workflow
-
-Follow this sequence for every refactoring task:
-
-1. **Read** the relevant section of [Architekture.md](Architekture.md) for the files you will touch.
-2. **Run** the full test suite to confirm the baseline.
-3. **Identify** the violation or smell: which rule from this document does it break?
-4. **Plan** the minimal change: what is the smallest edit that fixes the violation?
-5. **Edit** the code. One logical change per commit.
-6. **Verify** imports: nothing new violates the dependency direction.
-7. **Run** the full test suite. All previously passing tests must still pass.
-8. **Update** any affected docstrings or inline comments to reflect the new structure.
-9. **Do not** update `Architekture.md` unless the refactor changes the documented structure — that requires a separate review.
-
----
-
-## 6. Common Violations to Look For
-
-| Violation | Where it typically appears | Fix |
+| Function | Defined In | Also In |
 |---|---|---|
-| Business logic in a router handler | `app/routers/*.py` | Extract logic to the corresponding service |
-| Direct `aiosqlite` calls in a service | `app/services/*.py` | Move the query into the matching repository |
-| `HTTPException` raised inside a service | `app/services/*.py` | Raise a domain exception; catch and convert it in the router or exception handler |
-| API call inside a React component | `src/components/*.tsx` | Move to a hook; pass data via props |
-| Hardcoded URL string in a hook or component | `src/hooks/*.ts`, `src/components/*.tsx` | Use the constant from `src/api/endpoints.ts` |
-| `any` type in TypeScript | anywhere in `src/` | Replace with a concrete interface from `src/types/` |
-| `print()` statements in production code | `backend/app/**/*.py` | Replace with `structlog` logger |
-| Synchronous I/O in an async function | `backend/app/**/*.py` | Use the async equivalent |
-| A repository method that contains an `if` with a business rule | `app/repositories/*.py` | Move the rule to the service layer |
+| `formatTimestamp()` | `BanTable.tsx` (L103) | — (but `fmtTime()` in `BannedIpsSection.tsx` does the same thing) |
+| `fmtSeconds()` | `JailDetailPage.tsx` (L152) | `JailsPage.tsx` (L147) — identical |
+| `fmtTime()` | `BannedIpsSection.tsx` (L139) | — |
+
+**Recommendation**: Consolidate into `src/utils/formatDate.ts` and import from there.
 
 ---
 
-## 7. Out of Scope
+## 8. Duplicated Hook Logic (Frontend)
 
-Do not make the following changes unless explicitly instructed in a separate task:
+Three hooks follow an identical fetch-then-save pattern with near-identical code:
 
-- Adding new API endpoints or pages.
-- Changing database schema or migration files.
-- Upgrading dependencies.
-- Altering Docker or CI configuration.
-- Modifying `Architekture.md` or `Tasks.md`.
+| Hook | Lines | Pattern |
+|---|---|---|
+| `useFilterConfig.ts` | 91 | Load item → expose save → handle abort |
+| `useActionConfig.ts` | 89 | Load item → expose save → handle abort |
+| `useJailFileConfig.ts` | 76 | Load item → expose save → handle abort |
+
+**Recommendation**: Create a generic `useConfigItem<T>()` hook that takes `fetchFn` and `saveFn` parameters and eliminates the triplication.
+
+---
+
+## 9. Inconsistent Error Handling in Hooks (Frontend)
+
+Hooks handle errors differently:
+
+- Some filter out `AbortError` (e.g., `useHistory`, `useMapData`)
+- Others catch all errors indiscriminately (e.g., `useBans`, `useBlocklist`)
+
+This means some hooks surface spurious "request aborted" errors to the UI while others don't.
+
+**Recommendation**: Standardise a shared error-catching pattern, e.g. a `handleFetchError(err, setError)` utility that always filters `AbortError`.
+
+---
+
+## 10. No Global Request State / Caching (Frontend)
+
+Each hook manages its own loading/error/data state independently. There is:
+- No request deduplication (two components fetching the same data trigger two requests)
+- No stale-while-revalidate caching
+- No automatic background refetching
+
+**Recommendation**: Consider adopting React Query (TanStack Query) or SWR for data-fetching hooks. This would eliminate boilerplate in every hook (abort handling, loading state, error state, caching) and provide automatic deduplication.
+
+---
+
+## 11. Large Frontend Components
+
+| Component | Lines | Issue |
+|---|---|---|
+| `BlocklistsPage.tsx` | 968 | Page does a lot: source list, add/edit dialogs, import log, schedule config |
+| `JailsTab.tsx` | 939 | Combines jail list, config editing, raw config, validation, activate/deactivate |
+| `JailsPage.tsx` | 691 | Mixes jail table, detail drawer, ban/unban forms |
+| `JailDetailPage.tsx` | 663 | Full detail view with multiple sections |
+
+**Recommendation**: Extract sub-sections into focused child components. For example, `JailsTab.tsx` could delegate to `<JailConfigEditor>`, `<JailValidation>`, and `<JailActivateDialog>`.
+
+---
+
+## 12. Duplicated Section Styles (Frontend)
+
+The same card/section styling pattern (`backgroundColor`, `borderRadius`, `border`, `padding` using Fluent UI tokens) is repeated across 13+ files. Each page recreates it in its own `makeStyles` block.
+
+**Recommendation**: Define a shared `useCardStyles()` or export a `sectionStyle` in `src/theme/commonStyles.ts` and import it.
+
+---
+
+## Summary by Priority
+
+| Priority | Issue | Section |
+|---|---|---|
+| **High** | Service-to-service coupling / circular deps | §1 |
+| **High** | God module `config_file_service.py` (3105 lines, 73 functions) | §2 |
+| **High** | Shared private function imports across services | §5 |
+| **Medium** | Confusing config service naming | §3 |
+| **Medium** | Architecture doc drift | §4 |
+| **Medium** | Missing error boundaries (frontend) | §6 |
+| **Medium** | No global request state / caching (frontend) | §10 |
+| **Low** | Duplicated formatting functions (frontend) | §7 |
+| **Low** | Duplicated hook logic (frontend) | §8 |
+| **Low** | Inconsistent error handling in hooks (frontend) | §9 |
+| **Low** | Large frontend components | §11 |
+| **Low** | Duplicated section styles (frontend) | §12 |

Docs/Tasks.md

@@ -2,6 +2,314 @@
 
 This document breaks the entire BanGUI project into development stages, ordered so that each stage builds on the previous one. Every task is described in prose with enough detail for a developer to begin work. References point to the relevant documentation.
 
+Reference: `Docs/Refactoring.md` for full analysis of each issue.
+
 ---
 
 ## Open Issues
+
+---
+
+### Task 1 — Extract shared private functions to a utility module (✅ completed)
+
+**Priority**: High  
+**Refactoring ref**: Refactoring.md §1, §5  
+**Affected files**:
+- `backend/app/services/ban_service.py` (defines `_get_fail2ban_db_path` ~L117, `_parse_data_json` ~L152, `_ts_to_iso` ~L105)
+- `backend/app/services/history_service.py` (imports these three private functions from `ban_service`)
+
+**What to do**:
+1. Create a new file `backend/app/utils/fail2ban_db_utils.py`.
+2. Move the three functions `_get_fail2ban_db_path()`, `_parse_data_json()`, and `_ts_to_iso()` from `backend/app/services/ban_service.py` into the new utility file. Rename them to remove the leading underscore (they are now public utilities): `get_fail2ban_db_path()`, `parse_data_json()`, `ts_to_iso()`.
+3. In `backend/app/services/ban_service.py`, replace the function bodies with imports from the new utility: `from app.utils.fail2ban_db_utils import get_fail2ban_db_path, parse_data_json, ts_to_iso`. Update all internal call sites within `ban_service.py` that reference the old `_`-prefixed names.
+4. In `backend/app/services/history_service.py`, replace the import `from app.services.ban_service import _get_fail2ban_db_path, _parse_data_json, _ts_to_iso` with `from app.utils.fail2ban_db_utils import get_fail2ban_db_path, parse_data_json, ts_to_iso`. Update all call sites in `history_service.py`.
+5. Search the entire `backend/` tree for any other references to the old `_`-prefixed names and update them.
+6. Run existing tests: `cd backend && python -m pytest tests/` — all tests must pass.
+
+**Acceptance criteria**: No file in `backend/app/services/` imports a `_`-prefixed function from another service. The three functions live in `backend/app/utils/fail2ban_db_utils.py` and are imported from there.
+
+---
+
+### Task 2 — Decouple geo-enrichment from services (✅ completed)
+
+**Priority**: High  
+**Refactoring ref**: Refactoring.md §1  
+**Affected files**:
+- `backend/app/services/jail_service.py` (lazy imports `geo_service` at ~L860, ~L1047)
+- `backend/app/services/ban_service.py` (lazy imports `geo_service` at ~L251, ~L392)
+- `backend/app/services/blocklist_service.py` (lazy imports `geo_service` at ~L343)
+- `backend/app/services/history_service.py` (TYPE_CHECKING import of `geo_service` at ~L19)
+- `backend/app/services/geo_service.py` (the service being imported)
+- Router files that call these services: `backend/app/routers/jails.py`, `backend/app/routers/bans.py`, `backend/app/routers/dashboard.py`, `backend/app/routers/history.py`, `backend/app/routers/blocklist.py`
+
+**What to do**:
+1. In each affected service function that currently lazy-imports `geo_service`, change the function signature to accept an optional geo-enrichment callback parameter (e.g., `enrich_geo: Callable | None = None`). The callback signature should match what `geo_service` provides (typically `async def enrich(ip: str) -> GeoInfo | None`).
+2. Remove all lazy imports of `geo_service` from `jail_service.py`, `ban_service.py`, `blocklist_service.py`, and `history_service.py`.
+3. In the corresponding router files, import `geo_service` and pass its enrichment function as the callback when calling the service functions. The router layer is where wiring belongs.
+4. Run existing tests: `cd backend && python -m pytest tests/` — all tests must pass. If tests mock `geo_service` inside a service, update mocks to inject the callback instead.
+
+**Acceptance criteria**: No service file imports `geo_service` (directly or lazily). Geo-enrichment is injected from routers via callback parameters.
+
+---
+
+### Task 3 — Move shared domain exceptions to a central module (✅ completed)
+
+**Priority**: High  
+**Refactoring ref**: Refactoring.md §1  
+**Affected files**:
+- `backend/app/services/config_file_service.py` (defines `JailNotFoundError` and other domain exceptions)
+- `backend/app/services/jail_service.py` (may define or re-export exceptions)
+- Any service or router that imports exceptions cross-service (e.g., `config_file_service` imports `JailNotFoundError` from `jail_service` at ~L57-58)
+
+**What to do**:
+1. Create `backend/app/exceptions.py`.
+2. Grep the entire `backend/app/services/` directory for all custom exception class definitions (classes inheriting from `Exception` or `HTTPException`). Collect every exception that is imported by more than one module.
+3. Move those shared exception classes into `backend/app/exceptions.py`.
+4. Update all import statements across `backend/app/services/`, `backend/app/routers/`, and `backend/app/` to import from `backend/app/exceptions.py`.
+5. Exception classes used only within a single service may remain in that service file.
+6. Run existing tests: `cd backend && python -m pytest tests/` — all tests must pass.
+
+**Acceptance criteria**: `backend/app/exceptions.py` exists and contains all cross-service exceptions. No service imports an exception class from another service module.
+
+---
+
+### Task 4 — Split `config_file_service.py` (god module)
+
+**Priority**: High  
+**Refactoring ref**: Refactoring.md §2  
+**Affected files**:
+- `backend/app/services/config_file_service.py` (~2232 lines, ~73 functions)
+- `backend/app/routers/` files that import from `config_file_service`
+
+**What to do**:
+1. Read `backend/app/services/config_file_service.py` and categorise every function into one of three domains:
+   - **Jail config** — functions dealing with jail activation, deactivation, listing jail configs
+   - **Filter config** — functions dealing with fail2ban filter files (reading, writing, listing filters)
+   - **Action config** — functions dealing with fail2ban action files (reading, writing, listing actions)
+2. Create three new service files:
+   - `backend/app/services/jail_config_service.py` — jail-related functions
+   - `backend/app/services/filter_config_service.py` — filter-related functions
+   - `backend/app/services/action_config_service.py` — action-related functions
+3. Move functions from `config_file_service.py` into the appropriate new file. Any truly shared helpers used across all three domains should remain in `config_file_service.py` (renamed to a shared helper) or move to `backend/app/utils/`.
+4. Delete `config_file_service.py` once empty (or keep it as a thin re-export layer for backward compatibility during transition).
+5. Update all imports in `backend/app/routers/` and `backend/app/services/` that referenced `config_file_service`.
+6. Run existing tests: `cd backend && python -m pytest tests/` — all tests must pass.
+
+**Acceptance criteria**: No single service file exceeds ~800 lines. The three new files each handle one domain. All routers import from the correct new module.
+
+---
+
+### Task 5 — Extract log-preview / regex-test from `config_service.py`
+
+**Priority**: Medium  
+**Refactoring ref**: Refactoring.md §2  
+**Affected files**:
+- `backend/app/services/config_service.py` (~1845 lines)
+- `backend/app/routers/config.py` (routes that call log-preview / regex-test functions)
+
+**What to do**:
+1. Read `backend/app/services/config_service.py` and identify all functions related to log-preview and regex-testing (these are distinct from the core socket-based config reading/writing functions).
+2. Create `backend/app/services/log_service.py`.
+3. Move the log-preview and regex-test functions into `log_service.py`.
+4. Update imports in `backend/app/routers/config.py` (or create a new `backend/app/routers/log.py` if the endpoints are logically separate).
+5. Run existing tests: `cd backend && python -m pytest tests/` — all tests must pass.
+
+**Acceptance criteria**: `config_service.py` no longer contains log-preview or regex-test logic. `log_service.py` exists and is used by the appropriate router.
+
+---
+
+### Task 6 — Rename confusing config service files
+
+**Priority**: Medium  
+**Refactoring ref**: Refactoring.md §3  
+**Affected files**:
+- `backend/app/services/config_file_service.py` → rename to `jail_activation_service.py` (or the split modules from Task 4)
+- `backend/app/services/file_config_service.py` → rename to `raw_config_io_service.py`
+- All files importing from the old names
+
+**Note**: This task depends on Task 4 being completed first. If Task 4 splits `config_file_service.py`, this task only needs to rename `file_config_service.py`.
+
+**What to do**:
+1. Rename `backend/app/services/file_config_service.py` to `backend/app/services/raw_config_io_service.py`.
+2. Update all import statements across the codebase (`backend/app/services/`, `backend/app/routers/`, `backend/app/tasks/`, tests) that reference `file_config_service` to reference `raw_config_io_service`.
+3. Also rename the corresponding router if one exists: check `backend/app/routers/file_config.py` and rename accordingly.
+4. Run existing tests: `cd backend && python -m pytest tests/` — all tests must pass.
+
+**Acceptance criteria**: No file named `file_config_service.py` exists. The new name `raw_config_io_service.py` is used everywhere.
+
+---
+
+### Task 7 — Remove remaining service-to-service coupling
+
+**Priority**: Medium  
+**Refactoring ref**: Refactoring.md §1  
+**Affected files**:
+- `backend/app/services/auth_service.py` (imports `setup_service` at ~L23)
+- `backend/app/services/config_service.py` (imports `setup_service` at ~L47, lazy-imports `health_service` at ~L891)
+- `backend/app/services/blocklist_service.py` (lazy-imports `jail_service` at ~L299)
+
+**What to do**:
+1. For each remaining service-to-service import, determine why the dependency exists (read the calling code).
+2. Refactor using one of these strategies:
+   - **Dependency injection**: The router passes the needed data or function from service A when calling service B.
+   - **Shared utility**: If the imported function is a pure utility, move it to `backend/app/utils/`.
+   - **Event / callback**: The service accepts a callback parameter instead of importing another service directly.
+3. Remove all direct and lazy imports between service modules.
+4. Run existing tests: `cd backend && python -m pytest tests/` — all tests must pass.
+
+**Acceptance criteria**: Running `grep -r "from app.services" backend/app/services/` returns zero results (no service imports another service). All wiring happens in the router or dependency-injection layer.
+
+---
+
+### Task 8 — Update Architecture documentation
+
+**Priority**: Medium  
+**Refactoring ref**: Refactoring.md §4  
+**Affected files**:
+- `Docs/Architekture.md`
+
+**What to do**:
+1. Read `Docs/Architekture.md` and the actual file listings below.
+2. Add the following missing items to the appropriate sections:
+   - **Repositories**: Add `fail2ban_db_repo.py` and `geo_cache_repo.py` (in `backend/app/repositories/`)
+   - **Utils**: Add `conffile_parser.py`, `config_parser.py`, `config_writer.py`, `jail_config.py` (in `backend/app/utils/`)
+   - **Tasks**: Add `geo_re_resolve.py` (in `backend/app/tasks/`)
+   - **Services**: Correct the entry that lists `conffile_parser` as a service — it is in `app/utils/`
+   - **Routers**: Add `file_config.py` (in `backend/app/routers/`)
+3. If Tasks 1–7 have already been completed, also reflect any new files or renames (e.g., `fail2ban_db_utils.py`, `exceptions.py`, the split service files, renamed services).
+4. Verify no other files exist that are missing from the doc by comparing the doc's file lists against `ls backend/app/*/`.
+
+**Acceptance criteria**: Every `.py` file under `backend/app/` (excluding `__init__.py` and `__pycache__`) is mentioned in the Architecture doc.
+
+---
+
+### Task 9 — Add React Error Boundary to the frontend
+
+**Priority**: Medium  
+**Refactoring ref**: Refactoring.md §6  
+**Affected files**:
+- New file: `frontend/src/components/ErrorBoundary.tsx`
+- `frontend/src/App.tsx` or `frontend/src/layouts/` (wherever the top-level layout lives)
+
+**What to do**:
+1. Create `frontend/src/components/ErrorBoundary.tsx` — a React class component implementing `componentDidCatch` and `getDerivedStateFromError`. It should:
+   - Catch any rendering error in its children.
+   - Display a user-friendly fallback UI (e.g., "Something went wrong" message with a "Reload" button that calls `window.location.reload()`).
+   - Log the error (console.error is sufficient for now).
+2. Read `frontend/src/App.tsx` to find the main layout/route wrapper.
+3. Wrap the main content (inside `<App>` or `<MainLayout>`) with `<ErrorBoundary>` so that any component crash shows the fallback instead of a white screen.
+4. Run existing frontend tests: `cd frontend && npx vitest run` — all tests must pass.
+
+**Acceptance criteria**: An `<ErrorBoundary>` component exists and wraps the application's main content. A component throwing during render shows a fallback UI instead of crashing the whole app.
+
+---
+
+### Task 10 — Consolidate duplicated formatting functions (frontend)
+
+**Priority**: Low  
+**Refactoring ref**: Refactoring.md §7  
+**Affected files**:
+- `frontend/src/components/BanTable.tsx` (has `formatTimestamp()` ~L103)
+- `frontend/src/components/jail/BannedIpsSection.tsx` (has `fmtTime()` ~L139)
+- `frontend/src/pages/JailDetailPage.tsx` (has `fmtSeconds()` ~L152)
+- `frontend/src/pages/JailsPage.tsx` (has `fmtSeconds()` ~L147)
+
+**What to do**:
+1. Create `frontend/src/utils/formatDate.ts`.
+2. Define three exported functions:
+   - `formatTimestamp(ts: string): string` — consolidation of `formatTimestamp` and `fmtTime`
+   - `formatSeconds(seconds: number): string` — consolidation of the two identical `fmtSeconds` functions
+3. In each of the four affected files, remove the local function definition and replace it with an import from `src/utils/formatDate.ts`. Adjust call sites if the function name changed.
+4. Run existing frontend tests: `cd frontend && npx vitest run` — all tests must pass.
+
+**Acceptance criteria**: No formatting function for dates/times is defined locally in a component or page file. All import from `src/utils/formatDate.ts`.
+
+---
+
+### Task 11 — Create generic `useConfigItem<T>` hook (frontend)
+
+**Priority**: Low  
+**Refactoring ref**: Refactoring.md §8  
+**Affected files**:
+- `frontend/src/hooks/useFilterConfig.ts` (~91 lines)
+- `frontend/src/hooks/useActionConfig.ts` (~88 lines)
+- `frontend/src/hooks/useJailFileConfig.ts` (~76 lines)
+
+**What to do**:
+1. Read all three hook files. Identify the common pattern: load item via fetch → store in state → expose save function → handle abort controller cleanup.
+2. Create `frontend/src/hooks/useConfigItem.ts` with a generic hook:
+   ```ts
+   function useConfigItem<T>(
+     fetchFn: (signal: AbortSignal) => Promise<T>,
+     saveFn: (data: T) => Promise<void>
+   ): { data: T | null; loading: boolean; error: string | null; save: (data: T) => Promise<void> }
+   ```
+3. Rewrite `useFilterConfig.ts`, `useActionConfig.ts`, and `useJailFileConfig.ts` to be thin wrappers around `useConfigItem<T>` — each file should be <20 lines, just providing the specific fetch/save functions.
+4. Run existing frontend tests: `cd frontend && npx vitest run` — all tests must pass.
+
+**Acceptance criteria**: `useConfigItem.ts` exists. The three original hooks use it and each reduced to <20 lines of domain-specific glue.
+
+---
+
+### Task 12 — Standardise error handling in frontend hooks
+
+**Priority**: Low  
+**Refactoring ref**: Refactoring.md §9  
+**Affected files**:
+- All hook files in `frontend/src/hooks/` that do fetch calls (at least: `useHistory.ts`, `useMapData.ts`, `useBans.ts`, `useBlocklist.ts`, and others)
+
+**What to do**:
+1. Create a utility function in `frontend/src/utils/fetchError.ts`:
+   ```ts
+   export function handleFetchError(err: unknown, setError: (msg: string | null) => void): void {
+     if (err instanceof DOMException && err.name === "AbortError") return;
+     setError(err instanceof Error ? err.message : "Unknown error");
+   }
+   ```
+2. Grep all hook files for `catch` blocks. In every hook that catches fetch errors:
+   - Replace the catch body with a call to `handleFetchError(err, setError)`.
+3. Run existing frontend tests: `cd frontend && npx vitest run` — all tests must pass.
+
+**Acceptance criteria**: Every hook that fetches data uses `handleFetchError()` in its catch block. No hook surfaces `AbortError` to the UI.
+
+---
+
+### Task 13 — Extract sub-components from large frontend pages
+
+**Priority**: Low  
+**Refactoring ref**: Refactoring.md §11  
+**Affected files**:
+- `frontend/src/pages/BlocklistsPage.tsx` (~968 lines)
+- `frontend/src/components/config/JailsTab.tsx` (~939 lines)
+- `frontend/src/pages/JailsPage.tsx` (~691 lines)
+- `frontend/src/pages/JailDetailPage.tsx` (~663 lines)
+
+**What to do**:
+1. For each large file, identify logical UI sections that can be extracted into their own component files.
+2. Suggested splits (adjust after reading the actual code):
+   - **BlocklistsPage.tsx**: Extract `<BlocklistSourceList>`, `<BlocklistAddEditDialog>`, `<BlocklistImportLog>`, `<BlocklistScheduleConfig>`.
+   - **JailsTab.tsx**: Extract `<JailConfigEditor>`, `<JailRawConfig>`, `<JailValidation>`, `<JailActivateDialog>`.
+   - **JailsPage.tsx**: Extract `<JailDetailDrawer>`, `<BanUnbanForm>`.
+   - **JailDetailPage.tsx**: Extract logical sections (examine the JSX to identify).
+3. Place extracted components in appropriate directories (e.g., `frontend/src/components/blocklist/`, `frontend/src/components/jail/`).
+4. Each parent page should import and compose the new child components. Props should be passed down — avoid prop drilling deeper than 2 levels (use context if needed).
+5. Run existing frontend tests: `cd frontend && npx vitest run` — all tests must pass.
+
+**Acceptance criteria**: No single page or component file exceeds ~400 lines. Each extracted component is in its own file.
+
+---
+
+### Task 14 — Consolidate duplicated section/card styles (frontend)
+
+**Priority**: Low  
+**Refactoring ref**: Refactoring.md §12  
+**Affected files**:
+- 13+ files across `frontend/src/pages/` and `frontend/src/components/` that define identical card/section styles using `makeStyles` with `backgroundColor`, `borderRadius`, `border`, `padding` using Fluent UI tokens.
+
+**What to do**:
+1. Grep the frontend codebase for `makeStyles` calls that contain `backgroundColor` and `borderRadius` together. Identify the common pattern.
+2. Create `frontend/src/theme/commonStyles.ts` with a shared `useCardStyles()` hook that exports the common section/card style class.
+3. In each of the 13+ files, remove the local `makeStyles` definition for the card/section style and import `useCardStyles` from `commonStyles.ts` instead. Keep any file-specific style overrides local.
+4. Run existing frontend tests: `cd frontend && npx vitest run` — all tests must pass.
+
+**Acceptance criteria**: A shared `useCardStyles()` exists in `frontend/src/theme/commonStyles.ts`. At least 10 files import it instead of defining their own card styles.