# songalobung/footsim architecture

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

- Interactive diagram: https://gitdiagram.com/songalobung/footsim
- Repository: https://github.com/songalobung/footsim

## Overview

FootSim is a football match simulation and prediction suite. Its main workflow loads and normalizes historical match data, fits goal and event models, simulates matches minute by minute, then answers market queries from the shared simulations. Separate product branches cover squad and live-match adjustments, pre-match inspection, and walk-forward, calibration, statistical-significance, and betting analysis. The README documents the broader capabilities; sampled source and the SOURCE INDEX support the implementation links shown. Unsampled modules are represented at directory level where appropriate.

Main entry points: [`footsim/cli.py`](https://github.com/songalobung/footsim/blob/main/footsim/cli.py) (FootSim CLI), [`footsim/eval/backtest.py`](https://github.com/songalobung/footsim/blob/main/footsim/eval/backtest.py) (Walk-Forward Backtest), [`footsim/sim/match.py`](https://github.com/songalobung/footsim/blob/main/footsim/sim/match.py) (Match Simulator), [`footsim/goals/dixon_coles.py`](https://github.com/songalobung/footsim/blob/main/footsim/goals/dixon_coles.py) (Dixon-Coles Model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Match Data"]
  node_loader["Load &amp; Normalize<br/>[loader.py]"]
  node_history[("Historical Matches<br/>[loader.py]")]
  node_ewma["EWMA Ratings<br/>[ewma.py]"]
end

subgraph group_models["Prediction Models"]
  node_goal_model["Dixon-Coles Model<br/>[dixon_coles.py]"]
  node_copula["Goal Dependence<br/>[copula.py]"]
  node_event_model["Event Rates<br/>[rates.py]"]
end

subgraph group_simulation["Simulation"]
  node_simulator["Match Simulator<br/>[match.py]"]
  node_sim_config["Simulation Config<br/>[config.py]"]
  node_squad["Squad &amp; Absences<br/>[squad.py]"]
  node_players["Player Events<br/>[players.py]"]
  node_live["Live Simulation<br/>[inplay.py]"]
  node_markets["Market Queries<br/>[query.py]"]
end

subgraph group_analysis["Inspection &amp; Evaluation"]
  node_inspection["Match Inspection<br/>[inspection.py]"]
  node_backtest["Walk-Forward Backtest<br/>[backtest.py]"]
  node_betting["Betting &amp; Edge<br/>[betting.py]"]
  node_calibration["Calibration<br/>[calibration.py]"]
  node_significance["Significance Tests<br/>[significance.py]"]
  node_metrics["Evaluation Metrics<br/>[metrics.py]"]
  node_odds["Odds &amp; Devigging<br/>[odds.py]"]
  node_events_eval["Event Evaluation<br/>[events.py]"]
end

node_user(("CLI User"))
node_cli["FootSim CLI<br/>[cli.py]"]
node_source_data(("Match Data Source"))
node_pinnacle(("Pinnacle Closing Odds"))

node_user -->|"runs commands"| node_cli
node_cli -->|"loads matches"| node_loader
node_source_data -->|"provides season CSVs"| node_loader
node_loader -->|"normalizes and caches"| node_history
node_cli -->|"fits model"| node_goal_model
node_cli -->|"fits rates"| node_event_model
node_goal_model -->|"uses ratings"| node_ewma
node_cli -.->|"configures ratings"| node_ewma
node_goal_model -->|"fits from matches"| node_history
node_event_model -->|"fits from matches"| node_history
node_cli -->|"runs prediction"| node_simulator
node_goal_model -->|"supplies goal model"| node_simulator
node_event_model -->|"supplies event rates"| node_simulator
node_sim_config -->|"configures run"| node_simulator
node_squad -->|"adjusts teams"| node_simulator
node_players -->|"attributes events"| node_simulator
node_simulator -.->|"supports live mode"| node_live
node_simulator -->|"produces query inputs"| node_markets
node_cli -->|"queries markets"| node_markets
node_cli -->|"runs inspection"| node_inspection
node_inspection -->|"audits match form"| node_history
node_cli -->|"runs backtest"| node_backtest
node_backtest -->|"evaluates match history"| node_history
node_backtest -->|"refits per block"| node_goal_model
node_backtest -->|"removes odds margin"| node_odds
node_pinnacle -->|"benchmarks predictions"| node_backtest
node_cli -->|"runs betting analysis"| node_betting
node_backtest -.->|"evaluates wagers"| node_betting
node_backtest -->|"produces calibration"| node_calibration
node_backtest -->|"scores forecasts"| node_metrics
node_backtest -->|"tests benchmarks"| node_significance
node_cli -->|"evaluates events"| node_events_eval
node_events_eval -->|"scores event rates"| node_event_model
node_significance -->|"uses metrics"| node_metrics
node_goal_model -->|"uses dependence model"| node_copula

click node_cli "https://github.com/songalobung/footsim/blob/main/footsim/cli.py"
click node_loader "https://github.com/songalobung/footsim/blob/main/footsim/data/loader.py"
click node_history "https://github.com/songalobung/footsim/blob/main/footsim/data/loader.py"
click node_ewma "https://github.com/songalobung/footsim/blob/main/footsim/data/ewma.py"
click node_goal_model "https://github.com/songalobung/footsim/blob/main/footsim/goals/dixon_coles.py"
click node_copula "https://github.com/songalobung/footsim/blob/main/footsim/goals/copula.py"
click node_event_model "https://github.com/songalobung/footsim/blob/main/footsim/events/rates.py"
click node_simulator "https://github.com/songalobung/footsim/blob/main/footsim/sim/match.py"
click node_sim_config "https://github.com/songalobung/footsim/blob/main/footsim/sim/config.py"
click node_squad "https://github.com/songalobung/footsim/blob/main/footsim/sim/squad.py"
click node_players "https://github.com/songalobung/footsim/blob/main/footsim/sim/players.py"
click node_live "https://github.com/songalobung/footsim/blob/main/footsim/sim/inplay.py"
click node_markets "https://github.com/songalobung/footsim/blob/main/footsim/markets/query.py"
click node_inspection "https://github.com/songalobung/footsim/blob/main/footsim/eval/inspection.py"
click node_backtest "https://github.com/songalobung/footsim/blob/main/footsim/eval/backtest.py"
click node_betting "https://github.com/songalobung/footsim/blob/main/footsim/eval/betting.py"
click node_calibration "https://github.com/songalobung/footsim/blob/main/footsim/eval/calibration.py"
click node_significance "https://github.com/songalobung/footsim/blob/main/footsim/eval/significance.py"
click node_metrics "https://github.com/songalobung/footsim/blob/main/footsim/eval/metrics.py"
click node_odds "https://github.com/songalobung/footsim/blob/main/footsim/eval/odds.py"
click node_events_eval "https://github.com/songalobung/footsim/blob/main/footsim/eval/events.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_loader,node_history,node_ewma,node_user toneBlue
class node_goal_model,node_copula,node_event_model toneAmber
class node_simulator,node_sim_config,node_squad,node_players,node_live,node_markets toneMint
class node_inspection,node_backtest,node_betting,node_calibration,node_significance,node_metrics,node_odds,node_events_eval toneRose
class node_cli toneTeal
class node_source_data,node_pinnacle toneIndigo
```

## Components

### Match Data

- [Load & Normalize](https://github.com/songalobung/footsim/blob/main/footsim/data/loader.py): `footsim/data/loader.py`
- [Historical Matches](https://github.com/songalobung/footsim/blob/main/footsim/data/loader.py): `footsim/data/loader.py`
- [EWMA Ratings](https://github.com/songalobung/footsim/blob/main/footsim/data/ewma.py): `footsim/data/ewma.py`

### Prediction Models

- [Dixon-Coles Model](https://github.com/songalobung/footsim/blob/main/footsim/goals/dixon_coles.py): `footsim/goals/dixon_coles.py`
- [Goal Dependence](https://github.com/songalobung/footsim/blob/main/footsim/goals/copula.py): `footsim/goals/copula.py`
- [Event Rates](https://github.com/songalobung/footsim/blob/main/footsim/events/rates.py): `footsim/events/rates.py`

### Simulation

- [Match Simulator](https://github.com/songalobung/footsim/blob/main/footsim/sim/match.py): `footsim/sim/match.py`
- [Simulation Config](https://github.com/songalobung/footsim/blob/main/footsim/sim/config.py): `footsim/sim/config.py`
- [Squad & Absences](https://github.com/songalobung/footsim/blob/main/footsim/sim/squad.py): `footsim/sim/squad.py`
- [Player Events](https://github.com/songalobung/footsim/blob/main/footsim/sim/players.py): `footsim/sim/players.py`
- [Live Simulation](https://github.com/songalobung/footsim/blob/main/footsim/sim/inplay.py): `footsim/sim/inplay.py`
- [Market Queries](https://github.com/songalobung/footsim/blob/main/footsim/markets/query.py): `footsim/markets/query.py`

### Inspection & Evaluation

- [Match Inspection](https://github.com/songalobung/footsim/blob/main/footsim/eval/inspection.py): `footsim/eval/inspection.py`
- [Walk-Forward Backtest](https://github.com/songalobung/footsim/blob/main/footsim/eval/backtest.py): `footsim/eval/backtest.py`
- [Betting & Edge](https://github.com/songalobung/footsim/blob/main/footsim/eval/betting.py): `footsim/eval/betting.py`
- [Calibration](https://github.com/songalobung/footsim/blob/main/footsim/eval/calibration.py): `footsim/eval/calibration.py`
- [Significance Tests](https://github.com/songalobung/footsim/blob/main/footsim/eval/significance.py): `footsim/eval/significance.py`
- [Evaluation Metrics](https://github.com/songalobung/footsim/blob/main/footsim/eval/metrics.py): `footsim/eval/metrics.py`
- [Odds & Devigging](https://github.com/songalobung/footsim/blob/main/footsim/eval/odds.py): `footsim/eval/odds.py`
- [Event Evaluation](https://github.com/songalobung/footsim/blob/main/footsim/eval/events.py): `footsim/eval/events.py`

### Other components

- **CLI User**
- [FootSim CLI](https://github.com/songalobung/footsim/blob/main/footsim/cli.py): `footsim/cli.py`
- **Match Data Source**
- **Pinnacle Closing Odds**

## Connections

- CLI User → FootSim CLI: runs commands (evidence: `README.md`)
- FootSim CLI → Load & Normalize: loads matches (evidence: `footsim/cli.py`)
- Match Data Source → Load & Normalize: provides season CSVs (evidence: `footsim/data/loader.py`)
- Load & Normalize → Historical Matches: normalizes and caches (evidence: `footsim/data/loader.py`)
- FootSim CLI → Dixon-Coles Model: fits model (evidence: `footsim/cli.py`)
- FootSim CLI → Event Rates: fits rates (evidence: `footsim/cli.py`)
- Dixon-Coles Model → EWMA Ratings: uses ratings (evidence: `footsim/goals/dixon_coles.py`)
- FootSim CLI → EWMA Ratings: configures ratings
- Dixon-Coles Model → Historical Matches: fits from matches (evidence: `README.md`)
- Event Rates → Historical Matches: fits from matches (evidence: `README.md`)
- FootSim CLI → Match Simulator: runs prediction (evidence: `footsim/cli.py`)
- Dixon-Coles Model → Match Simulator: supplies goal model (evidence: `README.md`)
- Event Rates → Match Simulator: supplies event rates (evidence: `README.md`)
- Simulation Config → Match Simulator: configures run (evidence: `footsim/sim/match.py`)
- Squad & Absences → Match Simulator: adjusts teams (evidence: `footsim/sim/match.py`)
- Player Events → Match Simulator: attributes events (evidence: `footsim/sim/match.py`)
- Match Simulator → Live Simulation: supports live mode
- Match Simulator → Market Queries: produces query inputs (evidence: `README.md`)
- FootSim CLI → Market Queries: queries markets (evidence: `footsim/cli.py`)
- FootSim CLI → Match Inspection: runs inspection (evidence: `footsim/cli.py`)
- Match Inspection → Historical Matches: audits match form (evidence: `footsim/eval/inspection.py`)
- FootSim CLI → Walk-Forward Backtest: runs backtest (evidence: `footsim/cli.py`)
- Walk-Forward Backtest → Historical Matches: evaluates match history (evidence: `footsim/eval/backtest.py`)
- Walk-Forward Backtest → Dixon-Coles Model: refits per block (evidence: `footsim/eval/backtest.py`)
- Walk-Forward Backtest → Odds & Devigging: removes odds margin (evidence: `footsim/eval/backtest.py`)
- Pinnacle Closing Odds → Walk-Forward Backtest: benchmarks predictions (evidence: `README.md`)
- FootSim CLI → Betting & Edge: runs betting analysis (evidence: `footsim/cli.py`)
- Walk-Forward Backtest → Betting & Edge: evaluates wagers (evidence: `footsim/eval/backtest.py`)
- Walk-Forward Backtest → Calibration: produces calibration (evidence: `footsim/eval/backtest.py`)
- Walk-Forward Backtest → Evaluation Metrics: scores forecasts (evidence: `footsim/eval/backtest.py`)
- Walk-Forward Backtest → Significance Tests: tests benchmarks (evidence: `footsim/eval/backtest.py`)
- FootSim CLI → Event Evaluation: evaluates events (evidence: `footsim/cli.py`)
- Event Evaluation → Event Rates: scores event rates (evidence: `footsim/eval/events.py`)
- Significance Tests → Evaluation Metrics: uses metrics (evidence: `footsim/eval/significance.py`)
- Dixon-Coles Model → Goal Dependence: uses dependence model (evidence: `footsim/goals/dixon_coles.py`)
