# aliemad0/pitchiq architecture

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

- Interactive diagram: https://gitdiagram.com/aliemad0/pitchiq
- Repository: https://github.com/aliemad0/pitchiq

## Overview

PitchIQ is a Premier League history and statistics web application, with an interactive football-game suite alongside its encyclopedia. The main user journey is browsing a season or entity profile, where server-rendered routes and API handlers resolve requests against validated, committed JSON snapshots and feature-specific data services, then present localized results. Major branches include fixtures and standings, player comparisons and leaderboards, teams and managers, the historic map, and deterministic trivia. The README documents these capabilities and the snapshot architecture; sampled source confirms several data, search, manager, and trivia relationships, while some feature internals were not sampled.

Main entry points: [`src/data/loaders.ts`](https://github.com/aliemad0/pitchiq/blob/main/src/data/loaders.ts) (Data loaders), [`src/app/[locale]`](https://github.com/aliemad0/pitchiq/tree/main/src/app/%5Blocale%5D) (App routes), [`src/features/game/view`](https://github.com/aliemad0/pitchiq/tree/main/src/features/game/view) (Game sessions), [`src/data`](https://github.com/aliemad0/pitchiq/tree/main/src/data) (JSON snapshots)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_routes["App routes"]
  node_api["Route handlers"]
  node_i18n["Localization"]
end

subgraph group_data["Data platform"]
  node_snapshots["JSON snapshots"]
  node_loaders["Data loaders<br/>[loaders.ts]"]
  node_schemas["Data schemas<br/>[schemas.ts]"]
  node_names["Entity names<br/>[entity-names.ts]"]
end

subgraph group_football["Football encyclopedia"]
  node_search["Search<br/>[route.ts]"]
  node_leagues["Fixtures &amp; tables"]
  node_players["Player profiles"]
  node_comparison["Player comparison"]
  node_teams["Club profiles"]
  node_managers["Manager profiles"]
  node_map["Historic map"]
  node_trivia["Fact engine<br/>[engine.ts]"]
end

subgraph group_play["Interactive games"]
  node_game["Game modes"]
  node_game_domain["Game rules"]
  node_game_view["Game sessions"]
  node_game_storage["Game storage"]
end

node_visitor(("Visitor"))
node_data_pipeline(("Refresh pipeline"))

node_visitor -->|"browses"| node_routes
node_routes -.->|"loads data"| node_loaders
node_api -->|"loads data"| node_loaders
node_loaders -->|"reads snapshots"| node_snapshots
node_loaders -->|"validates with"| node_schemas
node_api -->|"resolves names"| node_names
node_names -->|"loads translations"| node_loaders
node_routes -->|"localizes pages"| node_i18n
node_visitor -->|"searches"| node_search
node_visitor -->|"views fixtures"| node_leagues
node_visitor -->|"views profiles"| node_players
node_visitor -->|"compares players"| node_comparison
node_visitor -->|"views clubs"| node_teams
node_visitor -->|"views managers"| node_managers
node_visitor -->|"explores map"| node_map
node_visitor -->|"requests facts"| node_trivia
node_trivia -.->|"derives facts"| node_snapshots
node_visitor -->|"plays modes"| node_game
node_game -.->|"runs sessions"| node_game_view
node_game_view -.->|"applies rules"| node_game_domain
node_game_view -.->|"persists progress"| node_game_storage
node_data_pipeline -->|"refreshes daily"| node_snapshots

click node_routes "https://github.com/aliemad0/pitchiq/tree/main/src/app/%5Blocale%5D"
click node_api "https://github.com/aliemad0/pitchiq/tree/main/src/app/api"
click node_i18n "https://github.com/aliemad0/pitchiq/tree/main/src/i18n"
click node_snapshots "https://github.com/aliemad0/pitchiq/tree/main/src/data"
click node_loaders "https://github.com/aliemad0/pitchiq/blob/main/src/data/loaders.ts"
click node_schemas "https://github.com/aliemad0/pitchiq/blob/main/src/data/schemas.ts"
click node_names "https://github.com/aliemad0/pitchiq/blob/main/src/features/i18n/entity-names.ts"
click node_search "https://github.com/aliemad0/pitchiq/blob/main/src/app/api/search/route.ts"
click node_leagues "https://github.com/aliemad0/pitchiq/tree/main/src/features/leagues"
click node_players "https://github.com/aliemad0/pitchiq/tree/main/src/features/players"
click node_comparison "https://github.com/aliemad0/pitchiq/blob/main/src/features/players/comparison-metrics.ts"
click node_teams "https://github.com/aliemad0/pitchiq/tree/main/src/features/teams"
click node_managers "https://github.com/aliemad0/pitchiq/blob/main/src/features/managers/manager-profile.api.ts"
click node_map "https://github.com/aliemad0/pitchiq/tree/main/src/features/map"
click node_trivia "https://github.com/aliemad0/pitchiq/blob/main/src/features/trivia/engine.ts"
click node_game "https://github.com/aliemad0/pitchiq/tree/main/src/features/game/components"
click node_game_domain "https://github.com/aliemad0/pitchiq/tree/main/src/features/game/domain"
click node_game_view "https://github.com/aliemad0/pitchiq/tree/main/src/features/game/view"
click node_game_storage "https://github.com/aliemad0/pitchiq/tree/main/src/features/game/storage"

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_routes,node_api,node_i18n toneBlue
class node_snapshots,node_loaders,node_schemas,node_names toneAmber
class node_search,node_leagues,node_players,node_comparison,node_teams,node_managers,node_map,node_trivia toneMint
class node_game,node_game_domain,node_game_view,node_game_storage toneRose
class node_visitor,node_data_pipeline toneIndigo
```

## Components

### Web experience

- [App routes](https://github.com/aliemad0/pitchiq/tree/main/src/app/%5Blocale%5D): `src/app/[locale]`
- [Route handlers](https://github.com/aliemad0/pitchiq/tree/main/src/app/api): `src/app/api`
- [Localization](https://github.com/aliemad0/pitchiq/tree/main/src/i18n): `src/i18n`

### Data platform

- [JSON snapshots](https://github.com/aliemad0/pitchiq/tree/main/src/data): `src/data`
- [Data loaders](https://github.com/aliemad0/pitchiq/blob/main/src/data/loaders.ts): `src/data/loaders.ts`
- [Data schemas](https://github.com/aliemad0/pitchiq/blob/main/src/data/schemas.ts): `src/data/schemas.ts`
- [Entity names](https://github.com/aliemad0/pitchiq/blob/main/src/features/i18n/entity-names.ts): `src/features/i18n/entity-names.ts`

### Football encyclopedia

- [Search](https://github.com/aliemad0/pitchiq/blob/main/src/app/api/search/route.ts): `src/app/api/search/route.ts`
- [Fixtures & tables](https://github.com/aliemad0/pitchiq/tree/main/src/features/leagues): `src/features/leagues`
- [Player profiles](https://github.com/aliemad0/pitchiq/tree/main/src/features/players): `src/features/players`
- [Player comparison](https://github.com/aliemad0/pitchiq/blob/main/src/features/players/comparison-metrics.ts): `src/features/players/comparison-metrics.ts`
- [Club profiles](https://github.com/aliemad0/pitchiq/tree/main/src/features/teams): `src/features/teams`
- [Manager profiles](https://github.com/aliemad0/pitchiq/blob/main/src/features/managers/manager-profile.api.ts): `src/features/managers/manager-profile.api.ts`
- [Historic map](https://github.com/aliemad0/pitchiq/tree/main/src/features/map): `src/features/map`
- [Fact engine](https://github.com/aliemad0/pitchiq/blob/main/src/features/trivia/engine.ts): `src/features/trivia/engine.ts`

### Interactive games

- [Game modes](https://github.com/aliemad0/pitchiq/tree/main/src/features/game/components): `src/features/game/components`
- [Game rules](https://github.com/aliemad0/pitchiq/tree/main/src/features/game/domain): `src/features/game/domain`
- [Game sessions](https://github.com/aliemad0/pitchiq/tree/main/src/features/game/view): `src/features/game/view`
- [Game storage](https://github.com/aliemad0/pitchiq/tree/main/src/features/game/storage): `src/features/game/storage`

### Other components

- **Visitor**
- **Refresh pipeline**

## Connections

- Visitor → App routes: browses (evidence: `README.md`)
- App routes → Data loaders: loads data
- Route handlers → Data loaders: loads data (evidence: `src/app/api/search/route.ts`)
- Data loaders → JSON snapshots: reads snapshots (evidence: `src/data/loaders.ts`)
- Data loaders → Data schemas: validates with (evidence: `src/data/loaders.ts`)
- Route handlers → Entity names: resolves names (evidence: `src/app/api/search/route.ts`)
- Entity names → Data loaders: loads translations (evidence: `src/features/i18n/entity-names.ts`)
- App routes → Localization: localizes pages (evidence: `README.md`)
- Visitor → Search: searches (evidence: `README.md`)
- Visitor → Fixtures & tables: views fixtures (evidence: `README.md`)
- Visitor → Player profiles: views profiles (evidence: `README.md`)
- Visitor → Player comparison: compares players (evidence: `README.md`)
- Visitor → Club profiles: views clubs (evidence: `README.md`)
- Visitor → Manager profiles: views managers (evidence: `README.md`)
- Visitor → Historic map: explores map (evidence: `README.md`)
- Visitor → Fact engine: requests facts (evidence: `README.md`)
- Fact engine → JSON snapshots: derives facts
- Visitor → Game modes: plays modes (evidence: `README.md`)
- Game modes → Game sessions: runs sessions
- Game sessions → Game rules: applies rules
- Game sessions → Game storage: persists progress
- Refresh pipeline → JSON snapshots: refreshes daily (evidence: `README.md`)