#title: "Trading System Architecture" date: 2026-05-21 status: living-document

#Trading System

A private, AI-assisted systematic trading operation run by one person with a mathematics background. Everything is self-hosted on Arch Linux. The system is designed to scale from $5k seed capital to $500k+ without changing architecture, only adding capacity.

#1. Hardware

#moirai (Research Station)

What moirai does: all research, backtesting, signal discovery, Jupyter notebooks, and strategy development. No live execution happens here.

#STARGATE (Execution Server)

What STARGATE does: live strategy execution under systemd, tick data storage (TimescaleDB/Parquet), order management, PnL tracking (Grafana/Prometheus), alerting (ntfy + email), and broker API connectivity.

#Planned Upgrades

#2. Software Stack

Languages:     Python 3.12+ (research + execution), Rust (perf-critical later)
Frameworks:    VectorBT (parameter sweeps) + NautilusTrader (event-driven backtest + live)
Storage:       TimescaleDB on STARGATE (live PnL, fills, ticks)
               Parquet on disk (research data archives)
               DuckDB for ad-hoc analytical queries on Parquet
Monitoring:    Grafana + Prometheus (dashboards, equity curves)
               Loki or journald + Promtail (strategy decision audit trail)
Alerts:        Alertmanager -> ntfy push + ~/.local/bin/email
Supervision:   systemd units (one per live strategy)
Isolation:     uv for Python environments, direnv for per-project env vars
Version ctrl:  git (SourceHut)
Backups:       restic snapshots of TimescaleDB to Hetzner S3

#Existing Scripts

Two statusbar modules already exist in the rice:

These integrate with dwmblocks and can be extended to show live PnL, strategy status, or position counts.

#3. How the Program Operates

#Data Flow

Market Data Sources (Polygon, Tiingo, Databento, exchange feeds)
        |
        v
  [STARGATE: Ingest Layer]
  - Cron or streaming ingest scripts
  - Write to TimescaleDB (live ticks/bars)
  - Archive to Parquet (historical)
        |
        v
  [moirai: Research Layer]          [STARGATE: Execution Layer]
  - Jupyter notebooks               - NautilusTrader live engine
  - VectorBT parameter sweeps       - Broker API connections
  - Signal discovery + validation    - Order management system
  - Walk-forward optimization        - Position sizing + risk limits
        |                                    |
        v                                    v
  Validated strategy code            Live fills + PnL
  (committed to git)                 (written to TimescaleDB)
        |                                    |
        v                                    v
  Deploy to STARGATE                 Grafana dashboards
  (systemd unit)                     ntfy/email alerts

#Strategy Lifecycle

1. Hypothesis (moirai): identify a mathematical relationship (mean reversion, momentum, factor, vol surface anomaly) from reading papers, exploring data, or AI-assisted literature search.
2. Backtest (moirai): implement in VectorBT for fast parameter sweeps. Validate with walk-forward optimization, deflated Sharpe ratio, synthetic data testing, and trade randomization.
3. Execution backtest (moirai): port to NautilusTrader for realistic fill simulation with slippage modeling.
4. Paper trade (STARGATE): deploy to paper account (Alpaca paper or IBKR paper) for 2-4 weeks. Compare fills against backtest expectations.
5. Live deploy (STARGATE): start at 20-30% of intended size. Run side-by-side with paper for a month. Reconcile.
6. Monitor (STARGATE): rolling Sharpe, drawdown alerts, daily loss limits. Auto-disable on kill switch triggers.
7. Archive or scale: if rolling 6-month Sharpe < 0, archive the strategy. If stable, increase allocation.

#Risk Controls (Enforced in Code)

#4. The Operator's Role (You)

This is not a "set and forget" system. The operator is the mathematician-programmer who:

#Daily (~30 min)

• Check Grafana dashboard: equity curve, drawdown, open positions
• Review any alerts from overnight
• Scan arxiv q-fin.ST and q-fin.TR for new papers

#Weekly (~2-4 hours)

• Review strategy-level metrics (per-strategy rolling Sharpe, fill quality, slippage vs. expected)
• Research session: explore new signal ideas in Jupyter
• Read one chapter of current quant book (see trading.md Section 10)

#Monthly

