Radon

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

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

Contents

• What it does
• Three gates, in order
• Quick start
• Architecture at a glance
• Now true
• Project layout
• Documentation
• Data source priority
• Deployment
• Tests
• Maintainers and help
• License

What it does

• 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.

Three gates, in order

Gate	Rule
Convexity	Potential gain >= 2x potential loss. Defined-risk default.
Edge	Specific, data-backed signal that has not fully moved price.
Risk	Half Kelly (0.5) default, 0.25 optional stricter, full Kelly banned. Hard cap 2.5% of bankroll per position.

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

Quick start

Prerequisites

• Python 3.13 (3.14 has an ib_insync / eventkit incompatibility)
• Use the Node.js major selected by the app image and bun for the terminal (web/). Package-manager ownership: DEVELOPMENT.md.
• Interactive Brokers Gateway (cloud via Tailscale, Docker, or local TWS)
• Accounts at the services in .env.example, web/.env.example, and docs/external-services.md

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. Read those before the operations runbook.

Dev launchers

scripts/cloud.sh    # cloud-thin laptop development
scripts/local.sh    # fully local: laptop runs everything including the IB Gateway Docker container

Choose a mode using the mode-switch procedure, including its Gateway and scheduler precautions. Market-data collection still requires upstream connectivity in local mode.

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

Architecture at a glance

Operator clients, Hetzner spread placement (radon-app / radon-broker), IBKR, outbound-only third parties. Illustrative only, rendered at 39bf6f5e; it omits the app → broker :8340 mTLS Gateway-control edge. Authoritative edges and the host-split runbook: docs/spof-host-split.md.

       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 (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). Direct-to-cloud. Embedded replica 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

Developer runbook: CLAUDE.md.

Now true

Durable facts. History and mechanism live in the owner file, not here.

• Indicators. Regime tabs at /regime/{skew,skew2d,straddle,cor,curve}. Cheap-wing scanner at /scanner?mode=vol-cone. Specs: docs/indicators/.
• CMD+J. Quotes, priced UW chains, and evaluate.py run from the in-app assistant. KB miss is not a dead end.
• Stop orders. Desktop and mobile tickets place STP and STP LMT through /api/orders/place.
• Incidents. Watchdog artifacts under data/incidents/. Triage with /incident <path>. Cases: docs/incident-runbook.md.
• Factory. GitHub issues labeled factory become draft PRs via Foreman in joemccann/radon-factory. Contract: docs/factory.md.

Project layout

radon/
├─ scripts/              Python scanners, evaluators, broker integrations
│  ├─ clients/           Broker and data-provider adapters
│  ├─ api/               FastAPI (:8321)
│  ├─ monitor_daemon/    Background fill/exit/rebalance daemon
│  ├─ db/                Turso writers + migrations
│  ├─ knowledge/         radon-kb MCP (journal, evals, incidents)
│  └─ watchdog/          Service-health alerting
├─ web/                  Next.js 16 terminal (bun)
├─ site/                 Marketing site (npm, separate Vercel project)
├─ cloud/                VPS systemd, Caddy, deploy, IB Gateway compose
├─ docker/ib-gateway/    Laptop IB Gateway compose
├─ lib/tools/            Pi tools (Vitest + CI)
├─ tests/                TWR money-math (CI collects this directory)
├─ docs/                 Topic-scoped documentation (index: docs/README.md)
├─ config/               Laptop launchd plists
├─ brand/                Design system and tokens
└─ CLAUDE.md             Authoritative developer runbook

Documentation

Index: docs/README.md. External services: docs/external-services.md. Equibles: docs/equibles-api.md. Toolchain map: DEVELOPMENT.md.

Data source priority

Follow the source priority and subsystem requirements in docs/external-services.md. Research and news sources do not substitute for missing market data.

Deployment

Merging a reviewed pull request into main triggers the deploy. After the CI gates pass, GitHub Actions extracts cloud/ from the exact tested SHA into an immutable VPS runner and runs its deploy contract.

Canonical infra: cloud/. Recovery: cloud/CLAUDE.md and docs/monorepo-cloud-migration.md. Confirm: gh run list --workflow=ci.yml --limit 1.

Tests

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 && bunx playwright test                   # E2E

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

The isolated TesterArmy flow suites run the workstation and public-site journeys with version-locked browser engines and retain reports and screenshots in CI.

Maintainers and help

Maintained by Joe McCann. Single operator. Clones are unsupported. See SUPPORT.md.

Security reports: SECURITY.md. Do not open a public issue for a vulnerability.

License

Dual-licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option. SPDX-License-Identifier: Apache-2.0 OR MIT

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.