Skip to Content
OpenFlare
GuidesDeploymentReferenceArchitectureChangelog

System Architecture

OpenFlare consists of the Server control plane, the Pingora Edge data plane, tunnel components (Relay and OpenFlared), and the management console frontend. For edge synchronization, validation, and runtime application workflows, see Pingora Edge Node Design.


Traffic Path Overview

Depending on the website upstream type, OpenFlare supports three distinct data plane traffic paths:

1. Standard Reverse Proxy Traffic Path

Browser
  |
  | HTTPS/HTTP request
  v
Pingora Edge (WAF, TLS, Rate Limit, optional Origin Error Page)
  |
  | reverse proxy
  v
Origin Server (direct public or private upstream)

When an origin server or gateway returns error status codes matching the configured list, OpenFlare returns global custom or default HTML while preserving the real HTTP status code. See Origin Error Page Design.

2. Intranet Penetration Traffic Path

Suitable for routing traffic to origin services hosted on private or firewall-restricted networks:

Browser
  |
  | HTTPS/HTTP request
  v
Pingora Edge (Agent host, TLS/WAF)
  |
  | reverse proxy to http://localhost:vhost_port (Host header preserved)
  v
OpenFlareRelay (frps)              <-- co-located with Agent, provides relay
  |
  | frp tunnel protocol (Host header routing)
  v
OpenFlared (frpc)                  <-- intranet server
  |
  | HTTP/HTTPS forward
  v
Internal Service (192.168.x.x)

3. Pages Static Hosting Traffic Path

Suitable for pre-built Single Page Applications (SPAs) or static website hosting:

Browser
  |
  | HTTPS/HTTP request
  v
Pingora Edge (Agent, TLS/WAF)
  |
  +---> [Static Serving] reads deployed files ---> Agent local Pages deployment directory
  |
  +---> [API Proxy] reverse proxy ---> Backend API service (if API proxying enabled)

Component Responsibilities

ComponentResponsibilityDetailed Design Reference
ServerAdmin UI/API, control-plane state persistence, configuration compilation and auto-sync, Pages deployment asset storage, Cloudflare A-record pointing, access log ingestion and traffic aggregation, Uptime Kuma monitoring sync, and login captcha protectionPingora Edge Node Design / Cloudflare DNS Pointing Design / Edge Observability & Business Traffic Stats / Uptime Kuma Sync Design / Login Captcha Design
Pingora EdgeIngests live traffic, evaluates WAF rules, PoW defense, Basic Auth, static file and reverse proxy serving, and optional origin error pagesWAF Design / Pages Design / Origin Error Page Design
RelayDeployed on edge nodes, manages frps daemon lifecycle, and receives dynamically dispatched tunnel relay configuration via heartbeatsTunnel Design
OpenFlaredDeployed in private networks, manages frpc process groups, maintains reverse tunnels across multiple Relays, and reports connectivityTunnel Design

Component Architecture and Division of Labor

1. Server (Control Plane)

