Skip to content

Architecture

Savvas Leousis edited this page Sep 26, 2026 · 2 revisions

Architecture

Code lives in src/stonks/. Each folder is a block with one job. Blocks talk through small interfaces called seams.

flowchart TB
  subgraph T[Transports]
    CLI[cli.py and python -m entry points]
    API[api]
    MCP[mcp]
    WEB[web console]
  end
  APP[app services]
  subgraph D[Domain]
    ING[ingest]
    LAB[lab]
    BT[backtest]
    PF[portfolio]
    REG[registry]
    PROD[production]
    EXE[execution]
    STR[strategies + features]
    ACC[accounts, connections, notify]
    OPS[scheduling, ops]
  end
  STORE[store<br/>DuckDB lake + SQLite state]
  CORE[core<br/>types, params, protocols]
  WEB --> API
  MCP --> API
  API --> APP
  CLI --> APP
  CLI --> D
  APP --> D
  D --> STORE
  D --> CORE
  STORE --> CORE
Loading

Blocks

Block Owns
core Shared types (Bar, Order, Fill, Portfolio), parameter specs, protocols, intervals, corporate action types.
ingest DataSource adapters (EODHD, Yahoo, DefiLlama), the pipeline, bar quality checks and quarantine.
store DuckDBLake (market data, optional Parquet bar store), SqliteState, SQL migrations.
features Helpers strategies reuse: ATR, volatility, momentum, trend, forecasts, fundamentals, extremes, ...
strategies BaseStrategy, the catalog examples, wrappers (regime, last trade, trailing stop) and the rule-based strategy.
portfolio The construction seam: signals to target weights to orders. Constructors: single_winner, equal_weight_top_n, inverse_vol, vol_target, atr_parity.
lab Runner, tuners, objectives, survival tests and presets, trial ledger, manifest, parallel pool, signal IC.
stats Probabilistic and deflated Sharpe, MinTRL, bootstrap, HAC, PBO, multiple testing.
backtest Engine, SimulatedBroker, fill and cost models, trade ledger, metrics, benchmark, corporate actions.
registry Strategies in SQLite plus files under data/artifacts/<id>/; audited status changes.
production The tick, ranker, model books (shadow), risk rules, hooks, go-live, health, P&L.
execution Brokers (simulated, Alpaca), client ids, reconciliation.
accounts Users, portfolios, subscriptions and the audit log.
connections Read-only broker connections (SnapTrade, Alpaca) synced into portfolios.
security Encryption of stored credentials.
notify Alerts (log, store, webhook) and per-user notifications (Web Push, email, webhook).
scheduling Built-in scheduler, market calendars, dead-man pings, metrics.
ops Backup, verify, restore, prune.
reporting Static HTML report and backtest tear sheets.
app Service layer used by the API, MCP and Studio. No business logic lives in a transport.
api FastAPI REST server with background jobs.
mcp MCP server; a thin client of the REST API.
web/ Angular trader console.

Seams

A seam is an interface. New behavior plugs in behind it without touching the rest.

Seam Plug in a new... Examples today
DataSource data vendor EODHD, Yahoo, DefiLlama
Strategy trading idea 28 catalogued strategies
Tuner parameter search grid, random
Objective score to optimize Sharpe, CAGR, final return
SurvivalTest robustness check 18 tests, found automatically
PortfolioConstructor way to size a book single winner, equal weight, inverse vol, vol target, ATR parity
RiskRule risk limit position and class caps, cash buffer, min order, and six more
PostTickHook, TradeGate step after or before trading position attribution, notifications
Broker place to send orders simulated, Alpaca
CostModel, FillModel trading cost or fill rule per asset class costs; immediate or bar-range fills
BrokerConnection read-only broker link SnapTrade, Alpaca, fake
Notifier, channels alert or delivery channel log, store, webhook, Web Push, SMTP
JobExecutor where scheduled jobs run api, in-process, local

Most registries find their members by scanning a package, so adding a test, rule, hook or constructor is one new file.

Why seams

  • A new strategy never touches tuners or tests; a new test works for every strategy.
  • Third-party libraries (alpaca-py, yfinance, scikit-learn, exchange-calendars, pywebpush) stay behind a seam.
  • Backtest and production share the construction pipeline and the Broker protocol, so strategy code is identical in both.
  • Schemas use domain names, not vendor JSON keys, so a new vendor fills the same tables.

Clone this wiki locally