Architecture

Technical stack

The hybrid TypeScript web + Python core architecture, the control-plane / trading-core / event-boundary split, and the concrete technologies behind each layer.

Clawlas uses two programming ecosystems, each for what it handles best: a TypeScript web layer and a Python research/execution core, joined by a Valkey/Redis event boundary. The whole system is self-hosted on one VPS with Docker.

Hybrid topology

Three cooperating planes plus an event boundary. Convex is the control plane and application state — never the low-latency execution engine.

Web app (TypeScript)        Vite · React · Convex · dashboard
        │ commands / events
Python control plane         API · model router · LangGraph · approvals
        │ Valkey / Redis Streams (event boundary)
Python trading core          discovery · CCXT & on-chain adapters
                             venue resolver · risk · execution · reconcile
        │
   CCXT venues · DEX / chains · data providers

TypeScript web → Python control plane → Valkey/Redis boundary → Python trading core → venues, chains and data providers.

The two ecosystems

Ecosystem	Owns
TypeScript	Web app & dashboard, Convex functions, frontend state, strategy configuration, human-approval and validation interfaces, real-time updates.
Python	CCXT & exchange WebSockets, ingestion & normalization, quant & statistics, strategies, agents, the model router, venue resolver, risk, execution, reconciliation and on-chain adapters.

Final stack

Concern	Technology
Frontend	TanStack Start (Vite) · React · TypeScript · Tailwind · shadcn/ui
Routing & tables	TanStack Router · TanStack Table
Charts	Lightweight Charts · Apache ECharts
Web backend / control plane	Convex (self-hosted) · FastAPI · Pydantic · uv
Agents & routing	LangGraph · provider-independent gateway · LiteLLM (evaluated)
Local / OSS inference	Ollama · llama.cpp · vLLM (future dedicated GPU)
Quant	NumPy · pandas · SciPy · statsmodels · scikit-learn · TA-Lib / pandas-ta
Backtesting	vectorbt · event-driven simulator · Backtrader (optional)
Market & chain	CCXT / CCXT Pro · direct adapters · web3.py · Jupiter / 0x / 1inch
Venue layer	VenueAdapter interface · CCXT / Jupiter / EVM-router / native / paper adapters
Memory	SQLite · SQLAlchemy/SQLModel · FTS5 · sqlite-vec (optional)
Analytics & events	Parquet · DuckDB · Valkey / Redis Streams
Jobs & cache	Valkey · BullMQ / Dramatiq / Celery
Cost & budget	usage logs · model registry · per-scope budgets · degradation policy
Infra	Docker · Docker Compose · Caddy · GitHub Actions
Observability	Prometheus · Grafana · Loki · Uptime Kuma
Backups	Restic → Cloudflare R2

TanStack Start
Convex
FastAPI
LangGraph
LiteLLM
Ollama
DuckDB
Valkey
BullMQ
CCXT
web3.py
Restic

Recorded stack decision (vNext)

Keep Python for the trading/AI core (CCXT, strategies, quant, model router, agents), keep Valkey/Redis as the async boundary, and keep TypeScript for the Vite/Convex app. New concepts (CCXT centrality, venue adapters, trust tiers, model router, cost control, reliability) are added without a runtime migration. A move to TypeScript is considered only component-by-component, and only when measurements show the benefit exceeds the cost.

Rejected on purpose

Standalone SSR (Next.js) — not needed for a private dashboard. Kubernetes — Docker Compose is enough for a personal VPS. Convex as the only database — memory and analytics live in SQLite and Parquet/DuckDB. SQLite for high-frequency market data — that is Parquet’s job. A full TS rewrite for CCXT — same venues, same limits, no functional gain. AI-only decisions and direct LLM access to exchanges — both forbidden.