Architecture

Bloqd follows a client-server architecture with a central management server and distributed agents.

System Overview

┌─────────────────────────────────────────────────────────────────┐
│                      BLOQD SERVER                                │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    Express API                            │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐        │   │
│  │  │  Auth   │ │ Servers │ │  Bans   │ │Templates│        │   │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘        │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    Services                               │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐        │   │
│  │  │Scheduler│ │ Discord │ │AbuseIPDB│ │  SMTP   │        │   │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘        │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   SQLite DB  │  │  WebSocket   │  │    React     │          │
│  │              │  │   Server     │  │   Frontend   │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                              │
                    HTTPS / WebSocket
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│   SERVER 1    │     │   SERVER 2    │     │   SERVER N    │
│ ┌───────────┐ │     │ ┌───────────┐ │     │ ┌───────────┐ │
│ │   Bloqd   │ │     │ │   Bloqd   │ │     │ │   Bloqd   │ │
│ │   Agent   │ │     │ │   Agent   │ │     │ │   Agent   │ │
│ └───────────┘ │     │ └───────────┘ │     │ └───────────┘ │
│ ┌───────────┐ │     │ ┌───────────┐ │     │ ┌───────────┐ │
│ │ fail2ban  │ │     │ │ fail2ban  │ │     │ │ fail2ban  │ │
│ └───────────┘ │     │ └───────────┘ │     │ └───────────┘ │
└───────────────┘     └───────────────┘     └───────────────┘

Components

Bloqd Server

The central management server consists of:

Component	Description
Express API	RESTful API for all operations
WebSocket Server	Real-time updates to dashboard
SQLite Database	Persistent storage for all data
React Frontend	Web-based dashboard
Scheduler	Background jobs (summaries, cleanup)

Bloqd Agent

A Python-based daemon running on each managed server:

Module	Description
Sync	Fetches whitelist from server
Reporter	Reports bans via Unix socket
Metrics	Collects system metrics (CPU, RAM, disk)
Health	Performs health checks
Commands	Executes remote commands

fail2ban Integration

The agent integrates with fail2ban through:

• Action Script - Reports bans to Bloqd
• Whitelist File - Synced from central server
• Jail Configurations - Deployed from templates

Data Flow

Ban Reporting Flow

fail2ban detects attack
        │
        ▼
Executes bloqd-report action
        │
        ▼
Writes to Unix socket (/var/run/bloqd-agent/report.sock)
        │
        ▼
Agent Reporter module reads from socket
        │
        ▼
POST /api/v1/report to Bloqd server
        │
        ▼
Server stores in database
        │
        ▼
WebSocket broadcast to dashboard
        │
        ▼
Discord notification (if enabled)

Whitelist Sync Flow

User adds IP to whitelist in dashboard
        │
        ▼
Stored in SQLite database
        │
        ▼
Agent polls /api/v1/whitelist/plain
        │
        ▼
Writes to /etc/fail2ban/bloqd-whitelist.txt
        │
        ▼
fail2ban-client reload

Command Execution Flow

User executes command in dashboard
        │
        ▼
Command stored in database with "pending" status
        │
        ▼
Agent polls /api/v1/servers/:id/commands
        │
        ▼
Agent acknowledges and executes command
        │
        ▼
Result sent back to server
        │
        ▼
WebSocket broadcast with result

Database Schema

Key tables in SQLite:

Table	Purpose
servers	Registered managed servers
api_keys	Authentication tokens
whitelist	IP/CIDR whitelist entries
ban_reports	Ban history
templates	Jail templates
agent_commands	Pending/completed commands
users	User accounts
roles	RBAC role definitions

Network Requirements

Server

Direction	Port	Protocol	Purpose
Inbound	3000	TCP	HTTP API & Dashboard
Outbound	443	TCP	Discord, AbuseIPDB, SMTP

Agent

Direction	Port	Protocol	Purpose
Outbound	443/3000	TCP	Connection to Bloqd server

Scalability

Single Server

• Handles 50+ managed servers comfortably
• SQLite handles millions of ban records
• WebSocket connections limited by file descriptors

High Availability

For larger deployments:

• Place Bloqd behind a load balancer
• Use sticky sessions for WebSocket
• Consider PostgreSQL for database (future feature)

Security Boundaries

┌─────────────────────────────────────────────┐
│              TRUST BOUNDARY                  │
│  ┌─────────────────────────────────────┐    │
│  │         Bloqd Server                │    │
│  │  - API Key validation               │    │
│  │  - JWT verification                 │    │
│  │  - Input sanitization               │    │
│  │  - Rate limiting                    │    │
│  └─────────────────────────────────────┘    │
└─────────────────────────────────────────────┘
                    │
                 HTTPS
                    │
┌─────────────────────────────────────────────┐
│              MANAGED SERVERS                 │
│  - Agent runs as root (required for f2b)    │
│  - Commands executed with restrictions      │
│  - Whitelist only writes to specific file   │
└─────────────────────────────────────────────┘

Technology Stack

Server

Layer	Technology
Runtime	Node.js 20+
Framework	Express 4.x
Database	SQLite (better-sqlite3)
Auth	JWT + API Keys
Real-time	WebSocket (ws)
Validation	Zod
Logging	Pino

Frontend

Layer	Technology
Framework	React 18
Build	Vite
Styling	Tailwind CSS
State	Zustand
Charts	Recharts

Agent

Layer	Technology
Runtime	Python 3.10+
HTTP	requests
Config	YAML
Service	systemd