# batmanscode/simdrive architecture

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

- Interactive diagram: https://gitdiagram.com/batmanscode/simdrive
- Repository: https://github.com/batmanscode/simdrive

## Overview

1. **Overall shape**
   - Sim Drive is a **TypeScript multiplayer game** with a **browser-based frontend** and a **Node.js authoritative server**.
   - The architecture is split between:
     - a **shared game domain layer** used by both client and server,
     - a **real-time game server** that owns room and race state,
     - and **browser clients** that render either the shared display or a phone controller.

2. **Client application**
   - The browser app lives under `src/` and is built with **Vite + React**.
   - `src/main.tsx` bootstraps the app, while `src/App.tsx` likely switches between the major experience modes: display, phone controller, lobby, tutorial, race, and results.
   - `src/styles.css` provides the UI styling for the whole game surface.

3. **Display vs controller roles**
   - The same frontend supports two very different roles:
     - the **shared display**, which shows the room, lobby, race HUD, and results,
     - the **phone controller**, which handles tilt steering, touch fallback, setup, and driver options.
   - This role split is central to the product: one browser acts as the host screen while multiple phones join as drivers.

4. **Authoritative server**
   - `server/index.ts` is the core simulation and room manager.
   - It owns:
     - room lifecycle,
     - player connection/disconnection,
     - race phase progression,
     - results and DNF handling,
     - and the authoritative movement/race logic.
   - The server is not just matchmaking; it runs the race rules and determines the source of truth for gameplay.

5. **Shared domain layer**
   - `src/shared/` contains code that must stay identical on both sides of the wire:
     - `cars.ts` for vehicle definitions and handling profiles,
     - `tracks.ts` for track data and procedural track structure,
     - `physics.ts` for movement/simulation helpers,
     - `types.ts` for shared room, driver, race, and message types.
   - This shared boundary reduces drift between what the client draws and what the server simulates.

6. **Real-time data flow**
   - Players connect to the server over the network and exchange room/race updates in real time, almost certainly via **WebSockets**.
   - The flow is:
     - display creates a room,
     - phones join using QR code or room code,
     - controller input streams to the server,
     - the server simulates the race and broadcasts authoritative state back to all clients.
   - The README notes that the dev server proxies WebSockets through the same origin, which simplifies local and Codespaces testing.

7. **Game-state and matchmaking boundaries**
   - Room flow is a major subsystem:
     - room creation,
     - controller join/resume,
     - VIP assignment,
     - lobby configuration,
     - one-player practice,
     - and room cleanup after disconnect.
   - The server keeps rooms alive through a short grace window if displays disconnect, which means room state is persistent across brief host interruptions but still server-owned.

8. **Race simulation subsystem**
   - The race logic includes vehicle-specific movement, lap counting, checkpoints, collisions, off-track reset behavior, warm-up/flying start timing, and results calculation.
   - The server also applies per-driver setup multipliers and vehicle-specific quirks, so the simulation is not just a generic kinematic loop; it is tied to the selected car and race settings.

9. **Rendering and presentation**
   - The display side renders the game’s presentation screens: landing, lobby, tutorial, in-race HUD, and results.
   - The README describes a cockpit-style race view with track ribbons, terrain, minimap, leaderboard, rear-view mirror, countdown lights, and auto-spectate after finish.
   - The exact rendering library is not explicit in the tree, but the architecture clearly separates **visual presentation** from the server simulation.

10. **Phone input and device-specific behavior**
   - The controller supports tilt steering, motion permission prompts, touch fallback controls, haptics, and browser-specific sensor paths.
   - This implies a distinct input subsystem on mobile that translates device motion and touch into normalized driving commands before sending them to the server.

11. **Automation and playtesting**
   - `playtests/` contains scripted test drivers and visual-capture tooling.
   - This is a separate verification layer for end-to-end race behavior, likely used to validate lap completion, full-race flow, and render output without manual phone testing.

12. **Deployment/runtime model**
   - In development, Vite serves the client while the Node server handles gameplay traffic.
   - In production, `npm start` runs a **single Node process on port 8787** that serves the built frontend and the WebSocket/game server together.
   - Static assets live in `public/` and include web metadata such as `robots.txt`, `site.webmanifest`, and `sitemap.xml`.

13. **Key architectural boundary to diagram**
   - The most important boundary is between:
     - **authoritative server simulation** and
     - **stateless-ish browser clients**.
   - Clients provide input and render state; the server owns the truth of room membership, race progress, physics, and results.

