# magnusinst84-sudo/offside architecture

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

- Interactive diagram: https://gitdiagram.com/magnusinst84-sudo/offside
- Repository: https://github.com/magnusinst84-sudo/offside

## Overview

OFFSIDE is a football analytics dashboard whose main journey moves from the war-room entry to match discovery and a match view, where live match data and win-probability estimates provide tactical context. Separate branches support AI commentary, player profiles, insights, and user settings. The README documents API-Football/mock match sourcing, Gemini commentary, and an XGBoost-backed prediction capability; sampled source confirms app routing, polling, settings persistence, and some match handling, but not every backend route’s internal implementation.

Main entry points: [`backend/main.py`](https://github.com/magnusinst84-sudo/offside/blob/main/backend/main.py) (FastAPI entrypoint), [`frontend/app/players/page.tsx`](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/players/page.tsx) (Player browser), [`frontend/app/ai/page.tsx`](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/ai/page.tsx) (AI tactical center), [`frontend/app/settings/page.tsx`](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/settings/page.tsx) (Settings screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_home["War room entry<br/>[page.tsx]"]
  node_matches_page["Match listings<br/>[page.tsx]"]
  node_match_page["Match detail<br/>[page.tsx]"]
  node_players_page["Player browser<br/>[page.tsx]"]
  node_player_page["Player profile<br/>[page.tsx]"]
  node_ai_page["AI tactical center<br/>[page.tsx]"]
  node_insights_page["Insights dashboard<br/>[page.tsx]"]
  node_settings_page["Settings screen<br/>[page.tsx]"]
  node_app_context["Shared app state<br/>[AppContext.tsx]"]
  node_settings_store[("Settings persistence<br/>[useLocalStorage.ts]")]
  node_match_hooks["Match data hooks<br/>[useMatchData.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_backend["Backend services"]
  node_api_main["FastAPI entrypoint<br/>[main.py]"]
  node_matches_service["Match service<br/>[matches.py]"]
  node_prediction_service["Prediction service<br/>[predict.py]"]
  node_commentary_service["Commentary service<br/>[commentary.py]"]
  node_players_service["Player service<br/>[players.py]"]
  node_insights_service["Insights service<br/>[insights.py]"]
end

subgraph group_domain["Domain data"]
  node_player_data["Static player roster<br/>[players.ts]"]
end

node_fan(("Fan or coach"))
node_football_api{{"API-Football"}}
node_gemini{{"Gemini API"}}

node_fan -->|"opens app"| node_home
node_home -->|"opens listings"| node_matches_page
node_fan -->|"browses players"| node_players_page
node_players_page -->|"opens profile"| node_player_page
node_fan -->|"asks analyst"| node_ai_page
node_fan -->|"views insights"| node_insights_page
node_fan -->|"changes settings"| node_settings_page
node_settings_page -->|"reads panel state"| node_app_context
node_settings_page -->|"persists preferences"| node_settings_store
node_ai_page -->|"reads match context"| node_app_context
node_ai_page -->|"sends question"| node_api_client
node_matches_page -->|"loads matches"| node_match_hooks
node_match_page -->|"loads match data"| node_match_hooks
node_match_hooks -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_api_main
node_api_main -->|"routes matches"| node_matches_service
node_api_main -->|"routes predictions"| node_prediction_service
node_api_main -->|"routes commentary"| node_commentary_service
node_api_main -->|"routes players"| node_players_service
node_api_main -->|"routes insights"| node_insights_service
node_matches_service -.->|"fetches fixtures"| node_football_api
node_commentary_service -.->|"requests analysis"| node_gemini
node_players_page -->|"browses roster"| node_player_data
node_player_page -->|"reads profile"| node_player_data
node_insights_page -.->|"loads insights"| node_insights_service

click node_home "https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/page.tsx"
click node_matches_page "https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/matches/page.tsx"
click node_match_page "https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/match/%5Bid%5D/page.tsx"
click node_players_page "https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/players/page.tsx"
click node_player_page "https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/player/%5Bid%5D/page.tsx"
click node_ai_page "https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/ai/page.tsx"
click node_insights_page "https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/insights/page.tsx"
click node_settings_page "https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/settings/page.tsx"
click node_app_context "https://github.com/magnusinst84-sudo/offside/blob/main/frontend/context/AppContext.tsx"
click node_settings_store "https://github.com/magnusinst84-sudo/offside/blob/main/frontend/hooks/useLocalStorage.ts"
click node_match_hooks "https://github.com/magnusinst84-sudo/offside/blob/main/frontend/hooks/useMatchData.ts"
click node_api_client "https://github.com/magnusinst84-sudo/offside/blob/main/frontend/lib/api.ts"
click node_player_data "https://github.com/magnusinst84-sudo/offside/blob/main/frontend/lib/data/players.ts"
click node_api_main "https://github.com/magnusinst84-sudo/offside/blob/main/backend/main.py"
click node_matches_service "https://github.com/magnusinst84-sudo/offside/blob/main/backend/routers/matches.py"
click node_prediction_service "https://github.com/magnusinst84-sudo/offside/blob/main/backend/routers/predict.py"
click node_commentary_service "https://github.com/magnusinst84-sudo/offside/blob/main/backend/routers/commentary.py"
click node_players_service "https://github.com/magnusinst84-sudo/offside/blob/main/backend/routers/players.py"
click node_insights_service "https://github.com/magnusinst84-sudo/offside/blob/main/backend/routers/insights.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_home,node_matches_page,node_match_page,node_players_page,node_player_page,node_ai_page,node_insights_page,node_settings_page,node_app_context,node_settings_store,node_match_hooks,node_api_client toneBlue
class node_api_main,node_matches_service,node_prediction_service,node_commentary_service,node_players_service,node_insights_service toneAmber
class node_player_data,node_football_api,node_gemini toneMint
class node_fan toneIndigo
```

## Components

### Frontend experience

- [War room entry](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Match listings](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/matches/page.tsx): `frontend/app/matches/page.tsx`
- [Match detail](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/match/%5Bid%5D/page.tsx): `frontend/app/match/[id]/page.tsx`
- [Player browser](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/players/page.tsx): `frontend/app/players/page.tsx`
- [Player profile](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/player/%5Bid%5D/page.tsx): `frontend/app/player/[id]/page.tsx`
- [AI tactical center](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/ai/page.tsx): `frontend/app/ai/page.tsx`
- [Insights dashboard](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/insights/page.tsx): `frontend/app/insights/page.tsx`
- [Settings screen](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/app/settings/page.tsx): `frontend/app/settings/page.tsx`
- [Shared app state](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/context/AppContext.tsx): `frontend/context/AppContext.tsx`
- [Settings persistence](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/hooks/useLocalStorage.ts): `frontend/hooks/useLocalStorage.ts`
- [Match data hooks](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/hooks/useMatchData.ts): `frontend/hooks/useMatchData.ts`
- [API client](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Backend services

- [FastAPI entrypoint](https://github.com/magnusinst84-sudo/offside/blob/main/backend/main.py): `backend/main.py`
- [Match service](https://github.com/magnusinst84-sudo/offside/blob/main/backend/routers/matches.py): `backend/routers/matches.py`
- [Prediction service](https://github.com/magnusinst84-sudo/offside/blob/main/backend/routers/predict.py): `backend/routers/predict.py`
- [Commentary service](https://github.com/magnusinst84-sudo/offside/blob/main/backend/routers/commentary.py): `backend/routers/commentary.py`
- [Player service](https://github.com/magnusinst84-sudo/offside/blob/main/backend/routers/players.py): `backend/routers/players.py`
- [Insights service](https://github.com/magnusinst84-sudo/offside/blob/main/backend/routers/insights.py): `backend/routers/insights.py`

### Domain data

- [Static player roster](https://github.com/magnusinst84-sudo/offside/blob/main/frontend/lib/data/players.ts): `frontend/lib/data/players.ts`

### Other components

- **Fan or coach**
- **API-Football**
- **Gemini API**

## Connections

- Fan or coach → War room entry: opens app
- War room entry → Match listings: opens listings
- Fan or coach → Player browser: browses players
- Player browser → Player profile: opens profile
- Fan or coach → AI tactical center: asks analyst
- Fan or coach → Insights dashboard: views insights
- Fan or coach → Settings screen: changes settings
- Settings screen → Shared app state: reads panel state
- Settings screen → Settings persistence: persists preferences
- AI tactical center → Shared app state: reads match context
- AI tactical center → API client: sends question
- Match listings → Match data hooks: loads matches
- Match detail → Match data hooks: loads match data
- Match data hooks → API client: requests data
- API client → FastAPI entrypoint: calls API
- FastAPI entrypoint → Match service: routes matches
- FastAPI entrypoint → Prediction service: routes predictions
- FastAPI entrypoint → Commentary service: routes commentary
- FastAPI entrypoint → Player service: routes players
- FastAPI entrypoint → Insights service: routes insights
- Match service → API-Football: fetches fixtures
- Commentary service → Gemini API: requests analysis
- Player browser → Static player roster: browses roster
- Player profile → Static player roster: reads profile
- Insights dashboard → Insights service: loads insights