How braedonsaunders/homerun works
1. Overall shape
- Homerun is a full-stack trading platform centered on a Python backend and a React/TypeScript frontend.
- The backend is the system of record and runtime controller; the frontend is an operational console for editing, validating, backtesting, monitoring, and executing strategies and data sources.
2. Backend API layer
- backend/main.py boots a FastAPI application.
- Route modules under backend/api/ partition the surface by domain: strategies, data sources, traders, discovery, news, weather, AI, ML, simulation, settings, workers, and execution/orchestration.
- WebSocket support is part of the backend API, not a separate service, and is used for live UI updates and real-time state distribution.
3. Persistent core and schema evolution
- PostgreSQL is the main persistence layer, accessed asynchronously through SQLAlchemy models in backend/models/.
- Alembic migrations in backend/alembic/versions/ show heavy schema evolution around strategy/version management, data-source records, trader state, discovery profiles, live trading state, notifications, and ML/AI artifacts.
- This indicates the architecture is DB-driven: runtime behavior, configuration, and history are mostly stored rather than hardcoded.
4. Strategy runtime as a first-class subsystem
- Strategies live in backend/services/strategies/ and are implemented as Python classes with lifecycle methods such as detection, evaluation, and exit logic.
- backend/services/strategy_runtime.py, strategy_loader.py, strategy_sdk.py, and strategy_versioning.py form the machinery for loading strategies from the DB, hot-reloading them, validating them, and running them against markets and events.
- Strategies consume market data, source records, and events, then emit opportunities/signals into the rest of the system.
5. Data source ingestion pipeline
- Custom and built-in data sources are managed through backend/services/data_source_* modules.
- The runtime pattern is fetch → transform → normalize → upsert into stored records, with SDK support for writing custom sources in Python.
- Sources can be RSS, REST, WebSockets, Chainlink, Binance, Twitter/X, or custom Python, and they feed both direct strategy reads and event-driven updates.
6. Eventing and live state propagation
- backend/services/event_bus.py, event_dispatcher.py, signal_bus.py, and runtime_signal_queue.py provide the internal pub/sub and queueing layer.
- Background workers and strategy runtimes subscribe to data-source updates, market refreshes, and operational events.
- The frontend receives live state over WebSockets, which means UI panels are driven by event streams rather than polling alone.
7. Worker-based background processing
- backend/workers/ contains separate worker processes for scanner, discovery, news, weather, events, traders, market universe, reconciliation, Cortex, and SLO/monitoring tasks.
- These workers are the execution boundary for periodic, streaming, and reconciliation jobs; they keep the API responsive and separate long-running market processing from request handling.
- The architecture is intentionally horizontally decomposed by concern rather than as one monolithic loop.
8. Trading and execution pipeline
- Trading is handled by backend/services/trader_orchestrator/ plus adjacent execution services like live_execution_service.py, live_execution_adapter.py, fill_monitor.py, and trading_proxy.py.
- The lifecycle is multi-stage: detect → evaluate → preflight/risk gate → arm → execute → monitor/reconcile.
- Execution targets include paper/simulation and live venues such as Polymarket and Kalshi, with venue-specific logic abstracted behind adapters and orchestrator policies.
9. Risk, sizing, and safety controls
- Risk management is not peripheral; it is embedded in the execution path through decision gates, exposure limits, inventory checks, liquidity checks, Kelly sizing, token circuit breakers, and order verification.
- Separate validation and maintenance services support safe enabling, disabling, and cleanup of strategies/traders.
- This forms a hard boundary between signal generation and trade placement.
10. Discovery, wallets, and trader intelligence
- There is a distinct discovery layer for finding and scoring wallets/traders, centered around wallet tracking, clustering, network analysis, and copy-trading logic.
- Services such as wallet_discovery.py, wallet_intelligence.py, trader_data_access.py, traders_copy_trade_signal_service.py, and trader_hot_state.py support this subsystem.
- It feeds trader-oriented opportunities into the shared signal and execution stack, but with its own profiling, ranking, and runtime state.
11. AI and research subsystem
- backend/services/ai/ contains LLM provider abstraction, agent/memory/tooling, market analysis, news sentiment, and opportunity judging.
- The Cortex-related modules and AI route surface suggest a self-contained research/assistant layer that can read platform state, call tools, and write outputs back into the system.
- The AI layer is integrated with the domain model rather than acting as a standalone chat feature.
12. Specialized vertical workflows
- News, weather, crypto, events, and market-monitoring each have their own service subtrees and orchestration modules.
- Examples include news/workflow_orchestrator.py, weather/workflow_orchestrator.py, crypto_service.py, market_monitor.py, and scanner.py.
- These are domain pipelines that normalize external signals into the same opportunity/data/event backbone used by strategies and traders.
13. Frontend architecture
- The frontend is a React app in frontend/src/, with feature panels for strategies, traders, discovery, news intelligence, AI, ML models, markets, settings, and trading.
- API access is encapsulated in frontend/src/services/, while live updates are handled through hooks such as WebSocket and realtime invalidation.
- UI state is organized around operational views, not generic CRUD screens, reflecting the backend’s domain-centric architecture.
14. Operational tooling and environment
- The repo includes launcher scripts, Docker/Postgres setup, CI workflows, tests, and migration tooling, showing that the project is meant to run as a locally deployable platform with reproducible infrastructure.
- The desktop launcher and scripts/infra/ helpers indicate a “single-command” local environment, while tests cover runtime, execution, simulation, data ingestion, and UI-integrated behaviors.
- For an architecture diagram, the key deployment boundary is: external data/venue providers on the edge, backend services/workers in the middle, PostgreSQL as state, and the React dashboard as the operator console.
Main entry points: routes.py API Routes · event_bus.py Event Bus · App.tsx React App · session_engine.py Trader Orchestrator
Components 19
Backend
FastAPI API, domain services, workers, and persistence-backed runtime.
- API App · Boots the backend application and mounts the HTTP/WebSocket surface.
backend/main.py - API Routes · Domain-partitioned route modules for strategies, traders, data, AI, discovery, and execution.
backend/api/routes.py - WebSocket Hub · Pushes real-time state and events to the UI.
backend/api/websocket.py - Strategy Runtime · Loads, versions, validates, and executes DB-backed strategies.
backend/services/strategy_runtime.py - Data Sources · Fetches, transforms, normalizes, and stores external market/data feeds.
backend/services/data_source_runner.py - Event Bus · Internal signal, queue, and dispatcher layer for runtime propagation.
backend/services/event_bus.py - Trader Orchestrator · Coordinates detect→gate→execute→monitor lifecycle for trading.
backend/services/trader_orchestrator/session_engine.py - Risk Gates · Decision gates, sizing, exposure, verification, and order safety checks.
backend/services/trader_orchestrator/risk_manager.py - Execution Service · Live and simulated execution adapters, fills, monitoring, and venue abstraction.
backend/services/live_execution_service.py - Discovery Stack · Wallet discovery, clustering, scoring, and copy-trade signal generation.
backend/services/wallet_discovery.py - AI Layer · Cortex and assistant services for analysis, tools, prompts, and model integration.
backend/services/ai/agent.py - Domain Pipelines · Specialized workflows for news, weather, crypto, scanning, and market monitoring.
backend/services/news/workflow_orchestrator.py - Workers · Separate worker processes for scanner, discovery, news, weather, traders, reconciliation, and monitoring.
backend/workers/runner.py
Frontend
React operator console and API client layer.
- React App · Operator-facing React application for monitoring and control.
frontend/src/App.tsx - Ops Panels · Strategy, trader, discovery, news, AI, ML, settings, and trading views.
frontend/src/components/StrategiesPanel.tsx - API Client · Frontend API wrappers for backend domains and state mutation.
frontend/src/services/api.ts - Realtime Hook · WebSocket and invalidation hooks for live UI updates.
frontend/src/hooks/useWebSocket.ts
State
Database schema, models, and migrations that hold platform state.
- Models · Async SQLAlchemy models for market, opportunity, and platform state.
backend/models/database.py - Migrations · Alembic history for strategy, trader, discovery, execution, and AI/ML tables.
backend/alembic/versions/202602130001_baseline_schema.py
Connections 24
- API App → API Routes: mounts · Application startup attaches the domain route surface.
- API App → WebSocket Hub: serves · The backend exposes live update channels alongside HTTP endpoints.
- API Routes → Strategy Runtime: controls · Strategy endpoints create, validate, backtest, and execute strategy lifecycles.
- API Routes → Data Sources: manages · Routes configure and inspect external data sources.
- API Routes → Trader Orchestrator: orchestrates · Routes expose trader lifecycle and execution controls.
- API Routes → Discovery Stack: serves · Discovery routes surface wallet and trader intelligence.
- API Routes → AI Layer: exposes · AI routes provide agent, model, and research surfaces.
- API Routes → Domain Pipelines: exposes · Domain workflows for news, weather, crypto, and scanning are routed here.
- Strategy Runtime → Event Bus: publishes · Strategy outcomes and runtime state are emitted into internal signals.
- Data Sources → Event Bus: publishes · Ingested updates are normalized and broadcast to downstream consumers.
- Event Bus → WebSocket Hub: feeds · Shared events are pushed through WebSockets to the operator UI.
- Event Bus → Workers: consumed by · Background jobs subscribe to internal signals and queues.
- Trader Orchestrator → Risk Gates: gated by · Execution passes through safety, sizing, and preflight checks.
- Trader Orchestrator → Execution Service: executes via · The orchestrator sends orders and monitors fills through execution services.
- Discovery Stack → Event Bus: publishes · Wallet and trader intelligence emits signals into the shared runtime.
- AI Layer → Models: reads/writes · AI features are backed by persisted models and platform state.
- Domain Pipelines → Event Bus: feeds · Specialized pipelines normalize domain events into the common backbone.
- Workers → Models: persists · Workers update runtime, reconciliation, and domain state in the database.
- Models → Migrations: evolves via · Database schema is shaped by repeated Alembic migrations.
- React App → Ops Panels: renders · The React shell composes the major operational panels.
- React App → API Client: uses · UI components call backend APIs through a shared client layer.
- React App → Realtime Hook: subscribes · The frontend receives live state through WebSocket hooks.
- API Client → API Routes: calls · Frontend client modules map to the backend route surface.
- Realtime Hook → WebSocket Hub: connects · Realtime UI state is synchronized over backend WebSockets.