Skip to content

Chapter 8: System Architecture

The goal: understand how the current QGTMAI paper-first precious-metals stack fits together without having to read the whole repo.

The 30,000-Foot View

  ┌─────────────────────────────────────────────────────────────────────┐
  │                        QGTMAI ARCHITECTURE                         │
  │                                                                     │
  │   DATA SOURCES          SIGNAL ENGINE          EXECUTION            │
  │   ────────────          ────────────          ──────────            │
  │   Alpaca bars     ──►   PM strategy        ──► Risk tiers       ──► │
  │   FRED / CFTC     ──►   strategies        ──► OMS / broker     ──► │
  │   Macro inputs    ──►   support models    ──► reconciliation       │
  │                                                                     │
  │                   CONTROL PLANE / OPERATOR SURFACES                 │
  │                                                                     │
  │   qgtm_web  ◄──►  qgtm_api  ◄──►  Redis state / heartbeat           │
  │   Terminal         Health           Daemon telemetry                │
  │   Forecasts        Universe         Watchdog state                  │
  │   Research         Risk             Strategy status                 │
  │                                                                     │
  └─────────────────────────────────────────────────────────────────────┘

Core Repo Surfaces

The repo is a monorepo, but the current production story is simpler than the older "everything is live everywhere" narrative.

Surface Role
qgtm_web Operator-facing terminal at qgtmai.com
qgtm_api HTTP and websocket control plane
qgtm_live Trading daemon with watchdog and reconciliation
qgtm_strategies 29 PM catalog entries plus runtime-live and supplemental/control modules
qgtm_risk Tiered kill-switch and exposure controls
qgtm_execution OMS and broker interaction
qgtm_data / qgtm_features upstream data and feature transforms
support-model layer regime, meta, and self-learning logic inside qgtm_strategies and qgtm_live
qgtm_signals / qgtm_bot optional or pre-launch signal delivery surfaces

Signal Pipeline

  1. Data ingestion
     Alpaca, FRED, CFTC, and other providers feed the PM stack.

  2. Feature and support-model prep
     Returns, volatility, ratios, positioning, and support-model context are
     computed for the runtime stack.

  3. Runtime PM strategies
     The static PM catalog contains 29 entries, while the live-known runtime
     surface is dynamic and currently exceeds that count.

  4. Aggregation and allocation
     Conflicting strategy outputs are combined into a target posture.

  5. Risk gating
     WARN -> THROTTLE -> NO_NEW -> FLATTEN tiers protect the book.

  6. Execution and reconciliation
     Orders route to Alpaca, then the daemon tracks fills and broker-vs-local
     state.

  7. API and terminal exposure
     Health, telemetry, forecasts, risk, and strategy views are exposed to the
     operator through the API and web terminal.

Current Runtime Truth

These are the counts and boundaries that matter:

  • 29 static PM catalog entries in qgtm_api.routes.PM_STRATEGIES
  • 31 live-known strategies returned by /api/v1/strategies on 2026-04-16
  • 36 broader README catalog entries for the PM stack
  • 20 PM-focused default universe instruments
  • 44 broad legacy commodity-universe instruments when focus=broad

The raw number of Python files in qgtm_strategies/ is not a trustworthy strategy count because several files are support bundles or grouped implementations.

Deployment Layout

  Cloudflare Pages
    ├── qgtmai.com         -> qgtm_web
    └── qgtm-docs          -> docs site

  DigitalOcean Droplet
    ├── qgtm-api.service   -> API container/runtime
    ├── qgtm-daemon.service-> daemon container/runtime
    └── qgtm-redis.service -> Redis container/runtime

  GitHub Actions
    ├── deploys web/docs
    └── syncs code + env to droplet, then restarts services

This is the current production truth. Older Fly.io / Neon / Upstash / Doppler stories are legacy repo surfaces, not the main operating path.

Why the Stack Looks Like This

  • Paper-first operation keeps risk low while the PM stack matures
  • Separate API and daemon supervision keeps failure domains cleaner
  • Redis provides a lightweight heartbeat and transient state bus
  • Cloudflare Pages gives a simple, fast web edge for the terminal and docs
  • GitHub Actions provides a single deploy control plane tied to the repo

Monorepo Map

  trading/
  ├── qgtm_core/        shared types, config, universes
  ├── qgtm_data/        data ingestion
  ├── qgtm_features/    transforms and feature prep
  ├── qgtm_strategies/  PM strategies and support bundles
  ├── qgtm_portfolio/   aggregation and allocation
  ├── qgtm_risk/        kill-switch and limits
  ├── qgtm_execution/   OMS and broker logic
  ├── qgtm_live/        daemon, reconciliation, watchdog
  ├── qgtm_api/         HTTP and websocket surfaces
  ├── qgtm_web/         terminal frontend
  ├── qgtm_signals/     optional publication layer
  ├── qgtm_bot/         optional chat-bot layer
  ├── infra/            compose, systemd, legacy infra assets
  ├── docs/             docs and tutorial
  └── tests/            automated verification

Key Takeaways

  1. The current system is a PM-focused paper-first operating stack, not a fully launched subscriber business.
  2. The production story is Cloudflare Pages + DigitalOcean droplet + Redis + GitHub Actions, not the older multi-vendor hosting narrative.
  3. Strategy-count truth is split: a 29-entry static PM catalog in code, and a dynamic /api/v1/strategies live surface that returned 31 on 2026-04-16.