Market-structure reconstruction. Radon surfaces convex options trades from dark pool and OTC flow, the volatility surface, and cross-asset positioning. The system runs every candidate through a hard three-gate framework before sizing it.

Flow signal or nothing. No narrative trades, no chart-pattern trades.

• What it does
• Three gates, in order
• Quick start
• External services
• Architecture at a glance
• Recent additions
• What's where
• Project layout
• Data source priority
• Deployment
• Tests
• Glossary

• Detects institutional positioning through Interactive Brokers, Unusual Whales, MenthorQ CTA, and cross-asset feeds.
• Designs convex options structures and sizes them with fractional Kelly.
• Streams live quotes, greeks, P&L, and order state to a Next.js terminal at localhost:3000 (laptop dev) and app.radon.run (production).
• Auto-deploys to a Hetzner VPS on every push to main.

Any gate fails, no trade. Full rules in CLAUDE.md. Strategy specs in docs/strategies.md.

Prerequisites

• Python 3.13 (3.14 has an ib_insync / eventkit incompatibility)
• Node.js 18+ and bun (npm is not used for the JS stack)
• Interactive Brokers Gateway (cloud via Tailscale, Docker, or local TWS)
• Accounts at the external services listed below — start with .env.example and web/.env.example, both fully annotated with sign-up URLs

git clone https://github.com/joemccann/radon.git
cd radon
cp .env.example .env             # then fill in
cp web/.env.example web/.env     # then fill in
pip install -r requirements.txt
cd web && bun install && cd ..

The two .env.example files are the canonical variable reference — every required and optional key has an inline comment with purpose, format, and required-vs-optional. Read those before the operations runbook.

Dev launchers

scripts/cloud.sh    # default: laptop runs Next.js + newsfeed, VPS serves FastAPI/relay/IB Gateway over Tailscale
scripts/local.sh    # fully local: laptop runs everything including the IB Gateway Docker container

cloud.sh is the everyday workflow. local.sh is for offline dev or when the VPS is down. Mode persists to .env.ib-mode; toggle later via scripts/ib mode local|cloud.

Open http://localhost:3000. Clerk auto-bypasses on localhost in non-production.

Radon is glued together from a long list of third-party services. The full env-var matrix lives in .env.example and web/.env.example; the table below summarises why each one is there and where to sign up.