The Go backend at the repository root (module github.com/Rain-kl/Wavelet) serves as the OpenFlare control plane, built on the Wavelet full-stack scaffold:

  • Provides admin REST APIs (/api/v1/d/*) authenticated via Session Cookie, with optional X-Access-Token.
  • Edge node protocols go through /api/v1/agent|relay|tunnel/*, authenticated with X-Agent-Token / X-Tunnel-Token respectively.
  • Contains the configuration Compiler, uniformly compiling DB rules, certificates, and global parameters into immutable configuration snapshots and required runtime resources.
  • Uniformly receives Pages local uploads, Remote URLs, and public GitHub Release pre-built artifacts, completing source checks, restricted downloads, archive validation, and immutable deployments; manual uploads create candidates awaiting explicit activation, while persistent-source sync creates-or-loads and atomically activates. The Server provides controlled latest-download endpoints to edge nodes; an internal scanner handles limited GitHub latest checks, lease recovery, optional auto-publish, and orphan upload compensation; generic task management endpoints cannot modify this schedule. Future repository source builds are extended via an isolated Server build executor; edge nodes never execute third-party fetch or build commands.
  • Provides the optional Cloudflare DNS pointing control plane: maintains group desired states with ZoneDomains as members, idempotently syncing a single A record to the active node IPv4 via Asynq; node IP changes are queued best-effort; phase 1 does not execute automatic failover.
  • Integrates backend Uptime Kuma monitoring synchronization, automatically maintaining HTTP probe tasks for active sites.
  • Startup entry: cmd/server/main.go + cmd/server/cli/ (api / worker / scheduler / all); OpenFlare business logic resides in internal/apps/openflare/, Server-side edge protocol handling in internal/apps/openflare/{agent,relay,flared}/, and edge runtimes in edge/pingora/ and internal/edge/{common,relay,flared}/.
  • See: Pingora Edge Node Design and Uptime Kuma Sync Design

2. Pingora Edge (Data Plane)

openflare-edge manages listeners, snapshots, and Pages assets, executing HTTP proxying, HTTP/2, TLS, WAF, PoW, site authentication, and caching within a single unified runtime. Nodes receive update notifications via WebSockets and synchronize site snapshots, IP groups, and performance policies through heartbeat manifests.

3. Relay and OpenFlared (Tunnel Components)

Extend data-plane reverse penetration capabilities:

  • openflare-relay manages the local frps daemon, receives Server configuration dispatches, and automatically updates relay ports.
  • openflared manages a group of frpc client processes within internal networks, establishing nearest multi-relay connections and high-availability disaster recovery.
  • See: Tunnel Design

Data and Request Flow Overview

1. Configuration Save and Sync Flow

Admin saves config -> auto-compiles and updates site snapshot by digest
                                 |
              +------------------+------------------+
              | (WebSocket broadcast or periodic Heartbeat)
              v                                     v
       [Edge Node]                             [Intranet OpenFlared]
  pull site snapshot and certs by hash    pull latest Tunnel mapping config
  pull/extract Pages packages             generate/rewrite frpc.toml
  verify and atomically swap in memory    smooth reload or spawn frpc
  report apply state (Success / Error)    report tunnel connection state and metrics

2. Static Hosting and API Proxy Flow

  • Static assets are extracted to projects/{project_id}/current on the edge node (pulled per project latest, keeping only the latest package); Pingora serves static files directly from local storage.
  • When API proxying is enabled, Pingora rewrites and forwards (reverse proxy) API requests to backend dynamic endpoints according to the site's configured api_proxy_path (e.g. /api).
  • Administrator operations and internal scanners generate restricted artifact candidates, reusing the unified inspection, upload.Ingest, and deployment pipeline. Manual uploads create unactivated candidates; persistent source syncs create-or-load and atomically activate. Future repository build executors will emit artifacts into the same pipeline; edge nodes remain consumers of active deployments.
  • See Pages Static Hosting Design.

3. WAF Security Filtering Flow

  • The WAF engine evaluates requests during the Pingora request phase.
  • WAF rules are orchestrated as visual DAGs on the control plane and compiled into runtime graphs upon publishing; edge nodes load and execute them via in-memory objects.
  • Global rules precede route-bound rules, which execute in explicit order. When an evaluation reaches "pass", processing proceeds to the next rule; reaching "block" immediately returns the node-configured blocking response.
  • IP group membership updates dynamically: the control plane notifies nodes to verify checksums, and nodes update only modified IP groups.
  • See WAF Design and WAF Orchestration Rule Design.

4. Edge Observability and Business Traffic Statistics Flow

Pingora access logs (business ground truth)
        |
        | nodes report log entries via heartbeats
        v
Server ingests via logstore (current log primary: PostgreSQL / SQLite / ClickHouse)
        |
        +---> Global aggregation --> Dashboard "Data Provided / Requests / Unique Visitors"
        +---> host in Zone --------> Zone "Data Provided" etc. (identical semantics)
        +---> node_id filter ------> Node business traffic volume

Host /proc network and CPU metrics --> Agent snapshot readings --> Host resource trends (isolated from business traffic)
Pingora health and connection counts --> Edge health (instantaneous readings, not 24h business totals)

5. Cloudflare DNS Pointing Flow

Admin configures connection/groups/members -> Server persists desired state -> Asynq sync task
                                                                                   |
                                                                                   v
                                                                         Cloudflare Zone / DNS API
                                                                                   |
                                                                                   v
                                                               single A record -> active_node IPv4

Node IP manual update or Agent heartbeat change ------------------------> Node-level best-effort enqueue
  • The Cloudflare module manages only the single A record of the same name under its control, without expanding the Zone core into an authoritative DNS control plane. When multiple A records of the same name exist, synchronization halts until cleaned up in Cloudflare.
  • Group backup nodes and active nodes are reserved for future failover; phase 1 fixes usage to the primary node without automatic failover based on heartbeat offline status.
  • See Cloudflare DNS Pointing Design.

Core Objects

Core system entities include:

  • Proxy and Configuration: zones (root domain boundary), zone_domains (explicit domain and cert/route bindings), proxy_routes (route policies), origins (origin servers), config_versions (configuration versions), tls_certificates (certificates). See Zone & Domain Resource Design.
  • Cloudflare DNS Pointing: of_cf_connections (global connections), of_cf_pointing_groups (primary/backup/active nodes and default orange-cloud), of_cf_pointing_members (ZoneDomain members, record cache, and sync status). See Cloudflare DNS Pointing Design.
  • Pages Static Hosting: of_pages_projects (Pages projects), of_pages_project_sources / of_pages_project_source_runtime (source configuration and runtime state), of_pages_deployments (immutable deployments), of_pages_deployment_files (deployment file manifests).
  • Nodes and Tunnels: nodes (nodes), tunnels (tunnel clients), node_system_profiles (system profiles), apply_logs (application logs).
  • WAF and Security: waf_rule_groups (WAF rule groups), waf_ip_groups (WAF IP groups), waf_rule_group_bindings (site WAF bindings).
  • System and Accounts: acme_accounts (ACME accounts), dns_accounts (DNS accounts), geoip_update_configs (GeoIP update configurations).

Key Design Decisions

DecisionRationale
Complete site snapshotsProvides consistent boundaries for validation, atomic swapping, and local recovery
Active pull by edge nodesEliminates Server SSH requirements, lowering security risks; enables flexible HTTP and WebSocket switching
Single active versionSimplifies control plane state and ensures consistency across nodes; provides instant one-click rollback
Separation of Zone domains and route policiesZone defines root domain boundaries; routes reuse site policies and bind certificates per domain
Cloudflare pointing independent of Zone coreZoneDomain provides FQDNs; Cloudflare module synchronizes single A records from desired state without expanding Zone into a general DNS plane
Intranet penetration based on frpReuses proven tunnel protocols to avoid custom protocol risks; vhost routing naturally matches reverse proxy routes
Decoupled runtime configuration and control DBWAF rules compile upon publishing and load atomically with site snapshots; dynamic IP groups refresh independently via checksum-driven in-memory snapshots
Access logs as the single truth for business trafficEdge nodes forbid business pre-aggregation; dashboard and Zone share Server-side aggregation, avoiding dual tracks between openresty_tx and bytes_sent
Layered separation of business traffic / edge health / host resourcesData Provided != host network egress != Pingora connection counts; UI and APIs maintain distinct naming and presentation
Pages artifact and repository build separationExisting sources import pre-built packages; future checkout/build pipelines run in isolated Server executors and reuse the artifact pipeline; edge nodes do not execute third-party builds

On this page