Skip to content

Architecture — QGTMAI Trading Platform

Current Operating Scope

QGTMAI is a paper-first precious-metals trading platform. The current canonical production path has three active surfaces:

  1. qgtm_web — the web terminal served at https://qgtmai.com
  2. qgtm_api — the FastAPI backend served at https://api.qgtmai.com
  3. qgtm_live — the systemd-managed daemon on the production droplet

The repo also contains broader research, signal-delivery, and business-stack surfaces, but those should be treated as optional or pre-launch unless a specific runbook says otherwise.

Design Principles

  1. Paper-first before live capital
  2. Repo-first and reproducible
  3. PM-focused runtime truth over marketing counts
  4. Risk and operator control ahead of growth features
  5. Clean separation between runtime truth and pre-launch business surfaces

System Context

flowchart LR
    O[Owner / Operator] --> W[QGTMAI Web Terminal]
    W --> A[QGTMAI API]
    A --> D[Trading Daemon]
    D --> B[Alpaca Broker]
    D --> M[Macro and PM Data Providers]
    A --> R[Redis State / Heartbeat]
    D --> R
    A --> G[GitHub / Deploy Control Plane]
    W --> C[Cloudflare Pages]

External Systems

  • Alpaca for broker execution and market data
  • FRED, CFTC/Nasdaq Data Link, EIA, NOAA, and related providers for macro and research inputs
  • GitHub Actions for CI/CD orchestration
  • Cloudflare Pages and DNS for web/docs hosting
  • DigitalOcean droplet for the API/daemon runtime

Runtime Components

Component Repo Surface Current Role
Web terminal qgtm_web Operator-facing terminal and research interface
API qgtm_api HTTP/WS control plane, market data, forecasts, strategy/risk views
Trading daemon qgtm_live Strategy execution loop, heartbeat, reconciliation, watchdog
Strategy layer qgtm_strategies 29 static PM catalog entries plus runtime-live and supplemental/control modules
Risk layer qgtm_risk Tiered kill-switch, drawdown and exposure controls
Portfolio layer qgtm_portfolio Aggregation and allocation logic
Execution layer qgtm_execution OMS and broker interaction
State/cache Redis Heartbeats, transient runtime state, websocket support
Research and features qgtm_data, qgtm_features, qgtm_strategies, qgtm_live Data ingestion, features, and support-model code paths

Data and Control Flow

  1. Market and macro data enters through the qgtm_data and market-data routes
  2. Features and support-model inputs are prepared for the PM stack
  3. Runtime PM strategies emit signals
  4. Portfolio and risk layers filter, scale, and gate those signals
  5. The daemon produces target actions and hands them to execution
  6. API routes expose health, telemetry, market data, forecasts, and strategy state to the terminal

Package Map

Package / Layer Responsibility
qgtm_core shared types, config, constants, universe definitions
qgtm_data upstream data access and ingestion
qgtm_altdata slower alternative-data paths
qgtm_features feature construction and analytical transforms
qgtm_strategies runtime strategies plus supplemental/control modules
qgtm_portfolio aggregation and allocation
qgtm_risk kill-switch tiers, drawdown, limits
qgtm_execution OMS and broker interactions
qgtm_live daemon loop, reconciliation, watchdog
qgtm_api REST and websocket surfaces
support-model layer regime, meta-labelling, and self-learning logic inside qgtm_strategies and qgtm_live
qgtm_signals optional signal publication layer
qgtm_bot optional Discord/Telegram surfaces
qgtm_web frontend terminal

Current Production Deployment

Surface Platform Notes
Web terminal Cloudflare Pages (qgtm-trading) qgtmai.com
Docs Cloudflare Pages (qgtm-docs) documentation site
API DigitalOcean droplet systemd-managed Docker Compose runtime
Daemon DigitalOcean droplet isolated from API via separate systemd unit
Redis DigitalOcean droplet Docker-managed service used by API and daemon
Secrets GitHub Actions + droplet .env current documented production path

Operational Truth Boundaries

  • qgtm_api.routes.PM_STRATEGIES is the 29-entry static PM catalog
  • /api/v1/strategies is the live-known runtime surface and returned 31 strategies in production on 2026-04-16
  • The public README catalog is broader (36 core PM modules) and includes supplemental/control surfaces
  • The default universe is PM-focused (20 instruments); focus=broad exposes the broader legacy commodity universe (44)
  • Signal monetization and subscriber-facing business surfaces remain pre-launch
  • There is no dedicated public kill-switch admin endpoint in the canonical paper-first production path today

What This Architecture Is Not

  • It is not a fully live-capital, subscriber-monetized stack yet
  • It is not accurately described by older Fly.io / Neon / Upstash / Doppler narratives
  • It should not be summarized by raw module counts in qgtm_strategies/

Use the deployment and runbook docs as the source of truth for operational behavior, and use the strategy taxonomy docs for inventory truth.