feat: Stage 1 — backend and frontend scaffolding

Backend (tasks 1.1, 1.5–1.8):
- pyproject.toml with FastAPI, Pydantic v2, aiosqlite, APScheduler 3.x,
  structlog, bcrypt; ruff + mypy strict configured
- Pydantic Settings (BANGUI_ prefix env vars, fail-fast validation)
- SQLite schema: settings, sessions, blocklist_sources, import_log;
  WAL mode + foreign keys; idempotent init_db()
- FastAPI app factory with lifespan (DB, aiohttp session, scheduler),
  CORS, unhandled-exception handler, GET /api/health
- Fail2BanClient: async Unix-socket wrapper using run_in_executor,
  custom error types, async context manager
- Utility modules: ip_utils, time_utils, constants
- 47 tests; ruff 0 errors; mypy --strict 0 errors

Frontend (tasks 1.2–1.4):
- Vite + React 18 + TypeScript strict; Fluent UI v9; ESLint + Prettier
- Custom brand theme (#0F6CBD, WCAG AA contrast) with light/dark variants
- Typed fetch API client (ApiError, get/post/put/del) + endpoints constants
- tsc --noEmit 0 errors

frontend/src/api/client.ts

@@ -0,0 +1,137 @@
+/**
+ * Central typed API client.
+ *
+ * This is the single point of contact between the frontend and the BanGUI
+ * backend. Components and hooks never call `fetch` directly — they use the
+ * functions exported from domain-specific API modules (e.g. `api/bans.ts`),
+ * which call the helpers exported from this file.
+ *
+ * All request and response types are defined in `src/types/` and used here
+ * to guarantee type safety at the API boundary.
+ */
+
+import { ENDPOINTS } from "./endpoints";
+
+/** Base URL for all API calls. Falls back to `/api` in production. */
+const BASE_URL: string = import.meta.env.VITE_API_URL ?? "/api";
+
+// ---------------------------------------------------------------------------
+// Error type
+// ---------------------------------------------------------------------------
+
+/** Thrown by the API client when the server returns a non-2xx response. */
+export class ApiError extends Error {
+  /** HTTP status code returned by the server. */
+  public readonly status: number;
+
+  /** Raw response body text as returned by the server. */
+  public readonly body: string;
+
+  /**
+   * @param status - The HTTP status code.
+   * @param body   - The raw response body text.
+   */
+  constructor(status: number, body: string) {
+    super(`API error ${String(status)}: ${body}`);
+    this.name = "ApiError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a `fetch` call and return the parsed JSON body as `T`.
+ *
+ * @param url     - Fully-qualified URL.
+ * @param options - Standard `RequestInit` options.
+ * @returns Parsed JSON response cast to `T`.
+ * @throws {ApiError} When the server returns a non-2xx status code.
+ */
+async function request<T>(url: string, options: RequestInit = {}): Promise<T> {
+  const response: Response = await fetch(url, {
+    ...options,
+    credentials: "include",
+    headers: {
+      "Content-Type": "application/json",
+      ...options.headers,
+    },
+  });
+
+  if (!response.ok) {
+    const body: string = await response.text();
+    throw new ApiError(response.status, body);
+  }
+
+  // 204 No Content — return undefined cast to T.
+  if (response.status === 204) {
+    return undefined as unknown as T;
+  }
+
+  return (await response.json()) as T;
+}
+
+// ---------------------------------------------------------------------------
+// Public HTTP verb helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Perform a GET request to the given path.
+ *
+ * @param path - API path relative to `BASE_URL`, e.g. `"/jails"`.
+ * @returns Parsed response body typed as `T`.
+ */
+export async function get<T>(path: string): Promise<T> {
+  return request<T>(`${BASE_URL}${path}`);
+}
+
+/**
+ * Perform a POST request with a JSON body.
+ *
+ * @param path - API path relative to `BASE_URL`.
+ * @param body - Request payload to serialise as JSON.
+ * @returns Parsed response body typed as `T`.
+ */
+export async function post<T>(path: string, body: unknown): Promise<T> {
+  return request<T>(`${BASE_URL}${path}`, {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+}
+
+/**
+ * Perform a PUT request with a JSON body.
+ *
+ * @param path - API path relative to `BASE_URL`.
+ * @param body - Request payload to serialise as JSON.
+ * @returns Parsed response body typed as `T`.
+ */
+export async function put<T>(path: string, body: unknown): Promise<T> {
+  return request<T>(`${BASE_URL}${path}`, {
+    method: "PUT",
+    body: JSON.stringify(body),
+  });
+}
+
+/**
+ * Perform a DELETE request, optionally with a JSON body.
+ *
+ * @param path - API path relative to `BASE_URL`.
+ * @param body - Optional request payload.
+ * @returns Parsed response body typed as `T`.
+ */
+export async function del<T>(path: string, body?: unknown): Promise<T> {
+  return request<T>(`${BASE_URL}${path}`, {
+    method: "DELETE",
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+}
+
+/** Convenience namespace bundling all HTTP helpers. */
+export const api = { get, post, put, del } as const;
+
+// Re-export endpoints so callers only need to import from `client.ts` if desired.
+export { ENDPOINTS };

frontend/src/api/endpoints.ts

@@ -0,0 +1,86 @@
+/**
+ * API endpoint path constants.
+ *
+ * Every backend path used by the frontend is defined here.
+ * Components and API modules import from this file rather than
+ * hard-coding URL strings, so renaming an endpoint requires only one change.
+ */
+
+export const ENDPOINTS = {
+  // -------------------------------------------------------------------------
+  // Health
+  // -------------------------------------------------------------------------
+  health: "/health",
+
+  // -------------------------------------------------------------------------
+  // Setup wizard
+  // -------------------------------------------------------------------------
+  setup: "/setup",
+
+  // -------------------------------------------------------------------------
+  // Authentication
+  // -------------------------------------------------------------------------
+  authLogin: "/auth/login",
+  authLogout: "/auth/logout",
+
+  // -------------------------------------------------------------------------
+  // Dashboard
+  // -------------------------------------------------------------------------
+  dashboardStatus: "/dashboard/status",
+  dashboardBans: "/dashboard/bans",
+  dashboardBansByCountry: "/dashboard/bans/by-country",
+
+  // -------------------------------------------------------------------------
+  // Jails
+  // -------------------------------------------------------------------------
+  jails: "/jails",
+  jail: (name: string): string => `/jails/${encodeURIComponent(name)}`,
+  jailStart: (name: string): string => `/jails/${encodeURIComponent(name)}/start`,
+  jailStop: (name: string): string => `/jails/${encodeURIComponent(name)}/stop`,
+  jailIdle: (name: string): string => `/jails/${encodeURIComponent(name)}/idle`,
+  jailReload: (name: string): string => `/jails/${encodeURIComponent(name)}/reload`,
+  jailsReloadAll: "/jails/reload-all",
+  jailIgnoreIp: (name: string): string => `/jails/${encodeURIComponent(name)}/ignoreip`,
+
+  // -------------------------------------------------------------------------
+  // Bans
+  // -------------------------------------------------------------------------
+  bans: "/bans",
+  bansActive: "/bans/active",
+
+  // -------------------------------------------------------------------------
+  // Geo / IP lookup
+  // -------------------------------------------------------------------------
+  geoLookup: (ip: string): string => `/geo/lookup/${encodeURIComponent(ip)}`,
+
+  // -------------------------------------------------------------------------
+  // Configuration
+  // -------------------------------------------------------------------------
+  configJails: "/config/jails",
+  configJail: (name: string): string => `/config/jails/${encodeURIComponent(name)}`,
+  configGlobal: "/config/global",
+  configReload: "/config/reload",
+  configRegexTest: "/config/regex-test",
+
+  // -------------------------------------------------------------------------
+  // Server settings
+  // -------------------------------------------------------------------------
+  serverSettings: "/server/settings",
+  serverFlushLogs: "/server/flush-logs",
+
+  // -------------------------------------------------------------------------
+  // Ban history
+  // -------------------------------------------------------------------------
+  history: "/history",
+  historyIp: (ip: string): string => `/history/${encodeURIComponent(ip)}`,
+
+  // -------------------------------------------------------------------------
+  // Blocklists
+  // -------------------------------------------------------------------------
+  blocklists: "/blocklists",
+  blocklist: (id: number): string => `/blocklists/${String(id)}`,
+  blocklistPreview: (id: number): string => `/blocklists/${String(id)}/preview`,
+  blocklistsImport: "/blocklists/import",
+  blocklistsSchedule: "/blocklists/schedule",
+  blocklistsLog: "/blocklists/log",
+} as const;