Skip to content
ClearEdge AlgoClearEdge Algo

Development

How to work on ClearEdge: run it, test it, and find your way around the code. For installing and running the app itself, see install and deployment.

Toolchain

Section titled “Toolchain”
  • Backend — Python 3.12 via uv (cd backend && uv sync).
  • Frontend — Node 22 (cd frontend && npm install).
  • pre-commit install (once) runs lint/format/type checks on every commit.

Tests & checks

Section titled “Tests & checks”
Terminal window
# Backend (no network, no services needed)
cd backend
uv run pytest                      # the full backend suite
uv run ruff check . && uv run ruff format --check .   # lint + format
uv run mypy ats                    # types


# Frontend
cd ../frontend
npm test                           # vitest component/unit tests
npm run build                      # type-check + production build
npm run lint                       # eslint

How the tests stay hermetic and honest:

  • Deterministic fixture catalog — tests build on a synthetic, seeded random-walk catalog (no committed vendor data, no network).
  • Recorded vendor traffic — Tiingo calls are replayed from vcrpy cassettes; the LLM (Anthropic) is always mocked. CI never hits a live service.
  • Golden snapshot — tests/test_backtest_job.py pins exact backtest output; a NautilusTrader upgrade (or an intended change) that shifts fills/P&L fails the test and the diff must be reviewed deliberately (delete the golden file to re-record).
  • Docs coverage guard — tests/test_docs_coverage.py fails if any ATS_* setting, registered strategy, computed metric, or API route is undocumented, or any internal doc link is dead.

Project layout

Section titled “Project layout”
Path What lives there
backend/ats/api/routers/ FastAPI routers (auth, data, strategies, backtests, research, reports, paper/live session control, session-history, account probe, gateway, studio, help, ws, …).
backend/ats/strategies/ The built-in strategies + registry (incl. intraday.py), the should_enter rule-test switch, sizing helpers, and the Studio sandbox.py.
backend/ats/workers/ The engines/jobs: backtest runner/job, metrics, walk_forward, wfo, optimize, monte_carlo, rule_test, deflated_sharpe, portfolio, cross_sectional, pairs, kalman, pair_screen, overnight, intraday_relval, portfolio_search, book.
backend/ats/broker/ IB node configs, fees (incl. the intraday SpreadCostFeeModel), the go-live gate, session control/telemetry, the shared session runner, gateway control/monitor.
backend/ats/data/ Tiingo + Databento clients and ingestion, the ParquetDataCatalog helpers, timeframes/resample.
backend/ats/studio/, backend/ats/help/ The NL→strategy codegen + the docs assistant.
backend/ats/db/ SQLAlchemy models + Alembic migrations.
backend/ats/*.py The CLIs: research, sweep, cross_sectional, pairs, pair_screen, overnight, intraday, intraday_relval, portfolio, portfolio_search, book, paper, live, crypto_paper, cli. See command-line research.
frontend/src/ The React SPA (MUI, TanStack Query, klinecharts) — the tabs + the header controls.
infra/ docker-compose (Postgres, Redis, and the paper/live IB Gateway profiles).
docs/ This documentation set, plus the canonical STRATEGY_GUIDE.md and adr/.
scripts/ setup.sh, start.sh, stop.sh, run-paper.sh, gen_api_reference.py.

Adding things

Section titled “Adding things”
  • A strategy — write a file under backend/ats/strategies/ per the contract (and the canonical STRATEGY_GUIDE); tests/test_strategies.py checks it automatically. Then run the ladder: uv run python -m ats.research --strategy <key> --symbols SPY,….
  • An API endpoint — after adding a route, regenerate the API reference so the coverage test passes: cd backend && uv run python ../scripts/gen_api_reference.py. See the API reference.
  • A setting / metric — document it (the configuration / metrics reference) or the coverage guard fails.
Section titled “Related”