---
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)

| Component | Spec | Role |
|---|---|---|
| CPU | Intel Core Ultra 7 265K (Arrow Lake), 20 threads | Parameter sweeps, backtest grids (embarrassingly parallel) |
| RAM | 30GB | Holds ~5 years of daily bars for 3000 names in-memory; tight for full L2 tick |
| GPU | AMD Radeon RX 6800 XT | PyTorch ROCm for ML model training; irrelevant for non-ML strategies |
| Storage | NVMe SSD (home partition: 422GB usable) | Local research notebooks, strategy source code |
| Network | Wired ethernet via Tailscale to STARGATE | Low-jitter for remote Postgres queries |
| OS | Arch Linux, dwm, fish shell |  |

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

### STARGATE (Execution Server)

| Component | Spec | Role |
|---|---|---|
| Storage | 916GB /mnt/storage (1TB drive) | Tick data warehouse, TimescaleDB, Parquet archives |
| Network | Wired ethernet, static LAN IP 10.0.0.142 | Live order execution with minimal jitter |
| Tailscale | 100.74.152.79 | Remote access from moirai and mobile |
| OS | Arch Linux (bare metal, no containers for trading) |  |

**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

| Trigger | Action |
|---|---|
| RAM bottleneck on moirai (full L2 tick research) | Upgrade to 64GB |
| Sub-second strategy validated | Add QuantVPS NY4 ($42-129/mo) for low-latency execution |
| $500k+ AUM | Beeks Financial Cloud dedicated NY4 with broker cross-connect |

## 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:

| Script | Path | What It Does |
|---|---|---|
| `sb-ticker` | `~/.local/bin/sb-ticker` | Fetches stock quotes from terminal-stocks.dev for configurable tickers (default: S&P 500, Dow, Nasdaq). Reads `~/.config/tickers`. Cache: `~/.cache/stock-prices`. |
| `sb-price` | `~/.local/bin/sb-price` | Crypto price ticker (BTC, ETH, BAT, etc.) from rate.sx. Supports 7d/14d history charts. Cache: `~/.cache/crypto-prices/`. |

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)

| Control | Rule | Enforcement |
|---|---|---|
| Per-trade stop | Hard loss limit per position | Strategy code |
| Daily loss limit | Pause all strategies after X% equity drawdown | Supervisor daemon |
| Strategy kill switch | Auto-disable on N consecutive losers or M% drawdown over K days | Per-strategy systemd wrapper |
| Position concentration | No single position > P% of equity | Pre-trade check |
| Correlation cap | Total exposure to correlated bucket capped | Portfolio-level check |

## 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

| Task | How AI Helps | Tools |
|---|---|---|
| **Literature mining** | Summarize arxiv papers, extract testable hypotheses from dense math | Claude Code with `claude -p --model sonnet` |
| **Formula verification** | Check derivations, verify implementations against paper equations | Claude in-session |
| **Code generation** | Scaffold backtest skeletons, data pipeline boilerplate, Grafana dashboard JSON | Claude Code |
| **Data exploration** | Generate DuckDB/SQL queries for ad-hoc analysis on tick data | Claude in-session |
| **Parameter space mapping** | Given a strategy, enumerate the parameter space worth sweeping | Claude brainstorm then VectorBT executes |
| **Anomaly investigation** | When a strategy behaves unexpectedly, help diagnose (regime change? data issue? bug?) | Claude + Jupyter |
| **Factor construction** | Help translate WorldQuant alpha101 formulas or paper-described factors into vectorized Python | Claude Code |

### 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

