Skip to content

ADR-001: Monorepo with Python Backend + TypeScript Frontend

Status

Accepted

Context

We need an architecture that supports: - Quantitative research (Python ecosystem: numpy, scipy, pandas, scikit-learn, pytorch) - Low-latency live trading (event-driven Python with asyncio) - Bloomberg-style web terminal (React/Next.js) - Shared type definitions and contracts across services - Simple local development (single docker compose up)

Decision

Use a monorepo structure with: - Python 3.12+ for all backend services (data, strategies, backtest, risk, execution, live trading, API, signals, bots) - TypeScript (Next.js 15) for the web frontend - uv for Python dependency management - pnpm for JavaScript dependency management - Shared contracts defined in qgtm_core/types.py with Pydantic models, serialized to JSON Schema for TypeScript consumption - Docker Compose for local orchestration

Consequences

  • Single repo simplifies CI/CD, code review, and cross-cutting changes
  • Python gives us access to the full quant finance ecosystem without FFI
  • TypeScript frontend gets full type safety with generated types from Pydantic schemas
  • Monorepo can get large — mitigate with clear module boundaries and sparse checkouts if needed

Alternatives Considered

  • Polyglot with Rust core (nautilus_trader pattern): Higher performance ceiling but dramatically higher complexity and slower iteration for strategy development
  • Separate repos per service: Harder to maintain consistency, version contracts, and make cross-cutting changes
  • Python-only with Dash/Streamlit frontend: Faster to prototype but poor UX ceiling for a Bloomberg-style terminal

References