Main entry points: [`src/App.tsx`](https://github.com/batmanscode/simdrive/blob/main/src/App.tsx) (App), [`server/index.ts`](https://github.com/batmanscode/simdrive/blob/main/server/index.ts) (Game Server), [`package.json`](https://github.com/batmanscode/simdrive/blob/main/package.json) (Package), [`src/main.tsx`](https://github.com/batmanscode/simdrive/blob/main/src/main.tsx) (Main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser Client"]
  node_index_html["Entry HTML<br/>html shell<br/>[index.html]"]
  node_src_main["Main<br/>bootstrap<br/>[main.tsx]"]
  node_src_app["App<br/>ui router<br/>[App.tsx]"]
  node_src_styles["Styles<br/>ui css<br/>[styles.css]"]
end

subgraph group_shared["Shared Domain"]
  node_shared_types["Types<br/>shared contracts<br/>[types.ts]"]
  node_shared_cars["Cars<br/>vehicle data<br/>[cars.ts]"]
  node_shared_tracks["Tracks<br/>track data<br/>[tracks.ts]"]
  node_shared_physics["Physics<br/>simulation helpers<br/>[physics.ts]"]
end

subgraph group_server["Authoritative Server"]
  node_server_index["Game Server<br/>authoritative runtime<br/>[index.ts]"]
end

subgraph group_playtests["Playtests"]
  node_playtest_driver["Driver<br/>test client<br/>[driver.ts]"]
  node_playtest_full_lap["Full Lap<br/>scenario<br/>[full-lap.ts]"]
  node_playtest_capture["Capture<br/>visual tooling<br/>[visual-capture.ts]"]
end

subgraph group_static["Static Assets"]
  node_public_robots["Public Assets<br/>static files<br/>[robots.txt]"]
  node_public_manifest["Manifest<br/>[site.webmanifest]"]
  node_public_sitemap["Sitemap<br/>seo asset<br/>[sitemap.xml]"]
end

node_package_json["Package<br/>runtime scripts<br/>[package.json]"]

node_index_html -->|"loads"| node_src_main
node_src_main -->|"mounts"| node_src_app
node_src_app -->|"uses"| node_src_styles
node_src_app -->|"reads"| node_shared_types
node_src_app -->|"uses"| node_shared_cars
node_src_app -->|"uses"| node_shared_tracks
node_src_app -.->|"mirrors"| node_shared_physics
node_server_index -->|"contracts"| node_shared_types
node_server_index -->|"simulates"| node_shared_cars
node_server_index -->|"runs on"| node_shared_tracks
node_server_index -->|"executes"| node_shared_physics
node_server_index -->|"broadcasts"| node_src_app
node_playtest_driver -->|"drives"| node_server_index
node_playtest_full_lap -->|"uses"| node_playtest_driver
node_playtest_capture -.->|"captures"| node_playtest_full_lap
node_package_json -->|"starts"| node_server_index
node_package_json -->|"builds"| node_src_main
node_package_json -.->|"runs"| node_playtest_full_lap
node_public_robots -.->|"bundles"| node_public_manifest
node_public_manifest -.->|"bundles"| node_public_sitemap

click node_index_html "https://github.com/batmanscode/simdrive/blob/main/index.html"
click node_src_main "https://github.com/batmanscode/simdrive/blob/main/src/main.tsx"
click node_src_app "https://github.com/batmanscode/simdrive/blob/main/src/App.tsx"
click node_src_styles "https://github.com/batmanscode/simdrive/blob/main/src/styles.css"
click node_shared_types "https://github.com/batmanscode/simdrive/blob/main/src/shared/types.ts"
click node_shared_cars "https://github.com/batmanscode/simdrive/blob/main/src/shared/cars.ts"
click node_shared_tracks "https://github.com/batmanscode/simdrive/blob/main/src/shared/tracks.ts"
click node_shared_physics "https://github.com/batmanscode/simdrive/blob/main/src/shared/physics.ts"
click node_server_index "https://github.com/batmanscode/simdrive/blob/main/server/index.ts"
click node_playtest_driver "https://github.com/batmanscode/simdrive/blob/main/playtests/lib/driver.ts"
click node_playtest_full_lap "https://github.com/batmanscode/simdrive/blob/main/playtests/full-lap.ts"
click node_playtest_capture "https://github.com/batmanscode/simdrive/blob/main/playtests/visual-capture.ts"
click node_public_robots "https://github.com/batmanscode/simdrive/blob/main/public/robots.txt"
click node_public_manifest "https://github.com/batmanscode/simdrive/blob/main/public/site.webmanifest"
click node_public_sitemap "https://github.com/batmanscode/simdrive/blob/main/public/sitemap.xml"
click node_package_json "https://github.com/batmanscode/simdrive/blob/main/package.json"

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_index_html,node_src_main,node_src_app,node_src_styles toneBlue
class node_shared_types,node_shared_cars,node_shared_tracks,node_shared_physics toneAmber
class node_server_index toneMint
class node_playtest_driver,node_playtest_full_lap,node_playtest_capture toneRose
class node_public_robots,node_public_manifest,node_public_sitemap toneIndigo
class node_package_json toneNeutral
```

## Components

### Browser Client

Vite + React frontend with shared display and phone controller roles.

- [Entry HTML](https://github.com/batmanscode/simdrive/blob/main/index.html): html shell · Bootstraps the browser app and static asset loading. · `index.html`
- [Main](https://github.com/batmanscode/simdrive/blob/main/src/main.tsx): bootstrap · Starts the React frontend. · `src/main.tsx`
- [App](https://github.com/batmanscode/simdrive/blob/main/src/App.tsx): ui router · Switches between display, controller, lobby, race, and results experiences. · `src/App.tsx`
- [Styles](https://github.com/batmanscode/simdrive/blob/main/src/styles.css): ui css · Global presentation styling for the game surface. · `src/styles.css`

### Shared Domain

Game models and simulation helpers used by both client and server.

- [Types](https://github.com/batmanscode/simdrive/blob/main/src/shared/types.ts): shared contracts · Room, driver, race, and message types shared across the wire. · `src/shared/types.ts`
- [Cars](https://github.com/batmanscode/simdrive/blob/main/src/shared/cars.ts): vehicle data · Vehicle definitions and handling profiles. · `src/shared/cars.ts`
- [Tracks](https://github.com/batmanscode/simdrive/blob/main/src/shared/tracks.ts): track data · Track layouts and procedural track structure. · `src/shared/tracks.ts`
- [Physics](https://github.com/batmanscode/simdrive/blob/main/src/shared/physics.ts): simulation helpers · Movement and simulation helpers shared by client and server. · `src/shared/physics.ts`

### Authoritative Server

Node runtime that owns rooms, races, and real-time game state.

- [Game Server](https://github.com/batmanscode/simdrive/blob/main/server/index.ts): authoritative runtime · Owns rooms, race phases, player state, and race simulation. · `server/index.ts`

### Playtests

Scripted end-to-end drivers and visual capture tooling.

- [Driver](https://github.com/batmanscode/simdrive/blob/main/playtests/lib/driver.ts): test client · Scripted driver used to automate gameplay flows. · `playtests/lib/driver.ts`
- [Full Lap](https://github.com/batmanscode/simdrive/blob/main/playtests/full-lap.ts): scenario · End-to-end race scenario for lap completion and flow validation. · `playtests/full-lap.ts`
- [Capture](https://github.com/batmanscode/simdrive/blob/main/playtests/visual-capture.ts): visual tooling · Runs visual capture around game playback. · `playtests/visual-capture.ts`

### Static Assets

Public files served with the built app.

- [Public Assets](https://github.com/batmanscode/simdrive/blob/main/public/robots.txt): static files · Robots, web manifest, and sitemap served with the app. · `public/robots.txt`
- [Manifest](https://github.com/batmanscode/simdrive/blob/main/public/site.webmanifest): web manifest · Browser app metadata for install and sharing. · `public/site.webmanifest`
- [Sitemap](https://github.com/batmanscode/simdrive/blob/main/public/sitemap.xml): seo asset · Site indexing metadata. · `public/sitemap.xml`

### Other components

- [Package](https://github.com/batmanscode/simdrive/blob/main/package.json): runtime scripts · Defines the client/server build and start workflow. · `package.json`

## Connections

- Entry HTML → Main: loads · HTML entry loads the React bootstrap.
- Main → App: mounts · Main entry renders the application shell.
- App → Styles: uses · App-wide presentation styling.
- App → Types: reads · UI reacts to shared room and race state.
- App → Cars: uses · Shows vehicle selections and properties.
- App → Tracks: uses · Renders track-dependent screens and previews.
- App → Physics: mirrors · Client-side presentation aligns with simulation rules.
- Game Server → Types: contracts · Server and client communicate through shared message and state types.
- Game Server → Cars: simulates · Vehicle handling and tuning inform race behavior.
- Game Server → Tracks: runs on · Server race logic is track-aware.
- Game Server → Physics: executes · Authoritative movement and race calculations.
- Game Server → App: broadcasts · Streams authoritative room and race state back to clients.
- Driver → Game Server: drives · Automated inputs exercise the game server.
- Full Lap → Driver: uses · Scenario logic is built on the scripted driver.
- Capture → Full Lap: captures · Visual tooling records scenario runs.
- Package → Game Server: starts · Production runtime launches the Node game server.
- Package → Main: builds · Frontend build and dev workflow.
- Package → Full Lap: runs · Playtest scripts are part of the project toolchain.
- Public Assets → Manifest: bundles · Public site metadata lives alongside other static assets.
- Manifest → Sitemap: bundles · Static web metadata set.
