Repository navigation
Architecture
Savvas Leousis edited this page Sep 26, 2026
·
2 revisions
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
| 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. |
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.
- 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
Brokerprotocol, so strategy code is identical in both. - Schemas use domain names, not vendor JSON keys, so a new vendor fills the same tables.
Source: sleousis/Stonks. Plans and status: docs/roadmap.md.
Start
Concepts
- Architecture
- Data and Storage
- Strategies
- Book Strategies
- Lab and Validation
- Backtesting
- Accounts and Modes
Using Stonks
- Strategy Studio
- Trading Tick
- Risk and Go-Live
- Operations
- Scheduling and Backups
- Deploy
- API and MCP
- Web Console
Reference