# ingsoft1-theglory/futbot-back architecture

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

- Interactive diagram: https://gitdiagram.com/ingsoft1-theglory/futbot-back
- Repository: https://github.com/ingsoft1-theglory/futbot-back

## Overview

FutBot is a FastAPI backend for managing football teams, leagues, and matches, including live simulation and WebSocket updates. A user reaches the system through REST endpoints or live connections; league and friendly-match operations prepare and run matches, persist results, and publish events. The simulation separates match state, player behavior, pitch rules, physics, and penalties. The README documents PostgreSQL/SQLAlchemy persistence and live events; sampled source and the SOURCE INDEX support the specific links shown. Some route, service, and engine internals were not sampled, so uncertain relationships are omitted.

Main entry points: [`src/engine/match_runner.py`](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/engine/match_runner.py) (Match tick loop), [`src/services/match_start_service.py`](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/services/match_start_service.py) (Match preparation), [`src/main.py`](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/main.py) (FastAPI app), [`src/services/league_run_service.py`](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/services/league_run_service.py) (League scheduling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_security["Tokens and security<br/>[security.py]"]
  node_league_routes["League routes<br/>[leagues.py]"]
  node_friendly_routes["Friendly routes<br/>[friendly.py]"]
  node_other_routes["Match and player routes"]
end

subgraph group_competition["Competition workflows"]
  node_league_service["League management<br/>[league_service.py]"]
  node_league_runner["League scheduling"]
  node_friendly_service["Friendly management"]
  node_lineup["Lineup configuration<br/>[lineup_service.py]"]
  node_match_start["Match preparation"]
end

subgraph group_simulation["Match simulation"]
  node_match_runner["Match tick loop<br/>[match_runner.py]"]
  node_match_state["Match state<br/>[state.py]"]
  node_world_rules["Pitch and metrics<br/>[pitch.py]"]
  node_behavior["Player behavior"]
  node_physics["Physics simulation<br/>[simulation.py]"]
  node_penalties["Penalty shootouts<br/>[penalties.py]"]
end

subgraph group_realtime["Live updates"]
  node_event_bus["Event bus<br/>[event_bus.py]"]
  node_ws["WebSocket endpoints<br/>[ws_match.py]"]
  node_broadcast["Match broadcasts<br/>[match_broadcast.py]"]
end

subgraph group_data["Persistence"]
  node_repositories["Data repositories"]
  node_models["Domain records<br/>[match.py]"]
  node_db[("SQLAlchemy database<br/>[base.py]")]
end

node_user(("Player or coach"))

node_user -->|"uses API"| node_api_app
node_api_app -->|"registers"| node_auth_routes
node_api_app -->|"registers"| node_league_routes
node_api_app -->|"registers"| node_friendly_routes
node_api_app -->|"registers"| node_other_routes
node_auth_routes -->|"uses tokens"| node_security
node_league_routes -->|"calls"| node_league_service
node_league_routes -->|"starts league"| node_league_runner
node_league_routes -->|"configures lineup"| node_lineup
node_friendly_routes -->|"calls"| node_friendly_service
node_friendly_routes -->|"starts match"| node_match_start
node_league_runner -->|"starts matches"| node_match_start
node_league_runner -->|"runs matches"| node_match_runner
node_match_start -->|"prepares state"| node_match_state
node_match_start -->|"launches"| node_match_runner
node_match_start -->|"loads behavior"| node_behavior
node_match_runner -->|"updates"| node_match_state
node_match_runner -->|"simulates ticks"| node_physics
node_match_runner -->|"uses pitch rules"| node_world_rules
node_match_runner -->|"runs shootout"| node_penalties
node_match_runner -.->|"notifies clients"| node_event_bus
node_league_runner -->|"publishes events"| node_event_bus
node_friendly_routes -->|"publishes events"| node_event_bus
node_ws -.->|"receives events"| node_event_bus
node_match_start -->|"configures broadcast"| node_broadcast
node_other_routes -.->|"uses persistence"| node_repositories
node_repositories -->|"queries records"| node_models
node_models -->|"maps tables"| node_db
node_league_service -->|"queries league data"| node_repositories
node_league_runner -->|"loads match data"| node_repositories
node_friendly_service -.->|"uses match data"| node_repositories

click node_api_app "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/main.py"
click node_auth_routes "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/routes/auth.py"
click node_security "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/core/security.py"
click node_league_routes "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/routes/leagues.py"
click node_friendly_routes "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/routes/friendly.py"
click node_other_routes "https://github.com/ingsoft1-theglory/futbot-back/tree/master/src/routes"
click node_league_service "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/services/league_service.py"
click node_league_runner "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/services/league_run_service.py"
click node_friendly_service "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/services/friendly_service.py"
click node_lineup "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/services/lineup_service.py"
click node_match_start "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/services/match_start_service.py"
click node_match_runner "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/engine/match_runner.py"
click node_match_state "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/engine/_02_to_match/state.py"
click node_world_rules "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/engine/_01_to_world/pitch.py"
click node_behavior "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/engine/_03_to_builder/behavior_executor.py"
click node_physics "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/engine/_04_to_physics/simulation.py"
click node_penalties "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/engine/penalties.py"
click node_event_bus "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/realtime/event_bus.py"
click node_ws "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/routes/ws_match.py"
click node_broadcast "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/realtime/match_broadcast.py"
click node_repositories "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/repositories/match_repository.py"
click node_models "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/models/match.py"
click node_db "https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/database/base.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_api_app,node_auth_routes,node_security,node_league_routes,node_friendly_routes,node_other_routes toneBlue
class node_league_service,node_league_runner,node_friendly_service,node_lineup,node_match_start toneAmber
class node_match_runner,node_match_state,node_world_rules,node_behavior,node_physics,node_penalties toneMint
class node_event_bus,node_ws,node_broadcast toneRose
class node_repositories,node_models,node_db,node_user toneIndigo
```

## Components

### API and access

- [FastAPI app](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/main.py): `src/main.py`
- [Authentication routes](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/routes/auth.py): `src/routes/auth.py`
- [Tokens and security](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/core/security.py): `src/core/security.py`
- [League routes](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/routes/leagues.py): `src/routes/leagues.py`
- [Friendly routes](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/routes/friendly.py): `src/routes/friendly.py`
- [Match and player routes](https://github.com/ingsoft1-theglory/futbot-back/tree/master/src/routes): `src/routes`

### Competition workflows

- [League management](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/services/league_service.py): `src/services/league_service.py`
- [League scheduling](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/services/league_run_service.py): `src/services/league_run_service.py`
- [Friendly management](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/services/friendly_service.py): `src/services/friendly_service.py`
- [Lineup configuration](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/services/lineup_service.py): `src/services/lineup_service.py`
- [Match preparation](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/services/match_start_service.py): `src/services/match_start_service.py`

### Match simulation

- [Match tick loop](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/engine/match_runner.py): `src/engine/match_runner.py`
- [Match state](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/engine/_02_to_match/state.py): `src/engine/_02_to_match/state.py`
- [Pitch and metrics](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/engine/_01_to_world/pitch.py): `src/engine/_01_to_world/pitch.py`
- [Player behavior](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/engine/_03_to_builder/behavior_executor.py): `src/engine/_03_to_builder/behavior_executor.py`
- [Physics simulation](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/engine/_04_to_physics/simulation.py): `src/engine/_04_to_physics/simulation.py`
- [Penalty shootouts](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/engine/penalties.py): `src/engine/penalties.py`

### Live updates

- [Event bus](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/realtime/event_bus.py): `src/realtime/event_bus.py`
- [WebSocket endpoints](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/routes/ws_match.py): `src/routes/ws_match.py`
- [Match broadcasts](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/realtime/match_broadcast.py): `src/realtime/match_broadcast.py`

### Persistence

- [Data repositories](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/repositories/match_repository.py): `src/repositories/match_repository.py`
- [Domain records](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/models/match.py): `src/models/match.py`
- [SQLAlchemy database](https://github.com/ingsoft1-theglory/futbot-back/blob/master/src/database/base.py): `src/database/base.py`

### Other components

- **Player or coach**

## Connections

- Player or coach → FastAPI app: uses API
- FastAPI app → Authentication routes: registers (evidence: `src/main.py`)
- FastAPI app → League routes: registers (evidence: `src/main.py`)
- FastAPI app → Friendly routes: registers (evidence: `src/main.py`)
- FastAPI app → Match and player routes: registers (evidence: `src/main.py`)
- Authentication routes → Tokens and security: uses tokens (evidence: `src/routes/auth.py`)
- League routes → League management: calls (evidence: `src/routes/leagues.py`)
- League routes → League scheduling: starts league (evidence: `src/routes/leagues.py`)
- League routes → Lineup configuration: configures lineup (evidence: `src/routes/leagues.py`)
- Friendly routes → Friendly management: calls (evidence: `src/routes/friendly.py`)
- Friendly routes → Match preparation: starts match (evidence: `src/routes/friendly.py`)
- League scheduling → Match preparation: starts matches (evidence: `src/services/league_run_service.py`)
- League scheduling → Match tick loop: runs matches (evidence: `src/services/league_run_service.py`)
- Match preparation → Match state: prepares state (evidence: `src/services/match_start_service.py`)
- Match preparation → Match tick loop: launches (evidence: `src/services/match_start_service.py`)
- Match preparation → Player behavior: loads behavior (evidence: `src/services/match_start_service.py`)
- Match tick loop → Match state: updates (evidence: `src/engine/match_runner.py`)
- Match tick loop → Physics simulation: simulates ticks (evidence: `src/engine/_04_to_physics/simulation.py`)
- Match tick loop → Pitch and metrics: uses pitch rules (evidence: `src/engine/match_runner.py`)
- Match tick loop → Penalty shootouts: runs shootout (evidence: `src/engine/penalties.py`)
- Match tick loop → Event bus: notifies clients
- League scheduling → Event bus: publishes events (evidence: `src/services/league_run_service.py`)
- Friendly routes → Event bus: publishes events (evidence: `src/routes/friendly.py`)
- WebSocket endpoints → Event bus: receives events
- Match preparation → Match broadcasts: configures broadcast (evidence: `src/services/match_start_service.py`)
- Match and player routes → Data repositories: uses persistence
- Data repositories → Domain records: queries records (evidence: `src/repositories/match_repository.py`)
- Domain records → SQLAlchemy database: maps tables (evidence: `src/models/match.py`)
- League management → Data repositories: queries league data (evidence: `src/services/league_service.py`)
- League scheduling → Data repositories: loads match data (evidence: `src/services/league_run_service.py`)
- Friendly management → Data repositories: uses match data