• Rolling Sharpe review per strategy; archive any with 6-month Sharpe < 0
• Allocation rebalance across strategies
• Data source check: verify feeds are clean, no gaps
• Infrastructure audit: disk space, systemd unit health, backup verification

#Quarterly

• Framework upgrades (NautilusTrader, VectorBT, broker SDKs)
• Data source expansion (add new asset classes or higher-resolution feeds)
• Tax planning review

#Annual

• CPA review (Green Trader Tax)
• Entity structure review (sole prop -> LLC -> S-corp progression)
• Hardware assessment

#5. AI-Assisted Research

The operator leads all research. AI is a research accelerator, not a decision-maker. AI never places trades or modifies live strategy parameters.

#Research Workflows

#What AI Does NOT Do

• Place orders or modify live positions
• Decide which strategies to deploy or archive
• Set risk parameters
• Access broker API credentials
• Make capital allocation decisions

#Prompt Patterns for Research

# Summarize a paper and extract testable hypotheses
claude -p --model sonnet "Read this paper abstract and methods section. 
Extract: (1) the core claim, (2) the mathematical model, 
(3) what data I'd need to test it, (4) expected Sharpe if the claim holds."

# Verify a backtest implementation
claude -p --model sonnet "Here is the formula from Avellaneda-Stoikov (2008) 
for optimal bid/ask spread: [formula]. Here is my Python implementation: [code]. 
Does my implementation match the paper? Flag any discrepancies."

# Generate a VectorBT skeleton
claude -p --model sonnet "Write a VectorBT backtest skeleton for a 
pairs-trading strategy on two cointegrated equities. Include: 
spread calculation, z-score entry/exit, walk-forward split."

#Research Data Sources for AI

#6. APIs and External Services

#Broker APIs

#Banking API

#Data APIs

#Monitoring APIs

#External Price Feeds (Already Configured)

#7. Directory Structure

~/dev/100x/trading/
  trading.md              # Foundational reference (strategy, brokers, tax, learning path)
  system.md               # This file (architecture, operations, maintenance)
  strategies/             # One directory per strategy
    momentum-futures/
    pairs-equities/
    factor-monthly/
  lib/                    # Shared Python modules
    data/                 # Data ingestion, storage, retrieval
    risk/                 # Position sizing, kill switches, limits
    broker/               # Broker API wrappers
    metrics/              # Sharpe, Sortino, Calmar, DSR calculations
  notebooks/              # Jupyter research notebooks (run on moirai)
  infra/                  # systemd units, Grafana dashboards, Prometheus configs
  scripts/                # Utility scripts (ingest, backup, reconcile)
  data/                   # Local data cache (gitignored; bulk lives on STARGATE)
  .envrc                  # direnv config
  pyproject.toml          # uv/poetry project definition

#8. Maintenance

#Backups

#Monitoring Health Checks

#Failure Modes and Recovery

#Security

• Broker API keys stored in environment variables via direnv, never in git
• STARGATE accessible only via Tailscale (no public ports for trading infra)
• All broker connections over TLS
• Two-factor auth on all broker accounts
• Mercury API token scoped to read-only where possible; write-scoped only for ACH transfers
• No trading credentials stored on moirai (research machine has no execution access)

#9. Mathematics in the System

The operator's mathematical background is the core competitive advantage. Areas where math applies directly:

#Mathematical Software on the System

Python:     numpy, scipy, statsmodels, scikit-learn, cvxpy, sympy
            pandas, polars (DataFrames)
            arch (GARCH models)
            hmmlearn (hidden Markov models for regime detection)
Rust:       nalgebra, ndarray (when Python is too slow)
R:          Available if needed for specific econometric packages
Jupyter:    Primary research interface on moirai

#10. Getting Started Checklist

See trading.md Section 13 ("First 90 Days") for the phased execution plan. The immediate next steps to bring this system online:

1. Initialize ~/dev/100x/trading/ as a git repo on SourceHut
2. Set up uv project with core dependencies
3. Open broker accounts (public.com, Alpaca paper, IBKR, Coinbase Advanced)
4. Install TimescaleDB on STARGATE
5. Pull first dataset (10 years daily bars via Tiingo or Polygon)
6. Replicate one classic strategy from Chan's books
7. Build first Grafana dashboard