```bash
# 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

| Source | Purpose | Access |
|---|---|---|
| arxiv q-fin | New papers, preprints | Web search / fetch |
| SSRN | Practitioner papers | Web search / fetch |
| Ernie Chan's books | Worked examples to replicate | Local (Calibre or PDF) |
| Lopez de Prado | ML validation methods | Local |
| WorldQuant alpha101 | 101 formulaic alpha signals | GitHub repo |
| Quantopian research archive | Historical notebooks | GitHub |

## 6. APIs and External Services

### Broker APIs

| Broker | Purpose | Auth | Python SDK |
|---|---|---|---|
| **public.com** | Equities, options, bonds, treasuries, crypto | OAuth API keys | Official |
| **Interactive Brokers** | Futures (MES, MNQ, MCL, etc.), global multi-asset | TWS/Gateway + API | `ib_async` |
| **Alpaca** | Paper trading, US equities, options | API key pair | `alpaca-py` |
| **Coinbase Advanced** | Crypto spot | API key | Official |
| **Tradier** | Options (cheapest API: $10/mo unlimited) | OAuth | Community |

### Banking API

| Service | Purpose | Auth |
|---|---|---|
| **Mercury** | Operating account, treasury sweep (4-5% APY on idle cash), programmatic ACH to/from brokers | API token |

### Data APIs

| Provider | Purpose | Cost | Auth |
|---|---|---|---|
| **Tiingo** | Daily bars (equities, crypto, FX, news) | Free tier / $30/mo | API key |
| **Polygon.io** | Intraday bars, trade/quote data | $29-199/mo | API key |
| **Databento** | Tick + L2 (when needed) | ~$100-500/mo metered | API key |
| **yfinance** | Prototyping only (unreliable, survivorship-biased) | Free | None |

### Monitoring APIs

| Service | Purpose |
|---|---|
| **Grafana** | Dashboards (STARGATE localhost:3000 or dedicated port) |
| **Prometheus** | Metrics collection |
| **ntfy** | Push notifications to phone |
| **~/.local/bin/email** | Email alerts via msmtp |

### External Price Feeds (Already Configured)

| Feed | Endpoint | Used By |
|---|---|---|
| terminal-stocks.dev | `terminal-stocks.dev/<tickers>` | `sb-ticker` statusbar module |
| rate.sx | `<denom>.rate.sx/<target>` | `sb-price` statusbar module |

## 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

| What | Where | Frequency |
|---|---|---|
| Strategy source code | SourceHut (git push) | Every commit |
| TimescaleDB (STARGATE) | Hetzner S3 via restic | Nightly |
| Parquet archives (STARGATE) | Hetzner S3 via restic | Weekly |
| Broker API credentials | Encrypted in password manager, NOT in git | On change |

### Monitoring Health Checks

| Check | Method | Frequency |
|---|---|---|
| Strategy processes alive | systemd status + Prometheus `up` metric | Continuous |
| Data feed freshness | Compare latest tick timestamp vs. wall clock | Every 5 min |
| Disk space on STARGATE | Prometheus node_exporter | Continuous |
| Broker connectivity | Heartbeat ping to each broker API | Every 1 min |
| PnL reconciliation | Compare internal OMS fills vs. broker statement | Daily |

### Failure Modes and Recovery

| Failure | Detection | Recovery |
|---|---|---|
| Strategy crash | systemd auto-restart + alert | Investigate logs; if repeated, disable strategy |
| Data feed stale | Freshness check fires | Switch to backup feed; alert operator |
| Broker API down | Heartbeat failure | Queue orders; alert operator; manual intervention |
| STARGATE power loss | Tailscale offline detection | All strategies have stop-losses at broker level (server-side stops) |
| Corrupted tick data | Checksum mismatch on Parquet read | Restore from restic backup; re-ingest from source |

### 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:

| Domain | Math | Application |
|---|---|---|
| Signal discovery | Time series analysis, stochastic calculus, PCA | Identifying mean-reverting spreads, trending factors, vol surface anomalies |
| Position sizing | Kelly criterion, convex optimization (cvxpy) | Optimal allocation across strategies and positions |
| Risk modeling | Copulas, VaR/CVaR, Monte Carlo simulation | Portfolio-level risk assessment |
| Validation | Hypothesis testing, multiple comparison correction, bootstrap | Deflated Sharpe Ratio, walk-forward, synthetic data testing |
| Execution | Optimal execution theory (Almgren-Chriss), Poisson process models | Minimizing market impact on larger orders |
| Options pricing | Stochastic volatility models (Heston, SABR), PDE methods | Vol surface arbitrage, greeks computation |
| Factor research | Cross-sectional regression, Fama-French, regularization | Building and testing alpha factors |

### 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