# indubitablysrivathsan/hippodrome architecture

> Architecture diagram of the GitHub repository indubitablysrivathsan/hippodrome, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/indubitablysrivathsan/hippodrome
- Repository: https://github.com/indubitablysrivathsan/hippodrome

## Overview

Hippodrome combines Indian horse-racing data ingestion and a DuckDB-backed browsing API with a research workflow that transforms betting odds into entropy signals for market analysis. The README documents the four-stage processing sequence and DSP topics; the tree also shows parsers, API routes and a React interface. Several modules and later pipeline steps were not sampled, so links involving those components reflect documented workflow or are omitted where wiring is uncertain.

Main entry points: [`api/main.py`](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/main.py) (API application), [`pipeline/03_build_signal.py`](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/pipeline/03_build_signal.py) (Entropy signal), [`api/db.py`](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/db.py) (Database access), [`db/migration.py`](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/db/migration.py) (DuckDB migration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_parsers["Document parsers"]
  node_etl["DuckDB migration<br/>[migration.py]"]
  node_race_store[("Race database")]
end

subgraph group_research["Signal research"]
  node_odds["Parse odds<br/>[01_parse_odds.py]"]
  node_features["Race features"]
  node_signal["Entropy signal<br/>[03_build_signal.py]"]
  node_calibration["Calibration bins"]
  node_entropy_analysis["Entropy distribution"]
  node_efficiency["Market efficiency"]
  node_calibration_analysis["Calibration analysis"]
  node_lz_analysis["LZ compressibility"]
  node_regimes["Regime detection"]
end

subgraph group_service["Horse racing API"]
  node_api_main["API application<br/>[main.py]"]
  node_db_access["Database access<br/>[db.py]"]
  node_venue_routes["Venue routes<br/>[venues.py]"]
  node_meeting_routes["Meeting routes<br/>[meetings.py]"]
  node_race_routes["Race routes<br/>[races.py]"]
  node_runner_routes["Runner routes<br/>[runners.py]"]
  node_entity_routes["Horse and people routes"]
  node_schema_routes["Schema and stats<br/>[schema.py]"]
end

subgraph group_interface["Browser interface"]
  node_app["Web application<br/>[App.jsx]"]
  node_pages["Data pages"]
  node_fetch["Fetch state<br/>[useFetch.js]"]
  node_client["API client<br/>[client.js]"]
end

node_source_data["Race source data"]
node_web_user(("Browser user"))
node_api_service{{"HTTP API"}}

node_source_data -->|"parse documents"| node_parsers
node_source_data -->|"load source files"| node_etl
node_etl -->|"writes records"| node_race_store
node_source_data -->|"raw race CSVs"| node_odds
node_odds -->|"market entries"| node_features
node_features -->|"race features"| node_signal
node_signal -->|"build bins"| node_calibration
node_signal -->|"analyze signal"| node_entropy_analysis
node_signal -->|"analyze signal"| node_efficiency
node_signal -->|"read signal"| node_lz_analysis
node_signal -->|"analyze signal"| node_regimes
node_calibration -->|"read bins"| node_calibration_analysis
node_api_main -->|"registers"| node_venue_routes
node_api_main -->|"registers"| node_meeting_routes
node_api_main -->|"registers"| node_race_routes
node_api_main -->|"registers"| node_runner_routes
node_api_main -->|"registers"| node_entity_routes
node_api_main -->|"registers"| node_schema_routes
node_venue_routes -->|"database access"| node_db_access
node_meeting_routes -->|"database access"| node_db_access
node_race_routes -->|"database access"| node_db_access
node_runner_routes -->|"database access"| node_db_access
node_entity_routes -->|"database access"| node_db_access
node_schema_routes -->|"database access"| node_db_access
node_web_user -->|"browses"| node_app
node_app -->|"routes views"| node_pages
node_pages -->|"loads data"| node_fetch
node_fetch -->|"requests"| node_client
node_client -->|"HTTP requests"| node_api_service
node_api_service -->|"dispatches"| node_api_main

click node_parsers "https://github.com/indubitablysrivathsan/hippodrome/tree/paddock/data"
click node_etl "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/db/migration.py"
click node_odds "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/pipeline/01_parse_odds.py"
click node_features "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/pipeline/02_build_race_features.py"
click node_signal "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/pipeline/03_build_signal.py"
click node_calibration "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/pipeline/04_build_calibration.py"
click node_entropy_analysis "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/analysis/entropy_distribution.py"
click node_efficiency "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/analysis/market_efficiency.py"
click node_calibration_analysis "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/analysis/calibration_curve.py"
click node_lz_analysis "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/analysis/lz_compressibility.py"
click node_regimes "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/analysis/regime_detection.py"
click node_api_main "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/main.py"
click node_db_access "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/db.py"
click node_venue_routes "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/routes/venues.py"
click node_meeting_routes "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/routes/meetings.py"
click node_race_routes "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/routes/races.py"
click node_runner_routes "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/routes/runners.py"
click node_entity_routes "https://github.com/indubitablysrivathsan/hippodrome/tree/paddock/api/routes"
click node_schema_routes "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/routes/schema.py"
click node_app "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/frontend/src/App.jsx"
click node_pages "https://github.com/indubitablysrivathsan/hippodrome/tree/paddock/frontend/src/pages"
click node_fetch "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/frontend/src/api/useFetch.js"
click node_client "https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/frontend/src/api/client.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_parsers,node_etl,node_race_store,node_web_user toneBlue
class node_odds,node_features,node_signal,node_calibration,node_entropy_analysis,node_efficiency,node_calibration_analysis,node_lz_analysis,node_regimes toneAmber
class node_api_main,node_db_access,node_venue_routes,node_meeting_routes,node_race_routes,node_runner_routes,node_entity_routes,node_schema_routes,node_api_service toneMint
class node_app,node_pages,node_fetch,node_client toneRose
class node_source_data toneIndigo
```

## Components

### Data ingestion

- [Document parsers](https://github.com/indubitablysrivathsan/hippodrome/tree/paddock/data): `data`
- [DuckDB migration](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/db/migration.py): `db/migration.py`
- **Race database**

### Signal research

- [Parse odds](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/pipeline/01_parse_odds.py): `pipeline/01_parse_odds.py`
- [Race features](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/pipeline/02_build_race_features.py): `pipeline/02_build_race_features.py`
- [Entropy signal](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/pipeline/03_build_signal.py): `pipeline/03_build_signal.py`
- [Calibration bins](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/pipeline/04_build_calibration.py): `pipeline/04_build_calibration.py`
- [Entropy distribution](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/analysis/entropy_distribution.py): `analysis/entropy_distribution.py`
- [Market efficiency](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/analysis/market_efficiency.py): `analysis/market_efficiency.py`
- [Calibration analysis](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/analysis/calibration_curve.py): `analysis/calibration_curve.py`
- [LZ compressibility](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/analysis/lz_compressibility.py): `analysis/lz_compressibility.py`
- [Regime detection](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/analysis/regime_detection.py): `analysis/regime_detection.py`

### Horse racing API

- [API application](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/main.py): `api/main.py`
- [Database access](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/db.py): `api/db.py`
- [Venue routes](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/routes/venues.py): `api/routes/venues.py`
- [Meeting routes](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/routes/meetings.py): `api/routes/meetings.py`
- [Race routes](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/routes/races.py): `api/routes/races.py`
- [Runner routes](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/routes/runners.py): `api/routes/runners.py`
- [Horse and people routes](https://github.com/indubitablysrivathsan/hippodrome/tree/paddock/api/routes): `api/routes`
- [Schema and stats](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/api/routes/schema.py): `api/routes/schema.py`

### Browser interface

- [Web application](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Data pages](https://github.com/indubitablysrivathsan/hippodrome/tree/paddock/frontend/src/pages): `frontend/src/pages`
- [Fetch state](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/frontend/src/api/useFetch.js): `frontend/src/api/useFetch.js`
- [API client](https://github.com/indubitablysrivathsan/hippodrome/blob/paddock/frontend/src/api/client.js): `frontend/src/api/client.js`

### Other components

- **Race source data**
- **Browser user**
- **HTTP API**

## Connections

- Race source data → Document parsers: parse documents
- Race source data → DuckDB migration: load source files
- DuckDB migration → Race database: writes records
- Race source data → Parse odds: raw race CSVs
- Parse odds → Race features: market entries
- Race features → Entropy signal: race features
- Entropy signal → Calibration bins: build bins
- Entropy signal → Entropy distribution: analyze signal
- Entropy signal → Market efficiency: analyze signal
- Entropy signal → LZ compressibility: read signal
- Entropy signal → Regime detection: analyze signal
- Calibration bins → Calibration analysis: read bins
- API application → Venue routes: registers
- API application → Meeting routes: registers
- API application → Race routes: registers
- API application → Runner routes: registers
- API application → Horse and people routes: registers
- API application → Schema and stats: registers
- Venue routes → Database access: database access
- Meeting routes → Database access: database access
- Race routes → Database access: database access
- Runner routes → Database access: database access
- Horse and people routes → Database access: database access
- Schema and stats → Database access: database access
- Browser user → Web application: browses
- Web application → Data pages: routes views
- Data pages → Fetch state: loads data
- Fetch state → API client: requests
- API client → HTTP API: HTTP requests
- HTTP API → API application: dispatches