# ravin06/astra-f1 architecture

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

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

## Overview

APEX / Grand Circuit is a local, single-player browser racing game. The player selects a circuit and race setup, configures a car or driver, then drives using keyboard, gamepad, or touch controls. The race runtime simulates the player and AI, validates laps, and records results; graphics, HUD, and synthesized audio present the session. Garage settings, presets, and progress persist in browser storage. README capabilities include multiple race modes, weather, replay, customization, and records. The graph follows the sampled runtime wiring; unsampled feature details are represented by their known implementing modules where supported.

Main entry points: [`src/main.js`](https://github.com/ravin06/astra-f1/blob/master/src/main.js) (Game Coordinator), [`src/data.js`](https://github.com/ravin06/astra-f1/blob/master/src/data.js) (Game Catalog), [`src/race.js`](https://github.com/ravin06/astra-f1/blob/master/src/race.js) (Race Session), [`src/graphics.js`](https://github.com/ravin06/astra-f1/blob/master/src/graphics.js) (3D Renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Player Experience"]
  node_app["Game Coordinator<br/>[main.js]"]
  node_ui["Menus and HUD<br/>[ui.js]"]
  node_input["Control Input<br/>[input.js]"]
  node_audio["Synthesized Audio<br/>[audio.js]"]
end

subgraph group_race["Race Runtime"]
  node_race["Race Session<br/>[race.js]"]
  node_physics["Driving and AI Physics<br/>[physics.js]"]
end

subgraph group_world["Circuits and Presentation"]
  node_track["Track Geometry<br/>[track.js]"]
  node_circuitdata["Circuit Layouts<br/>[circuits.js]"]
  node_graphics["3D Renderer<br/>[graphics.js]"]
  node_car["Formula Car Models<br/>[formula-car.js]"]
  node_scenery["Circuit Scenery<br/>[circuit-scenery.js]"]
end

subgraph group_profile["Profile and Saves"]
  node_gamedata["Game Catalog<br/>[data.js]"]
  node_persistence["Profile and Presets<br/>[persistence.js]"]
  node_localstore[("Browser Storage")]
end

node_player(("Player"))

node_player -->|"uses menus"| node_ui
node_ui -->|"dispatches actions"| node_app
node_app -->|"reads controls"| node_input
node_app -->|"starts and updates"| node_race
node_app -->|"builds and renders"| node_graphics
node_app -->|"plays cues"| node_audio
node_app -->|"updates display"| node_ui
node_app -->|"loads and saves"| node_persistence
node_app -->|"selects circuit"| node_track
node_app -->|"reads configuration"| node_gamedata
node_race -->|"steps karts"| node_physics
node_race -->|"queries track"| node_track
node_race -->|"uses vehicle stats"| node_gamedata
node_physics -->|"samples surface"| node_track
node_gamedata -->|"exports layouts"| node_circuitdata
node_graphics -->|"creates car models"| node_car
node_graphics -->|"adds scenery"| node_scenery
node_graphics -->|"reads vehicles"| node_gamedata
node_ui -->|"reads catalog"| node_gamedata
node_persistence -->|"sanitizes profile"| node_gamedata
node_persistence -->|"reads and writes"| node_localstore

click node_app "https://github.com/ravin06/astra-f1/blob/master/src/main.js"
click node_ui "https://github.com/ravin06/astra-f1/blob/master/src/ui.js"
click node_input "https://github.com/ravin06/astra-f1/blob/master/src/input.js"
click node_audio "https://github.com/ravin06/astra-f1/blob/master/src/audio.js"
click node_race "https://github.com/ravin06/astra-f1/blob/master/src/race.js"
click node_physics "https://github.com/ravin06/astra-f1/blob/master/src/physics.js"
click node_track "https://github.com/ravin06/astra-f1/blob/master/src/track.js"
click node_circuitdata "https://github.com/ravin06/astra-f1/blob/master/src/circuits.js"
click node_gamedata "https://github.com/ravin06/astra-f1/blob/master/src/data.js"
click node_graphics "https://github.com/ravin06/astra-f1/blob/master/src/graphics.js"
click node_car "https://github.com/ravin06/astra-f1/blob/master/src/formula-car.js"
click node_scenery "https://github.com/ravin06/astra-f1/blob/master/src/circuit-scenery.js"
click node_persistence "https://github.com/ravin06/astra-f1/blob/master/src/persistence.js"

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_ui,node_input,node_audio toneBlue
class node_race,node_physics toneAmber
class node_track,node_circuitdata,node_graphics,node_car,node_scenery toneMint
class node_gamedata,node_persistence,node_localstore toneRose
class node_player toneIndigo
```

## Components

### Player Experience

- [Game Coordinator](https://github.com/ravin06/astra-f1/blob/master/src/main.js): `src/main.js`
- [Menus and HUD](https://github.com/ravin06/astra-f1/blob/master/src/ui.js): `src/ui.js`
- [Control Input](https://github.com/ravin06/astra-f1/blob/master/src/input.js): `src/input.js`
- [Synthesized Audio](https://github.com/ravin06/astra-f1/blob/master/src/audio.js): `src/audio.js`

### Race Runtime

- [Race Session](https://github.com/ravin06/astra-f1/blob/master/src/race.js): `src/race.js`
- [Driving and AI Physics](https://github.com/ravin06/astra-f1/blob/master/src/physics.js): `src/physics.js`

### Circuits and Presentation

- [Track Geometry](https://github.com/ravin06/astra-f1/blob/master/src/track.js): `src/track.js`
- [Circuit Layouts](https://github.com/ravin06/astra-f1/blob/master/src/circuits.js): `src/circuits.js`
- [3D Renderer](https://github.com/ravin06/astra-f1/blob/master/src/graphics.js): `src/graphics.js`
- [Formula Car Models](https://github.com/ravin06/astra-f1/blob/master/src/formula-car.js): `src/formula-car.js`
- [Circuit Scenery](https://github.com/ravin06/astra-f1/blob/master/src/circuit-scenery.js): `src/circuit-scenery.js`

### Profile and Saves

- [Game Catalog](https://github.com/ravin06/astra-f1/blob/master/src/data.js): `src/data.js`
- [Profile and Presets](https://github.com/ravin06/astra-f1/blob/master/src/persistence.js): `src/persistence.js`
- **Browser Storage**

### Other components

- **Player**

## Connections

- Player → Menus and HUD: uses menus (evidence: `README.md`)
- Menus and HUD → Game Coordinator: dispatches actions (evidence: `src/ui.js`)
- Game Coordinator → Control Input: reads controls (evidence: `src/main.js`)
- Game Coordinator → Race Session: starts and updates (evidence: `src/main.js`)
- Game Coordinator → 3D Renderer: builds and renders (evidence: `src/main.js`)
- Game Coordinator → Synthesized Audio: plays cues (evidence: `src/main.js`)
- Game Coordinator → Menus and HUD: updates display (evidence: `src/main.js`)
- Game Coordinator → Profile and Presets: loads and saves (evidence: `src/main.js`)
- Game Coordinator → Track Geometry: selects circuit (evidence: `src/main.js`)
- Game Coordinator → Game Catalog: reads configuration (evidence: `src/main.js`)
- Race Session → Driving and AI Physics: steps karts (evidence: `src/race.js`)
- Race Session → Track Geometry: queries track (evidence: `src/race.js`)
- Race Session → Game Catalog: uses vehicle stats (evidence: `src/race.js`)
- Driving and AI Physics → Track Geometry: samples surface (evidence: `src/physics.js`)
- Game Catalog → Circuit Layouts: exports layouts (evidence: `src/data.js`)
- 3D Renderer → Formula Car Models: creates car models (evidence: `src/graphics.js`)
- 3D Renderer → Circuit Scenery: adds scenery (evidence: `src/graphics.js`)
- 3D Renderer → Game Catalog: reads vehicles (evidence: `src/graphics.js`)
- Menus and HUD → Game Catalog: reads catalog (evidence: `src/ui.js`)
- Profile and Presets → Game Catalog: sanitizes profile (evidence: `src/persistence.js`)
- Profile and Presets → Browser Storage: reads and writes (evidence: `src/persistence.js`)
