# crescentschaos/football-prototype architecture

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

- Interactive diagram: https://gitdiagram.com/crescentschaos/football-prototype
- Repository: https://github.com/crescentschaos/football-prototype

## Overview

Apex Football Simulator is a browser-based football simulation product. Users select teams and tactics, run a match or competition, then inspect live events, reports, standings, statistics, and history. The match engine models possession through shots and goalkeeper outcomes; season and tournament systems extend play into domestic and international competitions. The README documents these capabilities and the match-stage sequence; sampled source excerpts are partial, so some internal links rely on README statements rather than inspected call sites.

Main entry points: [`engine/matchEngine.js`](https://github.com/crescentschaos/football-prototype/blob/main/engine/matchEngine.js) (Match engine), [`simulation/seasonEngine.js`](https://github.com/crescentschaos/football-prototype/blob/main/simulation/seasonEngine.js) (Season simulation), [`engine/possession.js`](https://github.com/crescentschaos/football-prototype/blob/main/engine/possession.js) (Possession and movement), [`simulation/tournamentEngine.js`](https://github.com/crescentschaos/football-prototype/blob/main/simulation/tournamentEngine.js) (Tournament simulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Browser application"]
  node_application["App startup<br/>[main.js]"]
  node_state["Application state<br/>[state.js]"]
  node_rng["Seeded randomness<br/>[rng.js]"]
end

subgraph group_match["Match simulation"]
  node_match_engine["Match engine<br/>[matchEngine.js]"]
  node_possession["Possession and movement<br/>[possession.js]"]
  node_decisions["Ball decisions<br/>[decisionModel.js]"]
  node_passing["Passing<br/>[passing.js]"]
  node_defending["Defending<br/>[defending.js]"]
  node_transitions["Transitions<br/>[transitions.js]"]
  node_shooting["Shooting<br/>[shooting.js]"]
  node_goalkeeper["Goalkeeping<br/>[goalkeeper.js]"]
  node_offside["Offside decisions<br/>[offside.js]"]
  node_setpieces["Set pieces<br/>[setpieces.js]"]
  node_fatigue_injuries["Fitness and injuries<br/>[injuries.js]"]
end

subgraph group_competition["Competitions and seasons"]
  node_season["Season simulation<br/>[seasonEngine.js]"]
  node_world["International calendar<br/>[worldEngine.js]"]
  node_tournaments["Tournament simulation"]
  node_league_tournament["League tournaments"]
  node_knockout["Knockout cups<br/>[knockoutEngine.js]"]
  node_transfers["Transfers<br/>[transferEngine.js]"]
end

subgraph group_football_data["Football data and AI"]
  node_teams[("Team database<br/>[teamDatabase.js]")]
  node_players[("Player database<br/>[playerDatabase.js]")]
  node_competitions_data["Competition definitions<br/>[competitions.js]"]
  node_manager_ai["Manager tactics<br/>[managerAI.js]"]
end

subgraph group_presentation["User interfaces"]
  node_match_ui["Match interface<br/>[matchUI.js]"]
  node_season_ui["Season interface<br/>[seasonUI.js]"]
  node_league_ui["League interface"]
  node_player_ui["Player interface<br/>[playerUI.js]"]
  node_players_ui["Players browser<br/>[playersUI.js]"]
  node_team_ui["Team interface<br/>[teamUI.js]"]
  node_statistics_ui["Statistics interface<br/>[statisticsUI.js]"]
  node_hospital_ui["Injury interface<br/>[hospitalUI.js]"]
end

node_user(("Player"))

node_user -->|"opens"| node_application
node_application -->|"initializes"| node_state
node_user -->|"selects teams"| node_match_ui
node_match_ui -->|"starts match"| node_match_engine
node_teams -->|"provides squads"| node_players
node_match_engine -->|"simulates possession"| node_possession
node_possession -->|"evaluates actions"| node_decisions
node_possession -->|"attempts passes"| node_passing
node_possession -->|"contests possession"| node_defending
node_match_engine -->|"handles transitions"| node_transitions
node_match_engine -->|"creates shots"| node_shooting
node_shooting -->|"resolves shots"| node_goalkeeper
node_match_engine -->|"checks offside"| node_offside
node_match_engine -->|"handles set pieces"| node_setpieces
node_match_engine -->|"tracks fitness"| node_fatigue_injuries
node_manager_ai -->|"influences tactics"| node_match_engine
node_rng -->|"seeds simulation"| node_match_engine
node_match_engine -->|"provides events"| node_match_ui
node_user -->|"runs seasons"| node_season_ui
node_season_ui -->|"advances calendar"| node_season
node_season -.->|"simulates fixtures"| node_match_engine
node_season -->|"schedules internationals"| node_world
node_user -->|"runs competitions"| node_league_ui
node_league_ui -->|"starts league format"| node_league_tournament
node_league_tournament -->|"reuses standings logic"| node_season
node_user -->|"starts tournament"| node_tournaments
node_tournaments -->|"seeds cup bracket"| node_knockout
node_tournaments -.->|"simulates fixtures"| node_match_engine
node_competitions_data -.->|"defines formats"| node_tournaments
node_user -->|"browses players"| node_players_ui
node_players_ui -.->|"browses records"| node_players
node_user -->|"views teams"| node_team_ui
node_user -->|"views players"| node_player_ui
node_season -->|"tracks records"| node_statistics_ui
node_fatigue_injuries -.->|"reports injuries"| node_hospital_ui
node_season -.->|"shows progress"| node_season_ui
node_transfers -.->|"updates squads"| node_teams

click node_application "https://github.com/crescentschaos/football-prototype/blob/main/js/main.js"
click node_state "https://github.com/crescentschaos/football-prototype/blob/main/js/state.js"
click node_rng "https://github.com/crescentschaos/football-prototype/blob/main/js/rng.js"
click node_teams "https://github.com/crescentschaos/football-prototype/blob/main/data/teamDatabase.js"
click node_players "https://github.com/crescentschaos/football-prototype/blob/main/data/playerDatabase.js"
click node_competitions_data "https://github.com/crescentschaos/football-prototype/blob/main/data/competitions.js"
click node_manager_ai "https://github.com/crescentschaos/football-prototype/blob/main/ai/managerAI.js"
click node_match_engine "https://github.com/crescentschaos/football-prototype/blob/main/engine/matchEngine.js"
click node_possession "https://github.com/crescentschaos/football-prototype/blob/main/engine/possession.js"
click node_decisions "https://github.com/crescentschaos/football-prototype/blob/main/engine/decisionModel.js"
click node_passing "https://github.com/crescentschaos/football-prototype/blob/main/engine/passing.js"
click node_defending "https://github.com/crescentschaos/football-prototype/blob/main/engine/defending.js"
click node_transitions "https://github.com/crescentschaos/football-prototype/blob/main/engine/transitions.js"
click node_shooting "https://github.com/crescentschaos/football-prototype/blob/main/engine/shooting.js"
click node_goalkeeper "https://github.com/crescentschaos/football-prototype/blob/main/engine/goalkeeper.js"
click node_offside "https://github.com/crescentschaos/football-prototype/blob/main/engine/offside.js"
click node_setpieces "https://github.com/crescentschaos/football-prototype/blob/main/engine/setpieces.js"
click node_fatigue_injuries "https://github.com/crescentschaos/football-prototype/blob/main/engine/injuries.js"
click node_season "https://github.com/crescentschaos/football-prototype/blob/main/simulation/seasonEngine.js"
click node_world "https://github.com/crescentschaos/football-prototype/blob/main/simulation/worldEngine.js"
click node_tournaments "https://github.com/crescentschaos/football-prototype/blob/main/simulation/tournamentEngine.js"
click node_league_tournament "https://github.com/crescentschaos/football-prototype/blob/main/simulation/leagueTournamentEngine.js"
click node_knockout "https://github.com/crescentschaos/football-prototype/blob/main/simulation/knockoutEngine.js"
click node_transfers "https://github.com/crescentschaos/football-prototype/blob/main/simulation/transferEngine.js"
click node_match_ui "https://github.com/crescentschaos/football-prototype/blob/main/ui/matchUI.js"
click node_season_ui "https://github.com/crescentschaos/football-prototype/blob/main/ui/seasonUI.js"
click node_league_ui "https://github.com/crescentschaos/football-prototype/blob/main/ui/leagueTournamentUI.js"
click node_player_ui "https://github.com/crescentschaos/football-prototype/blob/main/ui/playerUI.js"
click node_players_ui "https://github.com/crescentschaos/football-prototype/blob/main/ui/playersUI.js"
click node_team_ui "https://github.com/crescentschaos/football-prototype/blob/main/ui/teamUI.js"
click node_statistics_ui "https://github.com/crescentschaos/football-prototype/blob/main/ui/statisticsUI.js"
click node_hospital_ui "https://github.com/crescentschaos/football-prototype/blob/main/ui/hospitalUI.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_application,node_state,node_rng toneBlue
class node_match_engine,node_possession,node_decisions,node_passing,node_defending,node_transitions,node_shooting,node_goalkeeper,node_offside,node_setpieces,node_fatigue_injuries toneAmber
class node_season,node_world,node_tournaments,node_league_tournament,node_knockout,node_transfers toneMint
class node_teams,node_players,node_competitions_data,node_manager_ai toneRose
class node_match_ui,node_season_ui,node_league_ui,node_player_ui,node_players_ui,node_team_ui,node_statistics_ui,node_hospital_ui,node_user toneIndigo
```

## Components

### Browser application

- [App startup](https://github.com/crescentschaos/football-prototype/blob/main/js/main.js): `js/main.js`
- [Application state](https://github.com/crescentschaos/football-prototype/blob/main/js/state.js): `js/state.js`
- [Seeded randomness](https://github.com/crescentschaos/football-prototype/blob/main/js/rng.js): `js/rng.js`

### Match simulation

- [Match engine](https://github.com/crescentschaos/football-prototype/blob/main/engine/matchEngine.js): `engine/matchEngine.js`
- [Possession and movement](https://github.com/crescentschaos/football-prototype/blob/main/engine/possession.js): `engine/possession.js`
- [Ball decisions](https://github.com/crescentschaos/football-prototype/blob/main/engine/decisionModel.js): `engine/decisionModel.js`
- [Passing](https://github.com/crescentschaos/football-prototype/blob/main/engine/passing.js): `engine/passing.js`
- [Defending](https://github.com/crescentschaos/football-prototype/blob/main/engine/defending.js): `engine/defending.js`
- [Transitions](https://github.com/crescentschaos/football-prototype/blob/main/engine/transitions.js): `engine/transitions.js`
- [Shooting](https://github.com/crescentschaos/football-prototype/blob/main/engine/shooting.js): `engine/shooting.js`
- [Goalkeeping](https://github.com/crescentschaos/football-prototype/blob/main/engine/goalkeeper.js): `engine/goalkeeper.js`
- [Offside decisions](https://github.com/crescentschaos/football-prototype/blob/main/engine/offside.js): `engine/offside.js`
- [Set pieces](https://github.com/crescentschaos/football-prototype/blob/main/engine/setpieces.js): `engine/setpieces.js`
- [Fitness and injuries](https://github.com/crescentschaos/football-prototype/blob/main/engine/injuries.js): `engine/injuries.js`

### Competitions and seasons

- [Season simulation](https://github.com/crescentschaos/football-prototype/blob/main/simulation/seasonEngine.js): `simulation/seasonEngine.js`
- [International calendar](https://github.com/crescentschaos/football-prototype/blob/main/simulation/worldEngine.js): `simulation/worldEngine.js`
- [Tournament simulation](https://github.com/crescentschaos/football-prototype/blob/main/simulation/tournamentEngine.js): `simulation/tournamentEngine.js`
- [League tournaments](https://github.com/crescentschaos/football-prototype/blob/main/simulation/leagueTournamentEngine.js): `simulation/leagueTournamentEngine.js`
- [Knockout cups](https://github.com/crescentschaos/football-prototype/blob/main/simulation/knockoutEngine.js): `simulation/knockoutEngine.js`
- [Transfers](https://github.com/crescentschaos/football-prototype/blob/main/simulation/transferEngine.js): `simulation/transferEngine.js`

### Football data and AI

- [Team database](https://github.com/crescentschaos/football-prototype/blob/main/data/teamDatabase.js): `data/teamDatabase.js`
- [Player database](https://github.com/crescentschaos/football-prototype/blob/main/data/playerDatabase.js): `data/playerDatabase.js`
- [Competition definitions](https://github.com/crescentschaos/football-prototype/blob/main/data/competitions.js): `data/competitions.js`
- [Manager tactics](https://github.com/crescentschaos/football-prototype/blob/main/ai/managerAI.js): `ai/managerAI.js`

### User interfaces

- [Match interface](https://github.com/crescentschaos/football-prototype/blob/main/ui/matchUI.js): `ui/matchUI.js`
- [Season interface](https://github.com/crescentschaos/football-prototype/blob/main/ui/seasonUI.js): `ui/seasonUI.js`
- [League interface](https://github.com/crescentschaos/football-prototype/blob/main/ui/leagueTournamentUI.js): `ui/leagueTournamentUI.js`
- [Player interface](https://github.com/crescentschaos/football-prototype/blob/main/ui/playerUI.js): `ui/playerUI.js`
- [Players browser](https://github.com/crescentschaos/football-prototype/blob/main/ui/playersUI.js): `ui/playersUI.js`
- [Team interface](https://github.com/crescentschaos/football-prototype/blob/main/ui/teamUI.js): `ui/teamUI.js`
- [Statistics interface](https://github.com/crescentschaos/football-prototype/blob/main/ui/statisticsUI.js): `ui/statisticsUI.js`
- [Injury interface](https://github.com/crescentschaos/football-prototype/blob/main/ui/hospitalUI.js): `ui/hospitalUI.js`

### Other components

- **Player**

## Connections

- Player → App startup: opens
- App startup → Application state: initializes (evidence: `js/main.js`)
- Player → Match interface: selects teams
- Match interface → Match engine: starts match
- Team database → Player database: provides squads (evidence: `data/playerDatabase.js`)
- Match engine → Possession and movement: simulates possession
- Possession and movement → Ball decisions: evaluates actions (evidence: `engine/possession.js`)
- Possession and movement → Passing: attempts passes
- Possession and movement → Defending: contests possession
- Match engine → Transitions: handles transitions
- Match engine → Shooting: creates shots
- Shooting → Goalkeeping: resolves shots
- Match engine → Offside decisions: checks offside
- Match engine → Set pieces: handles set pieces
- Match engine → Fitness and injuries: tracks fitness
- Manager tactics → Match engine: influences tactics
- Seeded randomness → Match engine: seeds simulation
- Match engine → Match interface: provides events
- Player → Season interface: runs seasons
- Season interface → Season simulation: advances calendar
- Season simulation → Match engine: simulates fixtures
- Season simulation → International calendar: schedules internationals (evidence: `simulation/worldEngine.js`)
- Player → League interface: runs competitions
- League interface → League tournaments: starts league format (evidence: `simulation/leagueTournamentEngine.js`)
- League tournaments → Season simulation: reuses standings logic (evidence: `simulation/leagueTournamentEngine.js`)
- Player → Tournament simulation: starts tournament
- Tournament simulation → Knockout cups: seeds cup bracket (evidence: `simulation/knockoutEngine.js`)
- Tournament simulation → Match engine: simulates fixtures
- Competition definitions → Tournament simulation: defines formats
- Player → Players browser: browses players
- Players browser → Player database: browses records
- Player → Team interface: views teams
- Player → Player interface: views players
- Season simulation → Statistics interface: tracks records
- Fitness and injuries → Injury interface: reports injuries
- Season simulation → Season interface: shows progress
- Transfers → Team database: updates squads
