# nandunsamarasekara/football101_managing_simulation architecture

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

- Interactive diagram: https://gitdiagram.com/nandunsamarasekara/football101_managing_simulation
- Repository: https://github.com/nandunsamarasekara/football101_managing_simulation

## Overview

Football Manager is a two-player, hot-seat, turn-based football game. Managers choose formations and tactics, submit up to three player orders each turn, and the match controller resolves play and set pieces before producing match results. The documented runtime is a pure Python simulation engine; the Pygame front end is not yet implemented. The graph reflects the README and shown source references; some module relationships are based on the source index, and the formation-file link is unverified.

Main entry points: [`engine/simulation.py`](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/simulation.py) (Tick Simulation), [`engine/match.py`](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/match.py) (Match Controller), [`engine/formations.py`](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/formations.py) (Formation Loader), [`engine/models.py`](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/models.py) (Match Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_match["Match Coordination"]
  node_match_controller["Match Controller<br/>[match.py]"]
  node_orders["Turn Orders<br/>[orders.py]"]
  node_match_log["Match Log<br/>[match.py]"]
  node_bot_script["Bot Match Script<br/>[play_bot_match.py]"]
end

subgraph group_play["Match Simulation"]
  node_simulation["Tick Simulation<br/>[simulation.py]"]
  node_movement["Player Movement<br/>[movement.py]"]
  node_actions["Ball Actions<br/>[actions.py]"]
  node_setpieces["Set Pieces<br/>[setpieces.py]"]
end

subgraph group_domain["Football Rules"]
  node_state_machine["Phase State<br/>[state_machine.py]"]
  node_events["Fouls and Cards<br/>[events.py]"]
  node_formations["Formation Loader<br/>[formations.py]"]
  node_formation_data["4-3-3 Formation<br/>[4-3-3.json]"]
end

subgraph group_foundation["Engine Foundation"]
  node_models["Match Models<br/>[models.py]"]
  node_physics["Geometry Helpers<br/>[physics.py]"]
  node_config["Game Configuration<br/>[config.py]"]
end

node_manager(("Team Managers"))

node_manager -->|"submits choices"| node_match_controller
node_match_controller -->|"collects orders"| node_orders
node_match_controller -->|"loads formations"| node_formations
node_match_controller -->|"runs turn"| node_simulation
node_match_controller -->|"resolves restart"| node_setpieces
node_match_controller -->|"updates phase"| node_state_machine
node_match_controller -->|"records results"| node_match_log
node_match_controller -->|"prompts choices"| node_manager
node_bot_script -->|"runs match"| node_match_controller
node_simulation -->|"reads orders"| node_orders
node_simulation -->|"loads roles"| node_formations
node_simulation -->|"computes movement"| node_movement
node_simulation -->|"resolves actions"| node_actions
node_simulation -->|"checks fouls"| node_events
node_simulation -->|"transitions phases"| node_state_machine
node_setpieces -->|"uses ball actions"| node_actions
node_setpieces -->|"uses phase rules"| node_state_machine
node_movement -->|"uses role data"| node_formations
node_movement -->|"uses geometry"| node_physics
node_actions -->|"uses geometry"| node_physics
node_formations -.->|"loads formation"| node_formation_data
node_simulation -->|"updates match state"| node_models
node_actions -->|"uses ball models"| node_models
node_events -->|"updates discipline"| node_models
node_formations -->|"places players"| node_models
node_state_machine -->|"transitions match"| node_models
node_orders -->|"uses positions"| node_models
node_simulation -->|"reads game rules"| node_config
node_actions -->|"reads action tuning"| node_config
node_events -->|"reads foul tuning"| node_config
node_movement -->|"reads movement tuning"| node_config
node_formations -->|"reads pitch dimensions"| node_config

click node_match_controller "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/match.py"
click node_orders "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/orders.py"
click node_match_log "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/match.py"
click node_simulation "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/simulation.py"
click node_movement "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/movement.py"
click node_actions "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/actions.py"
click node_setpieces "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/setpieces.py"
click node_state_machine "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/state_machine.py"
click node_events "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/events.py"
click node_formations "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/formations.py"
click node_formation_data "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/data/formations/4-3-3.json"
click node_models "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/models.py"
click node_physics "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/physics.py"
click node_config "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/config.py"
click node_bot_script "https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/scripts/play_bot_match.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_match_controller,node_orders,node_match_log,node_bot_script toneBlue
class node_simulation,node_movement,node_actions,node_setpieces toneAmber
class node_state_machine,node_events,node_formations,node_formation_data toneMint
class node_models,node_physics,node_config toneRose
class node_manager toneIndigo
```

## Components

### Match Coordination

- [Match Controller](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/match.py): `engine/match.py`
- [Turn Orders](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/orders.py): `engine/orders.py`
- [Match Log](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/match.py): `engine/match.py`
- [Bot Match Script](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/scripts/play_bot_match.py): `scripts/play_bot_match.py`

### Match Simulation

- [Tick Simulation](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/simulation.py): `engine/simulation.py`
- [Player Movement](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/movement.py): `engine/movement.py`
- [Ball Actions](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/actions.py): `engine/actions.py`
- [Set Pieces](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/setpieces.py): `engine/setpieces.py`

### Football Rules

- [Phase State](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/state_machine.py): `engine/state_machine.py`
- [Fouls and Cards](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/events.py): `engine/events.py`
- [Formation Loader](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/formations.py): `engine/formations.py`
- [4-3-3 Formation](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/data/formations/4-3-3.json): `data/formations/4-3-3.json`

### Engine Foundation

- [Match Models](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/models.py): `engine/models.py`
- [Geometry Helpers](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/physics.py): `engine/physics.py`
- [Game Configuration](https://github.com/nandunsamarasekara/football101_managing_simulation/blob/main/engine/config.py): `engine/config.py`

### Other components

- **Team Managers**

## Connections

- Team Managers → Match Controller: submits choices (evidence: `README.md`)
- Match Controller → Turn Orders: collects orders (evidence: `engine/match.py`)
- Match Controller → Formation Loader: loads formations (evidence: `engine/match.py`)
- Match Controller → Tick Simulation: runs turn (evidence: `engine/match.py`)
- Match Controller → Set Pieces: resolves restart (evidence: `engine/match.py`)
- Match Controller → Phase State: updates phase (evidence: `engine/match.py`)
- Match Controller → Match Log: records results (evidence: `engine/match.py`)
- Match Controller → Team Managers: prompts choices (evidence: `engine/match.py`)
- Bot Match Script → Match Controller: runs match (evidence: `scripts/play_bot_match.py`)
- Tick Simulation → Turn Orders: reads orders (evidence: `engine/simulation.py`)
- Tick Simulation → Formation Loader: loads roles (evidence: `engine/simulation.py`)
- Tick Simulation → Player Movement: computes movement (evidence: `engine/simulation.py`)
- Tick Simulation → Ball Actions: resolves actions (evidence: `engine/simulation.py`)
- Tick Simulation → Fouls and Cards: checks fouls (evidence: `engine/simulation.py`)
- Tick Simulation → Phase State: transitions phases (evidence: `engine/simulation.py`)
- Set Pieces → Ball Actions: uses ball actions (evidence: `engine/setpieces.py`)
- Set Pieces → Phase State: uses phase rules (evidence: `engine/setpieces.py`)
- Player Movement → Formation Loader: uses role data (evidence: `engine/movement.py`)
- Player Movement → Geometry Helpers: uses geometry (evidence: `engine/movement.py`)
- Ball Actions → Geometry Helpers: uses geometry (evidence: `engine/actions.py`)
- Formation Loader → 4-3-3 Formation: loads formation
- Tick Simulation → Match Models: updates match state (evidence: `engine/simulation.py`)
- Ball Actions → Match Models: uses ball models (evidence: `engine/actions.py`)
- Fouls and Cards → Match Models: updates discipline (evidence: `engine/events.py`)
- Formation Loader → Match Models: places players (evidence: `engine/formations.py`)
- Phase State → Match Models: transitions match (evidence: `engine/state_machine.py`)
- Turn Orders → Match Models: uses positions (evidence: `engine/orders.py`)
- Tick Simulation → Game Configuration: reads game rules (evidence: `engine/simulation.py`)
- Ball Actions → Game Configuration: reads action tuning (evidence: `engine/actions.py`)
- Fouls and Cards → Game Configuration: reads foul tuning (evidence: `engine/events.py`)
- Player Movement → Game Configuration: reads movement tuning (evidence: `engine/movement.py`)
- Formation Loader → Game Configuration: reads pitch dimensions (evidence: `engine/formations.py`)