# nolawimelese/mario-kart-picker architecture

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

- Interactive diagram: https://gitdiagram.com/nolawimelese/mario-kart-picker
- Repository: https://github.com/nolawimelese/mario-kart-picker

## Overview

MKPicker is a Mario Kart 8 Deluxe track-voting advisor. The user checks service availability, browses the catalog, enters their previous finishing position and three ballot tracks, then receives a ranked recommendation with reasons and strategy tips. The backend serves catalog and health endpoints and scores submitted tracks against race position and track strategies, using SQLite-backed track data. Settings provide theme preference. Component wiring beyond the sampled App and API code is inferred only where README capabilities establish the product workflow; omitted source limits some call-level links.

Main entry points: [`frontend/src/App.tsx`](https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/App.tsx) (App shell), [`backend/main.py`](https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/main.py) (Recommendation endpoint), [`frontend/src/CoursePicker.tsx`](https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/CoursePicker.tsx) (Track picker), [`backend/database.py`](https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/database.py) (Database session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_app["App shell<br/>[App.tsx]"]
  node_picker["Track picker<br/>[CoursePicker.tsx]"]
  node_browse["Track browser<br/>[Browse.tsx]"]
  node_settings["Settings panel<br/>[SettingsPanel.tsx]"]
  node_theme["Theme provider<br/>[ThemeContext.tsx]"]
  node_track_client["Track API client<br/>[tracks.ts]"]
  node_health_client["Health API client<br/>[health.ts]"]
  node_recommend_client["Recommendation client<br/>[recommend.ts]"]
end

subgraph group_api["Backend API"]
  node_health["Health endpoint<br/>[main.py]"]
  node_tracks_endpoint["Track catalog endpoint<br/>[main.py]"]
  node_recommend_endpoint["Recommendation endpoint<br/>[main.py]"]
end

subgraph group_domain["Recommendation domain"]
  node_track_model["Track and strategy models<br/>[models.py]"]
  node_scoring["Track scoring<br/>[recommender.py]"]
end

subgraph group_state["Persistence and preferences"]
  node_db_session["Database session<br/>[database.py]"]
  node_sqlite[("SQLite catalog<br/>[database.py]")]
  node_browser_storage[("Browser preference storage")]
end

node_player(("Player"))

node_player -->|"uses"| node_app
node_app -->|"checks service"| node_health_client
node_health_client -->|"requests health"| node_health
node_app -->|"loads catalog"| node_track_client
node_track_client -->|"requests tracks"| node_tracks_endpoint
node_app -->|"opens picker"| node_picker
node_app -->|"opens browser"| node_browse
node_player -->|"enters race details"| node_picker
node_picker -->|"submits ballot"| node_recommend_client
node_recommend_client -->|"posts position and tracks"| node_recommend_endpoint
node_recommend_endpoint -->|"queries tracks"| node_db_session
node_tracks_endpoint -->|"reads catalog"| node_db_session
node_db_session -->|"reads"| node_sqlite
node_recommend_endpoint -->|"scores tracks"| node_scoring
node_scoring -->|"returns scores and tips"| node_recommend_endpoint
node_recommend_endpoint -->|"loads track strategies"| node_track_model
node_tracks_endpoint -->|"serializes catalog"| node_track_model
node_player -->|"sets theme"| node_settings
node_settings -->|"updates preference"| node_theme
node_theme -->|"persists preference"| node_browser_storage

click node_app "https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/App.tsx"
click node_picker "https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/CoursePicker.tsx"
click node_browse "https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/Browse.tsx"
click node_settings "https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/SettingsPanel.tsx"
click node_theme "https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/design-system/theme/ThemeContext.tsx"
click node_track_client "https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/api/tracks.ts"
click node_health_client "https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/api/health.ts"
click node_recommend_client "https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/api/recommend.ts"
click node_health "https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/main.py"
click node_tracks_endpoint "https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/main.py"
click node_recommend_endpoint "https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/main.py"
click node_track_model "https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/models.py"
click node_scoring "https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/recommender.py"
click node_db_session "https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/database.py"
click node_sqlite "https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/database.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_app,node_picker,node_browse,node_settings,node_theme,node_track_client,node_health_client,node_recommend_client toneBlue
class node_health,node_tracks_endpoint,node_recommend_endpoint toneAmber
class node_track_model,node_scoring toneMint
class node_db_session,node_sqlite,node_browser_storage toneRose
class node_player toneIndigo
```

## Components

### Frontend experience

- [App shell](https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Track picker](https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/CoursePicker.tsx): `frontend/src/CoursePicker.tsx`
- [Track browser](https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/Browse.tsx): `frontend/src/Browse.tsx`
- [Settings panel](https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/SettingsPanel.tsx): `frontend/src/SettingsPanel.tsx`
- [Theme provider](https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/design-system/theme/ThemeContext.tsx): `frontend/src/design-system/theme/ThemeContext.tsx`
- [Track API client](https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/api/tracks.ts): `frontend/src/api/tracks.ts`
- [Health API client](https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/api/health.ts): `frontend/src/api/health.ts`
- [Recommendation client](https://github.com/nolawimelese/mario-kart-picker/blob/main/frontend/src/api/recommend.ts): `frontend/src/api/recommend.ts`

### Backend API

- [Health endpoint](https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/main.py): `backend/main.py`
- [Track catalog endpoint](https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/main.py): `backend/main.py`
- [Recommendation endpoint](https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/main.py): `backend/main.py`

### Recommendation domain

- [Track and strategy models](https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/models.py): `backend/models.py`
- [Track scoring](https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/recommender.py): `backend/recommender.py`

### Persistence and preferences

- [Database session](https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/database.py): `backend/database.py`
- [SQLite catalog](https://github.com/nolawimelese/mario-kart-picker/blob/main/backend/database.py): `backend/database.py`
- **Browser preference storage**

### Other components

- **Player**

## Connections

- Player → App shell: uses
- App shell → Health API client: checks service
- Health API client → Health endpoint: requests health
- App shell → Track API client: loads catalog
- Track API client → Track catalog endpoint: requests tracks
- App shell → Track picker: opens picker
- App shell → Track browser: opens browser
- Player → Track picker: enters race details
- Track picker → Recommendation client: submits ballot
- Recommendation client → Recommendation endpoint: posts position and tracks
- Recommendation endpoint → Database session: queries tracks
- Track catalog endpoint → Database session: reads catalog
- Database session → SQLite catalog: reads
- Recommendation endpoint → Track scoring: scores tracks
- Track scoring → Recommendation endpoint: returns scores and tips
- Recommendation endpoint → Track and strategy models: loads track strategies
- Track catalog endpoint → Track and strategy models: serializes catalog
- Player → Settings panel: sets theme
- Settings panel → Theme provider: updates preference
- Theme provider → Browser preference storage: persists preference