Architecture

Architecture

This page explains how Lumos Gate's components work together, how configuration changes reach your servers, and how the system behaves during failures. Understanding this helps with troubleshooting and evaluating the platform for your infrastructure.

System Overview

Lumos Gate consists of four main components:

The key principle: The control plane (dashboard, WebSocket server) and the data plane (HAProxy on shield VPS) are fully independent. If the dashboard goes down, your sites keep running. Agents operate autonomously with their last known configuration.

Data Flows

Config Push

When you change a domain, WAF rule, or any setting in the dashboard, the update reaches your shield servers in seconds:

1. Dashboard validates the input and saves the change to the database
2. Dashboard publishes a message to the WebSocket server
3. WebSocket Server looks up the agent connection and forwards the config
4. Agent receives the update, backs up the current config, generates new HAProxy configuration, validates it, and reloads HAProxy with zero downtime
5. If the reload fails, the agent automatically rolls back to the previous config and reports the error

For multi-server setups, step 2 publishes to all assigned servers in parallel. All servers receive the update within seconds.

SSL Certificate Provisioning

When you enable SSL for a domain:

1. The config push delivers sslEnabled=true to the agent
2. The agent sets the domain status to "provisioning" (dashboard shows a spinner)
3. The agent starts an ACME HTTP-01 challenge with Let's Encrypt
4. Let's Encrypt sends a verification request to your domain on port 80
5. HAProxy serves the challenge response
6. Let's Encrypt verifies and issues the certificate
7. The agent writes the cert files, updates HAProxy config, and reloads
8. The dashboard shows a green lock icon

Note: DNS must point to the shield VPS and port 80 must be open. See SSL/TLS for troubleshooting.

WAF Rule Application

When a WAF rule is created or updated:

1. The config push delivers the WAF settings to the agent
2. The agent generates HAProxy Lua scripts for the active modules (IP blacklist, rate limiting, OWASP patterns, bot challenge)
3. The agent writes the Lua files, updates HAProxy config, and reloads
4. New rules are active immediately

Metrics Collection

Traffic metrics flow from your shield servers to the dashboard analytics page:

1. The agent periodically reads stats from the HAProxy stats socket
2. Stats are sent to the WebSocket server via the persistent connection
3. The WebSocket server buffers metrics in memory and batch-writes them to the database
4. The dashboard analytics page queries aggregated data by domain, server, or time window

Billing Cycle

The credit system runs automatically every 5 minutes:

1. The system queries all active accounts on paid plans
2. Prorated charges are calculated (plan price / 30 days / 288 cycles per day)
3. Credits are deducted with concurrency-safe locking
4. If balance drops below 2x the plan price, a low_balance notification is sent
5. If balance is insufficient, the account is frozen and an account_frozen notification is sent

Notification Dispatch

When an event occurs (server down, SSL expiring, low balance, etc.):

1. The event is detected by the WebSocket server (agent disconnect, health check, billing cycle)
2. The system loads the user's notification settings
3. If email is enabled for this alert type, an HTML email is sent
4. If a webhook URL is configured, a JSON payload is POSTed (with SSRF protection)

DNS Failover

How failover detection works:

1. The health check runs every 5 minutes
2. For each domain with failover configured, the system checks if the primary server is healthy
3. If the primary is down (offline, error, or not seen for over 2 minutes):
   • DNS A record is updated to point to the first healthy secondary server
   • A failover_triggered notification is dispatched
4. When the primary recovers, DNS is switched back automatically

Security Model

Token Security

All sensitive tokens follow a zero-knowledge pattern -- the plaintext is shown exactly once at creation and never stored:

If you lose a token, you must create a new one -- there is no way to recover it from the database.

Agent Security

• Config encryption -- Local config files on each shield VPS are encrypted with AES-256-GCM
• WebSocket authentication -- The agent authenticates with its server token when connecting. The server validates the token hash.
• No inbound ports -- The agent only makes outbound connections. It does not listen on any management ports.

API Rate Limiting

The dashboard API enforces per-IP rate limits on sensitive endpoints (login, registration, password reset) to prevent brute-force attacks. Rate limit counters are atomic and concurrency-safe.

Webhook SSRF Protection

When delivering webhook notifications, the system blocks requests to private/reserved IP ranges to prevent SSRF attacks:

• localhost, 127.0.0.1, ::1
• 10.x.x.x, 172.16-31.x.x, 192.168.x.x (RFC 1918)
• 169.254.x.x (link-local), 0.0.0.0, fe80: (IPv6 link-local)

Origin IP Validation

When configuring domain origins, private IP ranges are allowed to support common deployment patterns:

Resilience & Failure Handling

Dashboard Outage

If the dashboard becomes unavailable, all existing proxy traffic continues uninterrupted. Agents operate independently with their local HAProxy configuration. You cannot make config changes until the dashboard recovers, but your sites stay up.

WebSocket Server Outage

If the WebSocket server goes down, agents lose their connection and begin reconnecting with exponential backoff. The server container auto-restarts, and agents reconnect within seconds. On reconnect, each agent syncs the full current configuration. During the outage, billing deductions, health checks, and notifications pause.

Message Broker Outage

If the real-time messaging layer becomes unavailable, config updates saved in the dashboard will not reach agents until it recovers. Agents continue serving traffic with their last known configuration. Auto-reconnect restores message flow when the service returns.

Key takeaway: In all failure scenarios, existing proxy traffic continues. The system separates the data plane (HAProxy serving traffic) from the control plane (dashboard and coordination services).

Metrics & Data Retention

Plan-Based Analytics

The analytics dashboard limits the visible time range based on your plan:

Next Steps

• Quick Start -- Get up and running with your first shield server
• Agent Installation -- Install the agent on a VPS
• Agent CLI -- Agent command-line options and scripts
• Supported OS -- Agent platform requirements
• Config Export -- Export your full configuration
• Troubleshooting -- Debug common issues