# jamesmcaleer/horseracing architecture

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

- Interactive diagram: https://gitdiagram.com/jamesmcaleer/horseracing
- Repository: https://github.com/jamesmcaleer/horseracing

## Overview

Horse Racing is a Pygame horse-racing simulator. The player generates a field, starts and watches a race, then sees the top-three podium; the documented controls also allow replay and return to the menu. Its domain stages are odds and speed assignment, horse assembly, race presentation, ranking, and finish results. The excerpts show the main runtime classes but omit some wiring and rendering details, so uncertain connections are left out; the README supports the asset and podium capabilities.

Main entry points: [`main.py`](https://github.com/jamesmcaleer/horseracing/blob/main/main.py) (Graphics handler), [`assets`](https://github.com/jamesmcaleer/horseracing/tree/main/assets) (Horse assets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_race_logic["Race generation"]
  node_chance["Chance handler<br/>[main.py]"]
  node_actions["Action handler<br/>[main.py]"]
  node_horse["Horse<br/>[main.py]"]
  node_assets["Horse assets"]
end

subgraph group_race_view["Race presentation"]
  node_graphics["Graphics handler<br/>[main.py]"]
  node_finish["Finish line<br/>[main.py]"]
end

subgraph group_race_results["Race results"]
  node_leaderboard["Leaderboard<br/>[main.py]"]
  node_podium["Podium<br/>[main.py]"]
end

node_player(("Player"))
node_pygame["Pygame"]

node_player -->|"controls"| node_graphics
node_graphics -->|"polls events"| node_pygame
node_actions -->|"generates odds"| node_chance
node_actions -->|"generates speeds"| node_chance
node_actions -->|"creates horses"| node_horse
node_actions -->|"fetches assets"| node_assets
node_graphics -->|"updates field"| node_actions
node_graphics -->|"moves and draws"| node_finish
node_graphics -->|"draws ranking"| node_leaderboard
node_leaderboard -->|"reads horses"| node_actions
node_podium -->|"reads ranked horses"| node_actions
node_graphics -->|"draws podium"| node_podium
node_graphics -->|"renders display"| node_pygame

click node_chance "https://github.com/jamesmcaleer/horseracing/blob/main/main.py"
click node_actions "https://github.com/jamesmcaleer/horseracing/blob/main/main.py"
click node_horse "https://github.com/jamesmcaleer/horseracing/blob/main/main.py"
click node_assets "https://github.com/jamesmcaleer/horseracing/tree/main/assets"
click node_graphics "https://github.com/jamesmcaleer/horseracing/blob/main/main.py"
click node_finish "https://github.com/jamesmcaleer/horseracing/blob/main/main.py"
click node_leaderboard "https://github.com/jamesmcaleer/horseracing/blob/main/main.py"
click node_podium "https://github.com/jamesmcaleer/horseracing/blob/main/main.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_chance,node_actions,node_horse,node_assets toneBlue
class node_graphics,node_finish toneAmber
class node_leaderboard,node_podium toneMint
class node_player,node_pygame toneIndigo
```

## Components

### Race generation

- [Chance handler](https://github.com/jamesmcaleer/horseracing/blob/main/main.py): `main.py`
- [Action handler](https://github.com/jamesmcaleer/horseracing/blob/main/main.py): `main.py`
- [Horse](https://github.com/jamesmcaleer/horseracing/blob/main/main.py): `main.py`
- [Horse assets](https://github.com/jamesmcaleer/horseracing/tree/main/assets): `assets`

### Race presentation

- [Graphics handler](https://github.com/jamesmcaleer/horseracing/blob/main/main.py): `main.py`
- [Finish line](https://github.com/jamesmcaleer/horseracing/blob/main/main.py): `main.py`

### Race results

- [Leaderboard](https://github.com/jamesmcaleer/horseracing/blob/main/main.py): `main.py`
- [Podium](https://github.com/jamesmcaleer/horseracing/blob/main/main.py): `main.py`

### Other components

- **Player**
- **Pygame**

## Connections

- Player → Graphics handler: controls
- Graphics handler → Pygame: polls events
- Action handler → Chance handler: generates odds
- Action handler → Chance handler: generates speeds
- Action handler → Horse: creates horses
- Action handler → Horse assets: fetches assets
- Graphics handler → Action handler: updates field
- Graphics handler → Finish line: moves and draws
- Graphics handler → Leaderboard: draws ranking
- Leaderboard → Action handler: reads horses
- Podium → Action handler: reads ranked horses
- Graphics handler → Podium: draws podium
- Graphics handler → Pygame: renders display