# liamryan391/horse_predictor architecture

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

- Interactive diagram: https://gitdiagram.com/liamryan391/horse_predictor
- Repository: https://github.com/liamryan391/horse_predictor

## Overview

Horse Predictor is an operator-facing horse-racing intelligence platform. The main workflow ingests sample or licensed-provider race cards and results, validates and enriches them, stores them, then serves model-ranked runners and operational evidence through a FastAPI API to a React workspace. Separate branches cover model evaluation and registry governance, monitoring and data quality, and the bet journal and admin audit functions. Edges follow explicit README statements or shown imports/calls; unsampled endpoint and frontend wiring is intentionally not inferred.

Main entry points: [`api.py`](https://github.com/liamryan391/horse_predictor/blob/main/api.py) (FastAPI service), [`data_pipeline.py`](https://github.com/liamryan391/horse_predictor/blob/main/data_pipeline.py) (Ingestion worker), [`frontend/src/main.tsx`](https://github.com/liamryan391/horse_predictor/blob/main/frontend/src/main.tsx) (Racing workspace), [`racing_storage.py`](https://github.com/liamryan391/horse_predictor/blob/main/racing_storage.py) (SQL storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Race Data Ingestion"]
  node_pipeline["Ingestion worker<br/>[data_pipeline.py]"]
  node_adapters["Provider adapters"]
  node_quality["Data validation<br/>[data_quality.py]"]
  node_enrichment["Race enrichment<br/>[race_enrichment.py]"]
end

subgraph group_serving["Prediction Service"]
  node_storage[("SQL storage<br/>[racing_storage.py]")]
  node_schema["Race schema<br/>[schema.py]"]
  node_api["FastAPI service<br/>[api.py]"]
  node_model["Prediction model"]
  node_contracts["API contracts<br/>[api_contracts.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
end

subgraph group_operations["Operations and Governance"]
  node_monitoring["Monitoring<br/>[monitoring.py]"]
  node_observability["Logs and tracing<br/>[observability.py]"]
  node_admin["Admin governance<br/>[api.py]"]
end

subgraph group_workspace["Operator Workspace"]
  node_frontend["Racing workspace<br/>[main.tsx]"]
  node_racecentre["Race centre logic<br/>[raceCentre.ts]"]
  node_journal["Bet journal logic<br/>[journal.ts]"]
  node_legacy["Legacy dashboard"]
end

node_operator(("Racing operator"))
node_provider{{"Licensed data provider"}}

node_operator -->|"starts import"| node_pipeline
node_pipeline -->|"fetches races"| node_adapters
node_provider -->|"supplies race data"| node_adapters
node_pipeline -.->|"validates data"| node_quality
node_pipeline -->|"writes race rows"| node_storage
node_pipeline -->|"configures logging"| node_observability
node_adapters -->|"enriches records"| node_enrichment
node_quality -->|"checks enrichment"| node_enrichment
node_storage -->|"defines tables"| node_schema
node_api -->|"reads and records"| node_storage
node_api -->|"scores runners"| node_model
node_api -->|"reports quality"| node_quality
node_api -->|"uses race features"| node_enrichment
node_api -->|"serves monitoring"| node_monitoring
node_api -->|"configures tracing"| node_observability
node_api -->|"uses response models"| node_contracts
node_api -->|"loads configuration"| node_settings
node_api -->|"handles governance"| node_admin
node_operator -->|"reviews workspace"| node_frontend
node_frontend -.->|"requests data"| node_api
node_frontend -->|"uses race logic"| node_racecentre
node_frontend -->|"parses journal"| node_journal
node_operator -->|"uses internal checks"| node_legacy
node_legacy -->|"uses predictions"| node_model
node_legacy -->|"reads race data"| node_storage

click node_pipeline "https://github.com/liamryan391/horse_predictor/blob/main/data_pipeline.py"
click node_adapters "https://github.com/liamryan391/horse_predictor/blob/main/provider_adapters.py"
click node_quality "https://github.com/liamryan391/horse_predictor/blob/main/data_quality.py"
click node_enrichment "https://github.com/liamryan391/horse_predictor/blob/main/race_enrichment.py"
click node_storage "https://github.com/liamryan391/horse_predictor/blob/main/racing_storage.py"
click node_schema "https://github.com/liamryan391/horse_predictor/blob/main/schema.py"
click node_api "https://github.com/liamryan391/horse_predictor/blob/main/api.py"
click node_model "https://github.com/liamryan391/horse_predictor/blob/main/prediction_model.py"
click node_contracts "https://github.com/liamryan391/horse_predictor/blob/main/api_contracts.py"
click node_settings "https://github.com/liamryan391/horse_predictor/blob/main/settings.py"
click node_monitoring "https://github.com/liamryan391/horse_predictor/blob/main/monitoring.py"
click node_observability "https://github.com/liamryan391/horse_predictor/blob/main/observability.py"
click node_admin "https://github.com/liamryan391/horse_predictor/blob/main/api.py"
click node_frontend "https://github.com/liamryan391/horse_predictor/blob/main/frontend/src/main.tsx"
click node_racecentre "https://github.com/liamryan391/horse_predictor/blob/main/frontend/src/raceCentre.ts"
click node_journal "https://github.com/liamryan391/horse_predictor/blob/main/frontend/src/journal.ts"
click node_legacy "https://github.com/liamryan391/horse_predictor/blob/main/horse_racing_app.py"

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_pipeline,node_adapters,node_quality,node_enrichment toneBlue
class node_storage,node_schema,node_api,node_model,node_contracts,node_settings toneAmber
class node_monitoring,node_observability,node_admin toneMint
class node_frontend,node_racecentre,node_journal,node_legacy toneRose
class node_operator,node_provider toneIndigo
```

## Components

### Race Data Ingestion

- [Ingestion worker](https://github.com/liamryan391/horse_predictor/blob/main/data_pipeline.py): `data_pipeline.py`
- [Provider adapters](https://github.com/liamryan391/horse_predictor/blob/main/provider_adapters.py): `provider_adapters.py`
- [Data validation](https://github.com/liamryan391/horse_predictor/blob/main/data_quality.py): `data_quality.py`
- [Race enrichment](https://github.com/liamryan391/horse_predictor/blob/main/race_enrichment.py): `race_enrichment.py`

### Prediction Service

- [SQL storage](https://github.com/liamryan391/horse_predictor/blob/main/racing_storage.py): `racing_storage.py`
- [Race schema](https://github.com/liamryan391/horse_predictor/blob/main/schema.py): `schema.py`
- [FastAPI service](https://github.com/liamryan391/horse_predictor/blob/main/api.py): `api.py`
- [Prediction model](https://github.com/liamryan391/horse_predictor/blob/main/prediction_model.py): `prediction_model.py`
- [API contracts](https://github.com/liamryan391/horse_predictor/blob/main/api_contracts.py): `api_contracts.py`
- [Runtime settings](https://github.com/liamryan391/horse_predictor/blob/main/settings.py): `settings.py`

### Operations and Governance

- [Monitoring](https://github.com/liamryan391/horse_predictor/blob/main/monitoring.py): `monitoring.py`
- [Logs and tracing](https://github.com/liamryan391/horse_predictor/blob/main/observability.py): `observability.py`
- [Admin governance](https://github.com/liamryan391/horse_predictor/blob/main/api.py): `api.py`

### Operator Workspace

- [Racing workspace](https://github.com/liamryan391/horse_predictor/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Race centre logic](https://github.com/liamryan391/horse_predictor/blob/main/frontend/src/raceCentre.ts): `frontend/src/raceCentre.ts`
- [Bet journal logic](https://github.com/liamryan391/horse_predictor/blob/main/frontend/src/journal.ts): `frontend/src/journal.ts`
- [Legacy dashboard](https://github.com/liamryan391/horse_predictor/blob/main/horse_racing_app.py): `horse_racing_app.py`

### Other components

- **Racing operator**
- **Licensed data provider**

## Connections

- Racing operator → Ingestion worker: starts import (evidence: `README.md`)
- Ingestion worker → Provider adapters: fetches races (evidence: `data_pipeline.py`)
- Licensed data provider → Provider adapters: supplies race data (evidence: `README.md`)
- Ingestion worker → Data validation: validates data
- Ingestion worker → SQL storage: writes race rows (evidence: `data_pipeline.py`)
- Ingestion worker → Logs and tracing: configures logging (evidence: `data_pipeline.py`)
- Provider adapters → Race enrichment: enriches records (evidence: `provider_adapters.py`)
- Data validation → Race enrichment: checks enrichment (evidence: `data_quality.py`)
- SQL storage → Race schema: defines tables (evidence: `racing_storage.py`)
- FastAPI service → SQL storage: reads and records (evidence: `api.py`)
- FastAPI service → Prediction model: scores runners (evidence: `api.py`)
- FastAPI service → Data validation: reports quality (evidence: `api.py`)
- FastAPI service → Race enrichment: uses race features (evidence: `api.py`)
- FastAPI service → Monitoring: serves monitoring (evidence: `api.py`)
- FastAPI service → Logs and tracing: configures tracing (evidence: `api.py`)
- FastAPI service → API contracts: uses response models (evidence: `api.py`)
- FastAPI service → Runtime settings: loads configuration (evidence: `api.py`)
- FastAPI service → Admin governance: handles governance (evidence: `README.md`)
- Racing operator → Racing workspace: reviews workspace (evidence: `README.md`)
- Racing workspace → FastAPI service: requests data
- Racing workspace → Race centre logic: uses race logic (evidence: `frontend/src/main.tsx`)
- Racing workspace → Bet journal logic: parses journal (evidence: `frontend/src/main.tsx`)
- Racing operator → Legacy dashboard: uses internal checks (evidence: `README.md`)
- Legacy dashboard → Prediction model: uses predictions (evidence: `horse_racing_app.py`)
- Legacy dashboard → SQL storage: reads race data (evidence: `horse_racing_app.py`)
