Architecture Concept · v0.1 Draft

HonorPro Hub

A multi-tenant SaaS control plane that licenses brokers and delivers turnkey trading features — MT5 server plugins paired with white-label web frontends — onto broker-owned infrastructure.

2026-08-19 · internal · status: concept for review (OPS-7)

1Product vision

Brokers who run their own MetaTrader 5 servers want modern client-facing functionality — a web terminal, copy trading, social trading, risk tooling — without building or operating any of it. The Hub is the product that sells them exactly that: a subscription service where a broker signs up, receives a license, and switches individual features on from a self-service console. Each feature arrives as a matched pair: a server-side component (an MT5 plugin or a gateway service that talks to the broker's MT5 server) plus a white-label web frontend branded for that broker.

The provider owns the Hub — the control plane, the licensing authority, the feature catalog, and the frontends. The broker owns their trading infrastructure — the MT5 server, the accounts, the market data, the money. That split is the core selling point: the broker's trading data never leaves the broker's infrastructure; the Hub only orchestrates.

2Terminology

3System topology

Two planes. The control plane (provider cloud) holds no trading data. The data plane (one per broker) holds all of it.

Traffic rules, in order of importance:

• The Hub never connects into a broker's network. The Agent dials out over WSS and keeps the channel open; every Hub→broker action (deploy, config push, license refresh, kill) rides that channel. No inbound firewall holes on the broker side.
• Trader traffic goes browser → feature frontend → broker Gateway. Quotes, orders, positions flow between the trader's browser and the broker's own Gateway; the Hub is not in that path and cannot become a latency or availability bottleneck for trading.
• Only telemetry and configuration cross the boundary: health heartbeats, feature usage counters, alert events. Never account data, orders, or personal client data.

4Tenancy & data boundary

The Hub database is multi-tenant with a broker_id discriminator on every row and row-level enforcement in the API layer (single schema; per-tenant schemas are not warranted at this data volume — the Hub stores configuration, not trading history). Broker Console sessions are scoped to exactly one broker_id; provider operators carry an explicit cross-tenant role.

5Broker lifecycle

A broker record moves through a small, explicit state machine. Licensing (§6) is layered on top of an active broker; deactivating the broker overrides every license.

stateDiagram-v2
  [*] --> Draft: create broker
  Draft --> Provisioning: issue license + agent token
  Provisioning --> Active: agent connected,
first feature deployed
  Active --> Suspended: manual suspend /
license expired + grace over
  Suspended --> Active: reactivate / renew
  Suspended --> Terminated: offboard
  Terminated --> [*]
  

6Licensing

The license is a signed document, not a database flag — because it must be enforceable on machines we do not control, including ones temporarily offline.

License document

{
  "license_id": "lic_01J9…",
  "broker_id": "brk_honorpro",
  "status": "active",              // active | suspended
  "issued_at": "2026-08-19T00:00:00Z",
  "valid_until": "2027-08-19T00:00:00Z",   // “active until” — the expiry the sales side manages
  "grace_hours": 72,               // offline tolerance
  "entitlements": [
    { "feature": "web-terminal",  "tier": "standard", "limits": { "concurrent_sessions": 500 } },
    { "feature": "copy-trading",  "tier": "pro",      "limits": { "masters": 50, "followers": 2000 } },
    { "feature": "price-alerts",  "tier": "standard", "limits": { "watched_symbols": 200 } }
  ],
  "signature": "ed25519:…"         // signed by the Hub licensing key
}

Issuance and refresh

• The Hub licensing service signs licenses with an Ed25519 private key that never leaves the control plane. Agents, gateways and plugins embed the public key.
• Licenses are short-lived on the wire: the Agent re-fetches a fresh signed copy every few hours over its WSS channel and fans it out to the Gateway and plugins. valid_until is the commercial expiry; the wire copy's own freshness window is what makes the kill-switch fast.
• Offline behaviour: if the Agent cannot reach the Hub, components keep honoring the last license for grace_hours, then degrade to read-only, then stop. A broker's internet blip never halts trading features instantly; a broker who cuts the cord to dodge expiry gets 72 hours, not forever.

Enforcement points

Statuses shown to operators: active expiring ≤ 30d grace expired suspended terminated. “Is this broker active, and until when” is a first-class column in the Provider Console, not a report.

7White-label

Branding is a per-broker document applied uniformly by every feature frontend:

• Identity: product name, logo set (light/dark), favicon, color tokens (accent, surfaces), typography choice from a curated set, email sender name.
• Domains: default {broker}.hub.example.com per feature or per broker; custom domains via CNAME with automated TLS (the frontends already resolve the tenant from Host).
• Locales: enabled languages per broker, default locale, per-broker string overrides on top of the shared 11-locale i18n base (the existing i18n system carries over; dir stays LTR everywhere — established constraint from the terminal).
• Legal: broker's own ToS/risk-disclosure documents, support links, company footer.

Implementation: the frontend fleet is one deployment, many tenants. A request hits the frontend host, tenant is resolved from the domain, the branding document and license are fetched from the Hub (edge-cached, minutes-level TTL), theme tokens are injected as CSS variables. No per-broker builds; a rebrand is a config change.

8Feature model

A feature is defined by a manifest in the catalog. The manifest is what makes “broker clicks Enable, everything else happens” possible.

feature: copy-trading
version: 2.4.1
components:
  - kind: mt5-plugin          # native, runs inside the broker's MT5 server
    artifact: copyengine-2.4.1-mt5build4620.zip   # signed
    mt5_min_build: 4560
  - kind: gateway-service     # Python module loaded by the broker's Gateway
    artifact: gw-copytrading-2.4.1.whl
  - kind: web-frontend        # provider-hosted SPA route(s)
    routes: [ "/copy", "/copy/admin" ]
config_schema: ./config.schema.json   # drives the auto-generated settings UI
license_flag: copy-trading
depends_on: [ web-terminal-core ]
health: [ "plugin:copyengine:heartbeat", "gw:copytrading:ping" ]

• Versioned: the catalog holds multiple versions per feature with release channels (stable / beta). Brokers sit on a channel; the provider promotes builds. Rollback = pin previous version.
• Config-schema-driven: each feature ships a JSON Schema for its settings. The Broker Console renders the settings form from the schema — new features get a config UI for free; rich features can ship a custom panel instead.
• Composable: features can depend on others (copy trading depends on the terminal core API). The Hub resolves dependencies at enable time.

Enable flow

sequenceDiagram
  participant B as Broker admin
  participant H as Hub
  participant A as Agent (broker box)
  participant G as Gateway
  participant M as MT5 server
  B->>H: Enable "copy-trading"
  H->>H: check entitlement, resolve deps & version
  H->>A: deploy plan (artifacts, config, license)
  A->>A: download signed artifacts, verify signatures
  A->>M: install plugin (staged, server-safe window)
  A->>G: install gateway module, hot-reload
  A->>H: deployed OK + component health
  H->>B: feature live — link to its admin panel
  

MT5 plugin installation is the one step that may require a server restart (MetaQuotes constraint). The deploy plan marks such steps staged: the Agent prepares everything and either restarts within a broker-approved maintenance window or waits for the broker admin to confirm the restart from the console.

9Broker-side runtime

Three things run on broker infrastructure, all installed from one signed installer:

Enrollment: the Provider Console issues a one-time token; the broker (or our onboarding engineer) runs the installer, pastes the token, and the Agent appears in the Hub with a persistent identity (mTLS client cert issued on enrollment). Everything after that is remote.

10Consoles

Broker Console (tenant self-service — the Hub's own frontend)

• Dashboard: license status and expiry, feature health at a glance, key usage numbers.
• Feature store: catalog of available features with entitlement state — enabled / available on your plan / contact sales. Enable, disable, pick channel.
• Feature settings: schema-generated config forms, plus embedded rich admin panels for the big features (the existing web-terminal admin console becomes the embedded panel for the terminal feature — SSO from the Hub session, no second login).
• Branding: the white-label editor with live preview.
• Notifications: Telegram / email channel setup, per-feature routing (used by Price Alerts, license expiry warnings, deploy results).
• Team: broker staff accounts and roles (owner / admin / operator / read-only).

Because the web terminal is itself a feature, the Broker Console is the natural home of what is today the terminal's admin area: one login, terminal administration under it. The current admin console (operators, dealing) continues to run gateway-side — it administers trading data that must stay broker-side — and is surfaced inside the Broker Console via SSO-embedded panel.

Provider Console (back office)

• Broker CRUD and lifecycle (§5); license issuance, renewal, suspension with reason codes.
• Catalog management: register feature versions, promote channels, mark builds critical.
• Fleet view: every agent, gateway, plugin across all brokers — version, health, license freshness; one screen answers “who is on the broken build”.
• Cross-tenant audit log and alert stream (agent offline, deploy failed, license tampering attempts).

11Initial feature catalog

12Price Alert feature

The first fully Hub-native feature, and deliberately the pilot: it exercises the manifest, config schema, gateway module deployment, licensing and notification pipeline end-to-end while being small enough to ship early.

What it does: watches the broker's quote stream and notifies the broker's team in Telegram when quotes stop flowing during hours when the market should be trading — the classic “feed died at 3 a.m. Sunday? no — feed died mid-session and nobody noticed” insurance.

Detection (gateway module — broker side, at the feed)

• Subscribes to ticks for the configured symbol set through the Gateway's existing MT5 manager connection (no extra MT5 load — it shares the pump).
• Per symbol, keeps last_tick_at and an expected-cadence profile. Stall condition: now − last_tick_at > threshold while the symbol's market is open.
• Market-hours source: primary — the symbol's trading-session schedule read from the MT5 server itself (per-symbol quote sessions), so the calendar is always the broker's own; secondary — a per-broker holiday/override calendar edited in the console (early closes, ad-hoc halts). If MT5 says the session is closed, silence is normal and no alert fires.
• Thresholds are per-symbol-group with sane defaults (e.g. majors 30 s, exotics 5 min, metals 60 s) and support a quiet multiplier around session open/close where feeds are legitimately thin.
• Debounce and aggregation: one stalled LP usually kills many symbols at once — the module groups simultaneous stalls into a single alert (“EURUSD.z +34 more stalled”), not 35 messages.

Notification (Hub side)

sequenceDiagram
  participant G as Gateway module
  participant H as Hub notification service
  participant T as Telegram
  G->>G: stall detected (market open, threshold passed)
  G->>H: alert event {symbols, since, severity}
  H->>T: message to broker's configured chat(s)
  Note over G,H: repeat/escalate every N min while stalled
  G->>H: recovery event
  H->>T: "feed recovered, gap 4m 12s"
  

• Delivery through the Hub's shared Telegram bot to chats the broker binds in the console (bind = broker admin sends /start <code> to the bot). Option for the broker's own bot token later.
• Escalation policy per broker: repeat interval, severity upgrade after M minutes, optional second channel (email) if unacknowledged.
• Recovery notice always sent, with measured gap duration — the gap log doubles as an SLA/LP-quality report.
• Fallback ordering: if the Gateway loses the Hub, it buffers events and can send direct-to-Telegram as a last resort (configurable); if the Gateway itself dies, the Hub's agent-heartbeat monitoring fires a separate “gateway offline” alert — the watchdog is itself watched.

Config (schema-driven form in the Broker Console)

{
  "symbol_groups": [
    { "match": "*.z", "threshold_s": 30 },
    { "match": "XAU*", "threshold_s": 60 }
  ],
  "calendar_overrides": [ { "date": "2026-12-25", "closed": true } ],
  "telegram_chats": [ "-100123456789" ],
  "repeat_min": 10,
  "escalate_after_min": 30,
  "open_close_quiet_multiplier": 3
}

13Data model (Hub core)

brokers          id, name, status, contacts, created_at
licenses         id, broker_id, status, valid_until, grace_hours, signed_doc, issued_at
entitlements     license_id, feature, tier, limits(json)
features         key, name, description, config_schema_ref
feature_versions feature, version, channel, components(json), mt5_min_build
deployments      id, broker_id, feature, version, state, plan(json), started_at, finished_at
agents           id, broker_id, cert_fp, last_seen, agent_version, host_meta
branding         broker_id, tokens(json), domains(json), locales(json), assets…
notif_channels   broker_id, kind(telegram|email), address, verified
alert_events     id, broker_id, feature, severity, payload, raised_at, resolved_at
audit_log        id, actor, broker_id, action, before, after, at
users            id, email, role, broker_id nullable (null ⇒ provider staff)

14API surface (sketch)

Auth: Hub sessions are JWT with broker_id + role claims; agent channel is mTLS; frontends resolve tenants via signed, short-TTL tenant descriptors so a compromised edge cache cannot grant an expired broker service.

15Security

• Signed everything: licenses (Ed25519) and artifacts (signature verified by the Agent before install). The broker box refuses unsigned code even if the Hub is compromised at the storage layer.
• Outbound-only broker connectivity; mTLS agent identity; enrollment tokens one-time and short-lived.
• No trading data in the control plane (§4) — the breach blast radius of the Hub is configuration, not client money data.
• RBAC both sides: provider staff roles (sales sees licenses, not deploys; ops sees fleet) and broker roles. Full audit log, immutable, exportable.
• Kill-switch honesty: suspension degrades gracefully (traders see a branded maintenance page; open positions remain manageable through the broker's own MT5 terminals — we disable our features, never their server).
• Secrets: broker-side secrets (manager passwords) live only on broker machines in the Gateway's env; the Hub stores none of them.

16Mapping to existing assets

The Hub is not a green-field rewrite; it is a control plane wrapped around software that already runs in production for one broker.

17Roadmap

18Open questions

1. Frontend hosting for regulated brokers: some will demand frontends on their own domain and their own infrastructure. Support a “self-hosted frontend” deployment mode (Agent deploys the SPA bundle to the broker's web server), or provider-hosted only at launch?
2. Billing: manual invoicing against license terms at launch, or billing integration (usage counters exist in telemetry) in phase 5?
3. Gateway placement: recommend a Linux VM beside the MT5 Windows host (today's proven layout) or support Windows-only single-box installs for small brokers?
4. MT5 version matrix: plugins are build-sensitive (mt5_min_build). How many concurrent MT5 server builds do we commit to supporting per plugin release?
5. Naming: “HonorPro Hub” is the working title; if the SaaS is sold beyond the HonorPro brand, the control plane needs a brand-neutral name (the white-label system itself never shows it to traders).
6. Existing Brokeree coexistence: for brokers running third-party plugins (as tenant #1 does — Ignore Rival Engines), define the compatibility checklist the onboarding flow must verify.

Draft v0.1 — for review. Next step after sign-off: phase 1 technical spec (Hub core data model + licensing service API, detailed).