Production .env lives on the VPS at /home/radon/radon-cloud/.env. Laptop dev uses the root .env for FastAPI and scripts, plus web/.env for Next.js (some keys are duplicated because Next.js can't read the root file from inside web/).

       Unusual Whales ─┐
   Interactive Brokers ├──> Signal Detection ──> Strategy Evaluation
            MenthorQ ──┘                              │
                                                      ▼
                                          Convex Structure Builder
                                                      │
                                                      ▼
                                          Kelly Position Sizing
                                                      │
                                                      ▼
                                          Execution / Monitoring
                                                      │
                                                      ▼
                                              Radon Terminal

Process layout

• localhost:3000 for the Next.js 16 terminal
• :8321 for FastAPI (40+ endpoints, JWT-gated, localhost bypass for server-to-server)
• :8765 for the IB realtime WebSocket relay
• 120s loop for the newsfeed scraper (headless Playwright)

Storage

• Turso libSQL cloud DB (canonical). Every Radon process talks directly to cloud — no embedded replica anywhere (retired 2026-05-20; see docs/cloud-services.md)
• JSON files in data/ as fallback / DR archive
• Hetzner-hosted media.radon.run for newsfeed images

Full architecture and the Phase 0-6 migration history live in docs/cloud-services.md. The developer runbook is CLAUDE.md.

Things that shipped in the last few weeks and are worth knowing about:

• No-replica DB architecture (2026-05-20). Every Radon process now goes direct-to-cloud — the code default since DUR-07, with the replica opt-in only via RADON_DB_USE_REPLICA=1 and RADON_DB_NO_REPLICA=1 kept as a fleet-wide systemd kill switch. The libsql embedded-replica model (data/replica.db) was retired after two same-day incidents: multi-writer WAL contention then single-writer frame conflicts. Reads cost +30–60 ms cloud round-trip, absorbed by SWR caching.
• Stuck-awaiting-2FA self-heal (2026-05-20). ib_watchdog.is_stuck_awaiting_2fa() fires a fresh IBKR Mobile push after 3 cycles of auth_state=awaiting_2fa with no push lock holder. Eliminates the human-in-the-loop dependency where the system used to sit stuck overnight.
• Authoritative footer IB status (2026-05-20). Sidebar + MobileAppBar derive a single displayStatus (CONNECTED / AWAITING 2FA / DEGRADED / UNREACHABLE / OFFLINE / RELAY OFFLINE) from FastAPI /health rather than the WS-relay's stale ib_connected flag. Footer and banner can no longer contradict each other.
• monitor_daemon handlers on client_id="auto" (2026-05-20). fill_monitor, exit_orders, journal_sync rotate across SUBPROCESS_ID_RANGE instead of hardcoded 70/71/72 — eliminates the half-open-socket "client id already in use" failure mode.
• Closing-trade exception in risk model (2026-05-20). OrderRiskLeg.coveringLongContracts lets the risk panel recognise a SELL of a held LONG as a close (or partial close) instead of flagging it UNBOUNDED. Symmetric for puts. SELL beyond held quantity flags only the excess.
• Autonomous Hetzner timers for vcg-scan, portfolio-sync, and cta-sync replaced the previous browser-driven refresh model. Data stays fresh even when no tab is open.
• Service-health watchdog with four buckets (intraday, continuous, daily, error), Pushover routing (P1 only), cooldown, hysteresis, and python -m scripts.watchdog ack <service> to silence noise.
• Banner categories. scheduled services flip red on stale; on-demand services show an amber dormant chip and are excluded from alerting.
• /usr/local/bin/radon operator CLI auto-enumerates every loaded radon-* unit, so new timers don't require script edits. Installed durably by setup-vps.sh.
• Cash flow throttle backoff. IBKR Flex codes 1001 / 1018 / 1019 trip an exponential circuit breaker (24h to 168h cap) so the script doesn't perpetuate a sliding-window throttle.
• CRI history zoom. The CRI spread chart now carries ~251 trading days of history with a brush-driven zoom UI and preset range chips.
• Banner humanization. service_health.last_error JSON is rewritten into operator-friendly copy before render.
• parseScanTime normalises naive Python ISO timestamps on the JS side so date-day drift can't surface in the UI.
• 2FA-aware IB Gateway restart with exponential backoff, cross-process push lock, and auth_state reporting. POST /ib/reset-backoff is the operator escape hatch.

radon/
├─ scripts/              Python scanners, evaluators, broker integrations
│  ├─ clients/           Broker and data-provider adapters
│  ├─ monitor_daemon/    Background fill/exit/rebalance daemon
│  ├─ db/                Turso writers + migrations
│  └─ watchdog/          Service-health alerting
├─ web/                  Next.js 16 terminal + FastAPI server scripts
├─ site/                 Standalone marketing site (separate Vercel project)
├─ docs/                 Topic-scoped documentation
├─ data/                 Runtime artifacts (gitignored except taxonomy + presets)
├─ config/               launchd plists and service configuration
├─ brand/                Design system and tokens
└─ CLAUDE.md             Authoritative developer runbook

Strict order for any price / flow / chain lookup. The full external-service inventory is in External services above.

1. Interactive Brokers for real-time quotes, options chains, and portfolio state
2. Unusual Whales for dark pool flow, sweeps, options flow, and analyst data
3. Cboe official feeds for COR1M historical fallback
4. Yahoo Finance as a strict last resort

Never skip to Yahoo or web scrape without trying IB then Unusual Whales first. Research surfaces (Exa) and news (themarketear, MenthorQ) are orthogonal — they don't substitute for missing price data.

git push origin main is the deploy. .github/workflows/ci.yml runs the Vitest + pytest gate then deploys on green: it SSHes to the Hetzner VPS and runs bash scripts/deploy.sh:

1. git reset --hard origin/main
2. pip install -r requirements.txt
3. npm install (the VPS uses npm, not bun) then next build --experimental-build-mode=compile
4. sudo systemctl restart radon-{nextjs,api,relay,monitor,newsfeed} with health-gated rollback

Confirm with gh run list --workflow=ci.yml --limit 1. Full operational detail in docs/operations.md. The systemd units, Caddy config, and Docker Compose project for IB Gateway live in a sibling radon-cloud repo.

python3.13 scripts/run_pytest_affected.py        # scoped Python tests
python -m pytest scripts/tests/ -v               # full Python suite
cd web && bun test                               # Vitest
cd web && npx playwright test                    # E2E

Mocked API calls cover most of the surface, so development rarely needs a live broker session. Order-route integration uses an isolated test-mode FastAPI harness (web/tests/fastapiHarness.ts) that never reuses the broker-backed localhost:8321 server.