# luciferakj/f1 architecture

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

- Interactive diagram: https://gitdiagram.com/luciferakj/f1
- Repository: https://github.com/luciferakj/f1

## Overview

F1 Race Replay lets a user choose a season, event, and session, then inspect a synchronized race replay and its telemetry and derived race intelligence. The frontend combines REST metadata/frame requests with WebSocket playback; the FastAPI backend loads FastF1 sessions and produces cached, interpolated replay frames. The graph retains documented analytics, timing, bookmarks, and interaction features. Some frontend wiring and several backend modules are unsampled, so edges for those are limited to README statements or omitted.

Main entry points: [`frontend/components/layout/MainDashboard.tsx`](https://github.com/luciferakj/f1/blob/main/frontend/components/layout/MainDashboard.tsx) (Replay dashboard), [`backend/api/replay.py`](https://github.com/luciferakj/f1/blob/main/backend/api/replay.py) (Replay endpoints), [`backend/telemetry/pipeline.py`](https://github.com/luciferakj/f1/blob/main/backend/telemetry/pipeline.py) (Replay data pipeline), [`backend/api/sessions.py`](https://github.com/luciferakj/f1/blob/main/backend/api/sessions.py) (Session endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Replay frontend"]
  node_season_picker["Season selector<br/>[page.tsx]"]
  node_replay_page["Replay route<br/>[page.tsx]"]
  node_dashboard["Replay dashboard<br/>[MainDashboard.tsx]"]
  node_frontend_api["API client<br/>[apiClient.ts]"]
  node_playback["Playback controls"]
  node_replay_state["Replay state<br/>[replayStore.ts]"]
  node_timing["Timing tower"]
  node_telemetry_view["Telemetry dashboard"]
end

subgraph group_backend_api["Backend API"]
  node_app["FastAPI application<br/>[main.py]"]
  node_sessions_api["Session endpoints<br/>[sessions.py]"]
  node_replay_api["Replay endpoints<br/>[replay.py]"]
  node_ws_api["Playback WebSocket<br/>[ws_replay.py]"]
  node_schemas["API response models<br/>[schemas.py]"]
end

subgraph group_data["Session and telemetry data"]
  node_fastf1_service["FastF1 session service<br/>[fastf1_service.py]"]
  node_overview["Session overview"]
  node_pipeline["Replay data pipeline<br/>[pipeline.py]"]
  node_loader["Raw telemetry loader<br/>[loader.py]"]
  node_processor["Frame processor<br/>[processor.py]"]
  node_query["Frame queries<br/>[query.py]"]
  node_cache[("Processed replay cache<br/>[cache.py]")]
  node_telemetry_models["Replay data models<br/>[models.py]"]
end

subgraph group_rendering["Track rendering"]
  node_track_canvas["Replay canvas<br/>[ReplayCanvas.tsx]"]
  node_pixi_engine["Pixi replay engine"]
  node_track_layer["Track layer<br/>[TrackLayer.ts]"]
  node_car_sprite["Car sprites<br/>[CarSprite.ts]"]
  node_camera["Camera controller"]
end

subgraph group_insights["Analytics and intelligence"]
  node_analytics["Telemetry analytics"]
  node_race_intel["Race intelligence"]
  node_race_insights["Race insights"]
  node_bookmarks["Replay bookmarks<br/>[useBookmarks.ts]"]
end

node_user(("Race viewer"))
node_fastf1["FastF1 data source"]

node_user -->|"chooses session"| node_season_picker
node_season_picker -->|"requests events"| node_sessions_api
node_user -->|"opens replay"| node_replay_page
node_replay_page -.->|"shows replay"| node_dashboard
node_dashboard -->|"requests replay data"| node_frontend_api
node_frontend_api -->|"fetches schedule"| node_sessions_api
node_frontend_api -->|"fetches REST data"| node_replay_api
node_playback -->|"streams playback"| node_ws_api
node_dashboard -.->|"controls playback"| node_playback
node_dashboard -.->|"uses replay state"| node_replay_state
node_dashboard -->|"shows timing"| node_timing
node_dashboard -->|"shows telemetry"| node_telemetry_view
node_dashboard -->|"shows analytics"| node_analytics
node_dashboard -->|"shows intelligence"| node_race_intel
node_dashboard -.->|"shows insights"| node_race_insights
node_dashboard -->|"offers bookmarks"| node_bookmarks
node_dashboard -->|"renders replay"| node_track_canvas
node_track_canvas -->|"mounts engine"| node_pixi_engine
node_pixi_engine -->|"creates layer"| node_track_layer
node_pixi_engine -->|"creates sprites"| node_car_sprite
node_pixi_engine -->|"creates controller"| node_camera
node_app -->|"registers router"| node_sessions_api
node_app -->|"registers router"| node_replay_api
node_app -->|"registers router"| node_ws_api
node_sessions_api -->|"loads schedule/session"| node_fastf1_service
node_sessions_api -->|"builds overview"| node_overview
node_overview -->|"creates response models"| node_schemas
node_replay_api -->|"loads session"| node_fastf1_service
node_replay_api -->|"builds overview"| node_overview
node_replay_api -->|"gets replay data"| node_pipeline
node_replay_api -->|"filters and looks up frames"| node_query
node_replay_api -->|"reads frame interval"| node_processor
node_replay_api -->|"returns API models"| node_schemas
node_ws_api -->|"gets replay data"| node_pipeline
node_ws_api -->|"queries frames"| node_query
node_pipeline -->|"reads and writes"| node_cache
node_pipeline -->|"loads session"| node_fastf1_service
node_pipeline -->|"extracts telemetry"| node_loader
node_pipeline -->|"builds frames"| node_processor
node_pipeline -->|"returns replay data"| node_telemetry_models
node_processor -->|"creates frames"| node_telemetry_models
node_query -->|"filters frames"| node_telemetry_models
node_fastf1_service -->|"loads session data"| node_fastf1

click node_season_picker "https://github.com/luciferakj/f1/blob/main/frontend/app/page.tsx"
click node_replay_page "https://github.com/luciferakj/f1/blob/main/frontend/app/replay/%5Byear%5D/%5Bevent%5D/%5Bsession%5D/page.tsx"
click node_dashboard "https://github.com/luciferakj/f1/blob/main/frontend/components/layout/MainDashboard.tsx"
click node_frontend_api "https://github.com/luciferakj/f1/blob/main/frontend/lib/apiClient.ts"
click node_playback "https://github.com/luciferakj/f1/blob/main/frontend/hooks/useReplayWebSocket.ts"
click node_replay_state "https://github.com/luciferakj/f1/blob/main/frontend/store/replayStore.ts"
click node_timing "https://github.com/luciferakj/f1/blob/main/frontend/components/leaderboard/LeaderboardPanel.tsx"
click node_telemetry_view "https://github.com/luciferakj/f1/tree/main/frontend/components/telemetry"
click node_analytics "https://github.com/luciferakj/f1/tree/main/frontend/components/analytics"
click node_race_intel "https://github.com/luciferakj/f1/tree/main/frontend/components/timeline"
click node_race_insights "https://github.com/luciferakj/f1/tree/main/frontend/components/insights"
click node_bookmarks "https://github.com/luciferakj/f1/blob/main/frontend/hooks/useBookmarks.ts"
click node_track_canvas "https://github.com/luciferakj/f1/blob/main/frontend/components/track/ReplayCanvas.tsx"
click node_pixi_engine "https://github.com/luciferakj/f1/blob/main/frontend/lib/pixi/PixiReplayEngine.ts"
click node_track_layer "https://github.com/luciferakj/f1/blob/main/frontend/lib/pixi/TrackLayer.ts"
click node_car_sprite "https://github.com/luciferakj/f1/blob/main/frontend/lib/pixi/CarSprite.ts"
click node_camera "https://github.com/luciferakj/f1/blob/main/frontend/lib/pixi/CameraController.ts"
click node_app "https://github.com/luciferakj/f1/blob/main/backend/main.py"
click node_sessions_api "https://github.com/luciferakj/f1/blob/main/backend/api/sessions.py"
click node_replay_api "https://github.com/luciferakj/f1/blob/main/backend/api/replay.py"
click node_ws_api "https://github.com/luciferakj/f1/blob/main/backend/api/ws_replay.py"
click node_schemas "https://github.com/luciferakj/f1/blob/main/backend/models/schemas.py"
click node_fastf1_service "https://github.com/luciferakj/f1/blob/main/backend/services/fastf1_service.py"
click node_overview "https://github.com/luciferakj/f1/blob/main/backend/services/session_overview_service.py"
click node_pipeline "https://github.com/luciferakj/f1/blob/main/backend/telemetry/pipeline.py"
click node_loader "https://github.com/luciferakj/f1/blob/main/backend/telemetry/loader.py"
click node_processor "https://github.com/luciferakj/f1/blob/main/backend/telemetry/processor.py"
click node_query "https://github.com/luciferakj/f1/blob/main/backend/telemetry/query.py"
click node_cache "https://github.com/luciferakj/f1/blob/main/backend/telemetry/cache.py"
click node_telemetry_models "https://github.com/luciferakj/f1/blob/main/backend/telemetry/models.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_season_picker,node_replay_page,node_dashboard,node_frontend_api,node_playback,node_replay_state,node_timing,node_telemetry_view,node_user toneBlue
class node_app,node_sessions_api,node_replay_api,node_ws_api,node_schemas toneAmber
class node_fastf1_service,node_overview,node_pipeline,node_loader,node_processor,node_query,node_cache,node_telemetry_models toneMint
class node_track_canvas,node_pixi_engine,node_track_layer,node_car_sprite,node_camera toneRose
class node_analytics,node_race_intel,node_race_insights,node_bookmarks,node_fastf1 toneIndigo
```

## Components

### Replay frontend

- [Season selector](https://github.com/luciferakj/f1/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Replay route](https://github.com/luciferakj/f1/blob/main/frontend/app/replay/%5Byear%5D/%5Bevent%5D/%5Bsession%5D/page.tsx): `frontend/app/replay/[year]/[event]/[session]/page.tsx`
- [Replay dashboard](https://github.com/luciferakj/f1/blob/main/frontend/components/layout/MainDashboard.tsx): `frontend/components/layout/MainDashboard.tsx`
- [API client](https://github.com/luciferakj/f1/blob/main/frontend/lib/apiClient.ts): `frontend/lib/apiClient.ts`
- [Playback controls](https://github.com/luciferakj/f1/blob/main/frontend/hooks/useReplayWebSocket.ts): `frontend/hooks/useReplayWebSocket.ts`
- [Replay state](https://github.com/luciferakj/f1/blob/main/frontend/store/replayStore.ts): `frontend/store/replayStore.ts`
- [Timing tower](https://github.com/luciferakj/f1/blob/main/frontend/components/leaderboard/LeaderboardPanel.tsx): `frontend/components/leaderboard/LeaderboardPanel.tsx`
- [Telemetry dashboard](https://github.com/luciferakj/f1/tree/main/frontend/components/telemetry): `frontend/components/telemetry`

### Backend API

- [FastAPI application](https://github.com/luciferakj/f1/blob/main/backend/main.py): `backend/main.py`
- [Session endpoints](https://github.com/luciferakj/f1/blob/main/backend/api/sessions.py): `backend/api/sessions.py`
- [Replay endpoints](https://github.com/luciferakj/f1/blob/main/backend/api/replay.py): `backend/api/replay.py`
- [Playback WebSocket](https://github.com/luciferakj/f1/blob/main/backend/api/ws_replay.py): `backend/api/ws_replay.py`
- [API response models](https://github.com/luciferakj/f1/blob/main/backend/models/schemas.py): `backend/models/schemas.py`

### Session and telemetry data

- [FastF1 session service](https://github.com/luciferakj/f1/blob/main/backend/services/fastf1_service.py): `backend/services/fastf1_service.py`
- [Session overview](https://github.com/luciferakj/f1/blob/main/backend/services/session_overview_service.py): `backend/services/session_overview_service.py`
- [Replay data pipeline](https://github.com/luciferakj/f1/blob/main/backend/telemetry/pipeline.py): `backend/telemetry/pipeline.py`
- [Raw telemetry loader](https://github.com/luciferakj/f1/blob/main/backend/telemetry/loader.py): `backend/telemetry/loader.py`
- [Frame processor](https://github.com/luciferakj/f1/blob/main/backend/telemetry/processor.py): `backend/telemetry/processor.py`
- [Frame queries](https://github.com/luciferakj/f1/blob/main/backend/telemetry/query.py): `backend/telemetry/query.py`
- [Processed replay cache](https://github.com/luciferakj/f1/blob/main/backend/telemetry/cache.py): `backend/telemetry/cache.py`
- [Replay data models](https://github.com/luciferakj/f1/blob/main/backend/telemetry/models.py): `backend/telemetry/models.py`

### Track rendering

- [Replay canvas](https://github.com/luciferakj/f1/blob/main/frontend/components/track/ReplayCanvas.tsx): `frontend/components/track/ReplayCanvas.tsx`
- [Pixi replay engine](https://github.com/luciferakj/f1/blob/main/frontend/lib/pixi/PixiReplayEngine.ts): `frontend/lib/pixi/PixiReplayEngine.ts`
- [Track layer](https://github.com/luciferakj/f1/blob/main/frontend/lib/pixi/TrackLayer.ts): `frontend/lib/pixi/TrackLayer.ts`
- [Car sprites](https://github.com/luciferakj/f1/blob/main/frontend/lib/pixi/CarSprite.ts): `frontend/lib/pixi/CarSprite.ts`
- [Camera controller](https://github.com/luciferakj/f1/blob/main/frontend/lib/pixi/CameraController.ts): `frontend/lib/pixi/CameraController.ts`

### Analytics and intelligence

- [Telemetry analytics](https://github.com/luciferakj/f1/tree/main/frontend/components/analytics): `frontend/components/analytics`
- [Race intelligence](https://github.com/luciferakj/f1/tree/main/frontend/components/timeline): `frontend/components/timeline`
- [Race insights](https://github.com/luciferakj/f1/tree/main/frontend/components/insights): `frontend/components/insights`
- [Replay bookmarks](https://github.com/luciferakj/f1/blob/main/frontend/hooks/useBookmarks.ts): `frontend/hooks/useBookmarks.ts`

### Other components

- **Race viewer**
- **FastF1 data source**

## Connections

- Race viewer → Season selector: chooses session
- Season selector → Session endpoints: requests events
- Race viewer → Replay route: opens replay
- Replay route → Replay dashboard: shows replay
- Replay dashboard → API client: requests replay data
- API client → Session endpoints: fetches schedule
- API client → Replay endpoints: fetches REST data
- Playback controls → Playback WebSocket: streams playback
- Replay dashboard → Playback controls: controls playback
- Replay dashboard → Replay state: uses replay state
- Replay dashboard → Timing tower: shows timing
- Replay dashboard → Telemetry dashboard: shows telemetry
- Replay dashboard → Telemetry analytics: shows analytics
- Replay dashboard → Race intelligence: shows intelligence
- Replay dashboard → Race insights: shows insights
- Replay dashboard → Replay bookmarks: offers bookmarks
- Replay dashboard → Replay canvas: renders replay
- Replay canvas → Pixi replay engine: mounts engine
- Pixi replay engine → Track layer: creates layer (evidence: `frontend/lib/pixi/PixiReplayEngine.ts`)
- Pixi replay engine → Car sprites: creates sprites (evidence: `frontend/lib/pixi/PixiReplayEngine.ts`)
- Pixi replay engine → Camera controller: creates controller (evidence: `frontend/lib/pixi/PixiReplayEngine.ts`)
- FastAPI application → Session endpoints: registers router (evidence: `backend/main.py`)
- FastAPI application → Replay endpoints: registers router (evidence: `backend/main.py`)
- FastAPI application → Playback WebSocket: registers router (evidence: `backend/main.py`)
- Session endpoints → FastF1 session service: loads schedule/session (evidence: `backend/api/sessions.py`)
- Session endpoints → Session overview: builds overview (evidence: `backend/api/sessions.py`)
- Session overview → API response models: creates response models (evidence: `backend/services/session_overview_service.py`)
- Replay endpoints → FastF1 session service: loads session (evidence: `backend/api/replay.py`)
- Replay endpoints → Session overview: builds overview (evidence: `backend/api/replay.py`)
- Replay endpoints → Replay data pipeline: gets replay data (evidence: `backend/api/replay.py`)
- Replay endpoints → Frame queries: filters and looks up frames (evidence: `backend/api/replay.py`)
- Replay endpoints → Frame processor: reads frame interval (evidence: `backend/api/replay.py`)
- Replay endpoints → API response models: returns API models (evidence: `backend/api/replay.py`)
- Playback WebSocket → Replay data pipeline: gets replay data (evidence: `backend/api/ws_replay.py`)
- Playback WebSocket → Frame queries: queries frames (evidence: `backend/api/ws_replay.py`)
- Replay data pipeline → Processed replay cache: reads and writes (evidence: `backend/telemetry/pipeline.py`)
- Replay data pipeline → FastF1 session service: loads session (evidence: `backend/telemetry/pipeline.py`)
- Replay data pipeline → Raw telemetry loader: extracts telemetry (evidence: `backend/telemetry/pipeline.py`)
- Replay data pipeline → Frame processor: builds frames (evidence: `backend/telemetry/pipeline.py`)
- Replay data pipeline → Replay data models: returns replay data (evidence: `backend/telemetry/pipeline.py`)
- Frame processor → Replay data models: creates frames (evidence: `backend/telemetry/processor.py`)
- Frame queries → Replay data models: filters frames (evidence: `backend/telemetry/query.py`)
- FastF1 session service → FastF1 data source: loads session data (evidence: `backend/services/fastf1_service.py`)
