# eneaferri/altf1-racing architecture

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

- Interactive diagram: https://gitdiagram.com/eneaferri/altf1-racing
- Repository: https://github.com/eneaferri/altf1-racing
- Video tour (about a minute): https://gitdiagram.com/eneaferri/altf1-racing/video

## Overview

AltF1 Racing is a browser-based arcade racing game, with single-player and online multiplayer modes. The principal workflow is choosing a mode and circuit, driving through the shared simulation, and viewing the race in the client. Online play adds a server-managed lobby and rooms; clients exchange input and receive game updates. Shared modules also define track data and race rules, while OpenF1 tools support real-circuit content generation. The map follows the README and available index references; unsampled multiplayer and rendering internals limit some links.

Main entry points: [`01_packages/client/src/singleplayer/SinglePlayerGame.ts`](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/singleplayer/SinglePlayerGame.ts) (Single-Player Game), [`01_packages/server/src/GameServer.ts`](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/server/src/GameServer.ts) (Game Server), [`01_packages/shared/src/sim/game.ts`](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/shared/src/sim/game.ts) (Race Simulation), [`01_packages/client/src/main.ts`](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/main.ts) (Client Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser Client"]
  node_client_entry["Client Entry<br/>[main.ts]"]
  node_mode_menu["Mode Menu<br/>[ModeMenu.ts]"]
  node_singleplayer["Single-Player Game"]
  node_keyboard["Keyboard Input"]
  node_game_loop["Game Loop<br/>[GameLoop.ts]"]
  node_scene_view["Race Scene<br/>[SceneView.ts]"]
  node_hud["Race HUD<br/>[Hud.ts]"]
  node_multiplayer_start["Multiplayer Setup<br/>[start.ts]"]
  node_net_client["Network Client<br/>[NetClient.ts]"]
  node_online_game["Online Race<br/>[OnlineGame.ts]"]
end

subgraph group_server["Online Server"]
  node_game_server["Game Server<br/>[GameServer.ts]"]
  node_lobby["Lobby<br/>[Lobby.ts]"]
  node_room["Race Room<br/>[Room.ts]"]
  node_grand_prix["Grand Prix<br/>[GrandPrix.ts]"]
  node_lap_records[("Lap Records<br/>[LapRecords.ts]")]
end

subgraph group_shared["Shared Game Runtime"]
  node_simulation["Race Simulation<br/>[game.ts]"]
  node_car_physics["Car Physics<br/>[car.ts]"]
  node_track_query["Track Queries<br/>[query.ts]"]
  node_online_context["Online Sim Setup<br/>[simContext.ts]"]
  node_track_builder["Track Builder<br/>[buildTrack.ts]"]
end

subgraph group_content["Circuit Content"]
  node_openf1["OpenF1 Circuit Tools<br/>[generate.ts]"]
  node_circuit_data["Circuit Definitions<br/>[circuits.ts]"]
end

node_player(("Player"))
node_browser(("Browser"))

node_player -->|"plays in"| node_browser
node_browser -->|"opens"| node_client_entry
node_client_entry -->|"shows"| node_mode_menu
node_client_entry -->|"starts"| node_singleplayer
node_client_entry -->|"starts"| node_multiplayer_start
node_player -->|"chooses mode"| node_mode_menu
node_singleplayer -->|"samples input"| node_keyboard
node_singleplayer -->|"uses loop"| node_game_loop
node_singleplayer -->|"advances"| node_simulation
node_singleplayer -->|"renders race"| node_scene_view
node_singleplayer -->|"updates display"| node_hud
node_multiplayer_start -.->|"connects"| node_net_client
node_net_client -.->|"exchanges messages"| node_game_server
node_online_game -.->|"predicts locally"| node_simulation
node_game_server -->|"manages"| node_lobby
node_game_server -->|"routes race play"| node_room
node_game_server -->|"delegates GP"| node_grand_prix
node_game_server -->|"uses records"| node_lap_records
node_simulation -->|"advances cars"| node_car_physics
node_simulation -->|"queries track"| node_track_query
node_online_context -->|"configures"| node_simulation
node_openf1 -->|"uses definitions"| node_circuit_data
node_openf1 -.->|"produces track content"| node_track_builder

click node_client_entry "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/main.ts"
click node_mode_menu "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/view/menu/ModeMenu.ts"
click node_singleplayer "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/singleplayer/SinglePlayerGame.ts"
click node_keyboard "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/controller/KeyboardController.ts"
click node_game_loop "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/core/GameLoop.ts"
click node_scene_view "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/view/SceneView.ts"
click node_hud "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/view/hud/Hud.ts"
click node_multiplayer_start "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/multiplayer/start.ts"
click node_net_client "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/multiplayer/NetClient.ts"
click node_online_game "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/multiplayer/OnlineGame.ts"
click node_game_server "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/server/src/GameServer.ts"
click node_lobby "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/server/src/Lobby.ts"
click node_room "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/server/src/Room.ts"
click node_grand_prix "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/server/src/GrandPrix.ts"
click node_lap_records "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/server/src/LapRecords.ts"
click node_simulation "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/shared/src/sim/game.ts"
click node_car_physics "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/shared/src/sim/car.ts"
click node_track_query "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/shared/src/track/query.ts"
click node_online_context "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/shared/src/net/simContext.ts"
click node_track_builder "https://github.com/eneaferri/altf1-racing/blob/main/01_packages/shared/src/track/buildTrack.ts"
click node_openf1 "https://github.com/eneaferri/altf1-racing/blob/main/01_tools/openf1/generate.ts"
click node_circuit_data "https://github.com/eneaferri/altf1-racing/blob/main/01_tools/openf1/circuits.ts"

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_client_entry,node_mode_menu,node_singleplayer,node_keyboard,node_game_loop,node_scene_view,node_hud,node_multiplayer_start,node_net_client,node_online_game,node_browser toneBlue
class node_game_server,node_lobby,node_room,node_grand_prix,node_lap_records toneAmber
class node_simulation,node_car_physics,node_track_query,node_online_context,node_track_builder toneMint
class node_openf1,node_circuit_data toneRose
class node_player toneIndigo
```

## Components

### Browser Client

- [Client Entry](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/main.ts): `01_packages/client/src/main.ts`
- [Mode Menu](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/view/menu/ModeMenu.ts): `01_packages/client/src/view/menu/ModeMenu.ts`
- [Single-Player Game](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/singleplayer/SinglePlayerGame.ts): `01_packages/client/src/singleplayer/SinglePlayerGame.ts`
- [Keyboard Input](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/controller/KeyboardController.ts): `01_packages/client/src/controller/KeyboardController.ts`
- [Game Loop](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/core/GameLoop.ts): `01_packages/client/src/core/GameLoop.ts`
- [Race Scene](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/view/SceneView.ts): `01_packages/client/src/view/SceneView.ts`
- [Race HUD](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/view/hud/Hud.ts): `01_packages/client/src/view/hud/Hud.ts`
- [Multiplayer Setup](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/multiplayer/start.ts): `01_packages/client/src/multiplayer/start.ts`
- [Network Client](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/multiplayer/NetClient.ts): `01_packages/client/src/multiplayer/NetClient.ts`
- [Online Race](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/client/src/multiplayer/OnlineGame.ts): `01_packages/client/src/multiplayer/OnlineGame.ts`

### Online Server

- [Game Server](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/server/src/GameServer.ts): `01_packages/server/src/GameServer.ts`
- [Lobby](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/server/src/Lobby.ts): `01_packages/server/src/Lobby.ts`
- [Race Room](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/server/src/Room.ts): `01_packages/server/src/Room.ts`
- [Grand Prix](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/server/src/GrandPrix.ts): `01_packages/server/src/GrandPrix.ts`
- [Lap Records](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/server/src/LapRecords.ts): `01_packages/server/src/LapRecords.ts`

### Shared Game Runtime

- [Race Simulation](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/shared/src/sim/game.ts): `01_packages/shared/src/sim/game.ts`
- [Car Physics](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/shared/src/sim/car.ts): `01_packages/shared/src/sim/car.ts`
- [Track Queries](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/shared/src/track/query.ts): `01_packages/shared/src/track/query.ts`
- [Online Sim Setup](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/shared/src/net/simContext.ts): `01_packages/shared/src/net/simContext.ts`
- [Track Builder](https://github.com/eneaferri/altf1-racing/blob/main/01_packages/shared/src/track/buildTrack.ts): `01_packages/shared/src/track/buildTrack.ts`

### Circuit Content

- [OpenF1 Circuit Tools](https://github.com/eneaferri/altf1-racing/blob/main/01_tools/openf1/generate.ts): `01_tools/openf1/generate.ts`
- [Circuit Definitions](https://github.com/eneaferri/altf1-racing/blob/main/01_tools/openf1/circuits.ts): `01_tools/openf1/circuits.ts`

### Other components

- **Player**
- **Browser**

## Connections

- Player → Browser: plays in (evidence: `README.md`)
- Browser → Client Entry: opens (evidence: `README.md`)
- Client Entry → Mode Menu: shows (evidence: `01_packages/client/src/main.ts`)
- Client Entry → Single-Player Game: starts (evidence: `01_packages/client/src/main.ts`)
- Client Entry → Multiplayer Setup: starts (evidence: `01_packages/client/src/main.ts`)
- Player → Mode Menu: chooses mode (evidence: `README.md`)
- Single-Player Game → Keyboard Input: samples input (evidence: `01_packages/client/src/singleplayer/SinglePlayerGame.ts`)
- Single-Player Game → Game Loop: uses loop (evidence: `01_packages/client/src/singleplayer/SinglePlayerGame.ts`)
- Single-Player Game → Race Simulation: advances (evidence: `01_packages/shared/src/sim/game.ts`)
- Single-Player Game → Race Scene: renders race (evidence: `01_packages/client/src/singleplayer/SinglePlayerGame.ts`)
- Single-Player Game → Race HUD: updates display (evidence: `01_packages/client/src/singleplayer/SinglePlayerGame.ts`)
- Multiplayer Setup → Network Client: connects
- Network Client → Game Server: exchanges messages
- Online Race → Race Simulation: predicts locally
- Game Server → Lobby: manages (evidence: `01_packages/server/src/GameServer.ts`)
- Game Server → Race Room: routes race play (evidence: `01_packages/server/src/GameServer.ts`)
- Game Server → Grand Prix: delegates GP (evidence: `01_packages/server/src/GameServer.ts`)
- Game Server → Lap Records: uses records (evidence: `01_packages/server/src/GameServer.ts`)
- Race Simulation → Car Physics: advances cars (evidence: `01_packages/shared/src/sim/game.ts`)
- Race Simulation → Track Queries: queries track (evidence: `01_packages/shared/src/sim/game.ts`)
- Online Sim Setup → Race Simulation: configures (evidence: `01_packages/shared/src/net/simContext.ts`)
- OpenF1 Circuit Tools → Circuit Definitions: uses definitions (evidence: `01_tools/openf1/scenery.ts`)
- OpenF1 Circuit Tools → Track Builder: produces track content
