Architecture

Component diagram

Wi-Fi Client ──> Access Point (hostapd) ──> Catsplash
                         │                       │
                         │                  ┌────┴────┐
                         │                  │ Firewall│
                         │                  │(iptables)│
                         │                  └─────────┘
                         │                       │
                         │                  ┌────┴────┐
                         │                  │  SQLite  │
                         │                  │  (WAL)   │
                         │                  └─────────┘
                         │                       │
                         │                  ┌────┴────┐
                         │                  │   Web    │
                         │                  │  Portal  │
                         │                  └─────────┘

Main components

main.go (Entry point)

1. Loads configuration (TOML + CLI flags).
2. Opens SQLite database with WAL.
3. Initializes firewall (iptables).
4. Sets up DNAT redirection.
5. Starts the Reaper (session expiration manager).
6. Starts the traffic monitor.
7. Launches the portal web server.
8. Waits for termination signal to clean up resources.

config/ (Configuration)

Loads and validates configuration from a TOML file. Supports CLI flag overrides (--iface, --wan, --port, --db).

firewall/ (Firewall)

iptables management module:

• Init(): Creates custom CATS_PREROUTING chain, NAT Masquerade, FORWARD rules.
• SetupRedirect(): Adds DNAT rule to redirect HTTP traffic to the portal.
• AllowClient(): Inserts 2 FORWARD rules (upload/download) + 1 NAT rule (bypass).
• BlockClient(): Removes the above rules.
• Teardown(): Complete cleanup on exit.

state/ (State)

SQLite session management:

• DB: Opens SQLite connection with WAL, automatic migrations.
• Reaper: Goroutine that checks every 10 seconds for expired sessions and closes them.
• Client: Struct with MAC, IP, state, timestamps, traffic, and limits.

server/ (Web server)

Serves the captive portal and administration:

• /portal - Welcome page with authentication form and CSRF token.
• /auth - Processes authentication and releases the client.
• /admin - Admin panel with authentication, client management and session view.
• /privacy - Privacy policy accessible from the portal.
• /data-request - ARCO+ endpoint: personal data access request.
• /data-deletion - ARCO+ endpoint: personal data deletion request.
• / (catch-all) - Intercepts any HTTP request and redirects to the portal.

state/ (State)

SQLite session management:

• DB: Opens SQLite connection with WAL, automatic migrations.
• Reaper: Goroutine that checks every 10 seconds for expired sessions and closes them.
• Client: Struct with MAC, IP, state, timestamps, traffic, and limits.
• Audit: Audit event logging (data access, deletions, authentication).