How ingsoft1-theglory/futbot-back works
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: match_runner.py Match tick loop · match_start_service.py Match preparation · main.py FastAPI app · league_run_service.py League scheduling
Components 24
API and access
- FastAPI app
src/main.py - Authentication routes
src/routes/auth.py - Tokens and security
src/core/security.py - League routes
src/routes/leagues.py - Friendly routes
src/routes/friendly.py - Match and player routes
src/routes
Competition workflows
- League management
src/services/league_service.py - League scheduling
src/services/league_run_service.py - Friendly management
src/services/friendly_service.py - Lineup configuration
src/services/lineup_service.py - Match preparation
src/services/match_start_service.py
Match simulation
- Match tick loop
src/engine/match_runner.py - Match state
src/engine/_02_to_match/state.py - Pitch and metrics
src/engine/_01_to_world/pitch.py - Player behavior
src/engine/_03_to_builder/behavior_executor.py - Physics simulation
src/engine/_04_to_physics/simulation.py - Penalty shootouts
src/engine/penalties.py
Live updates
- Event bus
src/realtime/event_bus.py - WebSocket endpoints
src/routes/ws_match.py - Match broadcasts
src/realtime/match_broadcast.py
Persistence
- Data repositories
src/repositories/match_repository.py - Domain records
src/models/match.py - SQLAlchemy database
src/database/base.py
Other components
- Player or coach
Connections 31
- Player or coach → FastAPI app: uses API
- FastAPI app → Authentication routes: registers
src/main.py - FastAPI app → League routes: registers
src/main.py - FastAPI app → Friendly routes: registers
src/main.py - FastAPI app → Match and player routes: registers
src/main.py - Authentication routes → Tokens and security: uses tokens
src/routes/auth.py - League routes → League management: calls
src/routes/leagues.py - League routes → League scheduling: starts league
src/routes/leagues.py - League routes → Lineup configuration: configures lineup
src/routes/leagues.py - Friendly routes → Friendly management: calls
src/routes/friendly.py - Friendly routes → Match preparation: starts match
src/routes/friendly.py - League scheduling → Match preparation: starts matches
src/services/league_run_service.py - League scheduling → Match tick loop: runs matches
src/services/league_run_service.py - Match preparation → Match state: prepares state
src/services/match_start_service.py - Match preparation → Match tick loop: launches
src/services/match_start_service.py - Match preparation → Player behavior: loads behavior
src/services/match_start_service.py - Match tick loop → Match state: updates
src/engine/match_runner.py - Match tick loop → Physics simulation: simulates ticks
src/engine/_04_to_physics/simulation.py - Match tick loop → Pitch and metrics: uses pitch rules
src/engine/match_runner.py - Match tick loop → Penalty shootouts: runs shootout
src/engine/penalties.py - Match tick loop → Event bus: notifies clients
- League scheduling → Event bus: publishes events
src/services/league_run_service.py - Friendly routes → Event bus: publishes events
src/routes/friendly.py - WebSocket endpoints → Event bus: receives events
- Match preparation → Match broadcasts: configures broadcast
src/services/match_start_service.py - Match and player routes → Data repositories: uses persistence
- Data repositories → Domain records: queries records
src/repositories/match_repository.py - Domain records → SQLAlchemy database: maps tables
src/models/match.py - League management → Data repositories: queries league data
src/services/league_service.py - League scheduling → Data repositories: loads match data
src/services/league_run_service.py - Friendly management → Data repositories: uses match data