# nkosikhona-ai/sa-quant-racing-predictor architecture

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

- Interactive diagram: https://gitdiagram.com/nkosikhona-ai/sa-quant-racing-predictor
- Repository: https://github.com/nkosikhona-ai/sa-quant-racing-predictor

## Overview

SA Quant Racing Predictor turns a Computaform/PhotoForm race-card PDF into extracted runners, configurable race predictions and betting intelligence. The main Streamlit workflow accepts and segments the meeting, lets users set race context and odds, invokes the prediction engine, and presents rankings, EV/value signals, race navigation, and exotic combinations. README-described model variants and meeting-level bets are represented, though their detailed implementations were not sampled. The app imports the extractor and predictor; relationships beyond the shown code and README are omitted or marked unverified.

Main entry points: [`app.py`](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py) (Streamlit app), [`predictor.py`](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/predictor.py) (Prediction engine), [`extractor.py`](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/extractor.py) (PDF parser), [`index.html`](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/index.html) (Static fallback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Race-card ingestion"]
  node_streamlit["Streamlit app<br/>[app.py]"]
  node_parser["PDF parser<br/>[extractor.py]"]
  node_racefields["Race setup<br/>[app.py]"]
end

subgraph group_predict["Prediction engine"]
  node_prediction["Prediction engine<br/>[predictor.py]"]
  node_trackmodels["Track models<br/>[predictor.py]"]
  node_calibration["ML calibration<br/>[predictor.py]"]
  node_modelartifact["Calibration model"]
end

subgraph group_experience["Betting interface"]
  node_odds["Odds editor<br/>[app.py]"]
  node_rankings["Race rankings<br/>[app.py]"]
  node_value["EV and value<br/>[app.py]"]
  node_racebrowse["Race navigation<br/>[app.py]"]
  node_exotics["Exotic bets<br/>[app.py]"]
  node_meetingbets["Multi-race bets<br/>[app.py]"]
  node_matrix["EV meeting matrix<br/>[app.py]"]
  node_texttables["Copyable tables<br/>[app.py]"]
end

subgraph group_fallback["Static fallback"]
  node_staticpage["Static fallback<br/>[index.html]"]
  node_staticdata["Static race data<br/>[data.js]"]
end

node_bettor(("Bettor"))
node_pdf["Race-card PDF"]

node_bettor -->|"configures and requests"| node_streamlit
node_pdf -->|"uploads"| node_streamlit
node_streamlit -->|"extracts PDF"| node_parser
node_parser -->|"extracts runners"| node_racefields
node_streamlit -->|"configures races"| node_racefields
node_streamlit -->|"accepts odds"| node_odds
node_streamlit -->|"runs predictions"| node_prediction
node_prediction -->|"selects model"| node_trackmodels
node_prediction -->|"calibrates probabilities"| node_calibration
node_calibration -.->|"loads model"| node_modelartifact
node_prediction -->|"returns predictions"| node_rankings
node_rankings -->|"shows EV signals"| node_value
node_streamlit -->|"navigates races"| node_racebrowse
node_rankings -->|"shows combinations"| node_exotics
node_racebrowse -->|"shows meeting bets"| node_meetingbets
node_rankings -->|"summarizes EV"| node_matrix
node_rankings -->|"formats results"| node_texttables
node_bettor -.->|"uses fallback"| node_staticpage
node_staticpage -.->|"uses race data"| node_staticdata

click node_streamlit "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py"
click node_parser "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/extractor.py"
click node_racefields "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py"
click node_prediction "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/predictor.py"
click node_trackmodels "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/predictor.py"
click node_calibration "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/predictor.py"
click node_modelartifact "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/calibration_model_v42.pkl"
click node_odds "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py"
click node_rankings "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py"
click node_value "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py"
click node_racebrowse "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py"
click node_exotics "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py"
click node_meetingbets "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py"
click node_matrix "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py"
click node_texttables "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py"
click node_staticpage "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/index.html"
click node_staticdata "https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/data.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_streamlit,node_parser,node_racefields toneBlue
class node_prediction,node_trackmodels,node_calibration,node_modelartifact toneAmber
class node_odds,node_rankings,node_value,node_racebrowse,node_exotics,node_meetingbets,node_matrix,node_texttables toneMint
class node_staticpage,node_staticdata toneRose
class node_bettor,node_pdf toneIndigo
```

## Components

### Race-card ingestion

- [Streamlit app](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py): `app.py`
- [PDF parser](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/extractor.py): `extractor.py`
- [Race setup](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py): `app.py`

### Prediction engine

- [Prediction engine](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/predictor.py): `predictor.py`
- [Track models](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/predictor.py): `predictor.py`
- [ML calibration](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/predictor.py): `predictor.py`
- [Calibration model](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/calibration_model_v42.pkl): `calibration_model_v42.pkl`

### Betting interface

- [Odds editor](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py): `app.py`
- [Race rankings](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py): `app.py`
- [EV and value](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py): `app.py`
- [Race navigation](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py): `app.py`
- [Exotic bets](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py): `app.py`
- [Multi-race bets](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py): `app.py`
- [EV meeting matrix](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py): `app.py`
- [Copyable tables](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/app.py): `app.py`

### Static fallback

- [Static fallback](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/index.html): `index.html`
- [Static race data](https://github.com/nkosikhona-ai/sa-quant-racing-predictor/blob/main/data.js): `data.js`

### Other components

- **Bettor**
- **Race-card PDF**

## Connections

- Bettor → Streamlit app: configures and requests (evidence: `README.md`)
- Race-card PDF → Streamlit app: uploads (evidence: `README.md`)
- Streamlit app → PDF parser: extracts PDF (evidence: `app.py`)
- PDF parser → Race setup: extracts runners (evidence: `README.md`)
- Streamlit app → Race setup: configures races (evidence: `README.md`)
- Streamlit app → Odds editor: accepts odds (evidence: `README.md`)
- Streamlit app → Prediction engine: runs predictions (evidence: `app.py`)
- Prediction engine → Track models: selects model (evidence: `predictor.py`)
- Prediction engine → ML calibration: calibrates probabilities (evidence: `README.md`)
- ML calibration → Calibration model: loads model
- Prediction engine → Race rankings: returns predictions (evidence: `README.md`)
- Race rankings → EV and value: shows EV signals (evidence: `README.md`)
- Streamlit app → Race navigation: navigates races (evidence: `app.py`)
- Race rankings → Exotic bets: shows combinations (evidence: `README.md`)
- Race navigation → Multi-race bets: shows meeting bets (evidence: `README.md`)
- Race rankings → EV meeting matrix: summarizes EV (evidence: `app.py`)
- Race rankings → Copyable tables: formats results (evidence: `README.md`)
- Bettor → Static fallback: uses fallback (evidence: `README.md`)
- Static fallback → Static race data: uses race data
