# hnthap/car-ride architecture

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

- Interactive diagram: https://gitdiagram.com/hnthap/car-ride
- Repository: https://github.com/hnthap/car-ride

## Overview

##### Project type and purpose
- This is a single-page, front-end 3D simulation (“Car Ride in Paris”) built with React, TypeScript, Three.js and Vite.
- Purpose: render a drivable car and Paris landmarks in WebGL, controlled via keyboard.

##### File structure
- Top-level:
- public/ — static 3D assets (.glb) and images
- src/ — application source
- components/ — React components for each model (EiffelTower, Car, Ground, etc.)
- hooks/ — custom React hooks (useControls, useWheels, useMessages)
- models/ — model preload wrappers (.jsx)
- utils.ts — helper functions
- App.tsx, MainScene.tsx, LandmarkChart.tsx — entry components
- Config & tooling files:
- vite.config.ts, tsconfig.json, package.json

##### README for additional insights
- Confirms it’s a NodeJS-based React app, built and served with Vite.
- No backend or database—pure front-end.
- Dev vs. production modes via `npm run dev` and `npm run preview`.

a. Main components:
- Browser Client (runtime)
- React Application Layer
- Three.js Renderer / WebGL Context
- Static Asset Store (public/*.glb, images, appconfig.json)
- Build Toolchain / Dev Server (Vite + NodeJS)
b. Relationships & interactions:
- User → Browser Client (keyboard input)
- Browser Client → React App (event handlers via useControls hook)
- React App → Three.js (MainScene renders scene graph)
- Three.js → Static Asset Store (loads .glb via fetch)
- React App → Hooks & Models (manage car physics, wheel rotation, messages)
- Vite Dev Server → Browser Client in dev; static server in preview.
c. Architectural patterns:
- Component-based UI (React)
- Data-flow with custom hooks (stateful logic separated)
- Asset-driven scene (declarative scene graph in TSX)
- Build/serve pipeline (Vite with HMR in dev, static serve in preview)
d. Key technologies:
- React + TypeScript
- Three.js (GLTFLoader, WebGLRenderer)
- Vite (development server, bundling)
- GLB 3D models (public folder)
- React hooks (useControls, useWheels, useMessages)

##### Detailed capture of architectural elements
- React component category (scene entrypoints vs. leaf model components).
- Custom hooks as middleware between UI and renderer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build & Dev Toolchain"
        VITE["Vite Dev Server / Bundler"]:::toolchain
        TS["tsconfig.json"]:::toolchain
        PKG["package.json"]:::toolchain
        VITE --- TS
        VITE --- PKG
    end

    Browser["Browser Client (runtime)"]:::runtime
    VITE -->|"serves index.html"| Browser

    HTML["index.html"]:::code
    click HTML "https://github.com/hnthap/car-ride/blob/main/index.html"
    Browser -->|"loads"| HTML

    Main["src/main.tsx"]:::code
    click Main "https://github.com/hnthap/car-ride/blob/main/src/main.tsx"
    Browser -->|"boots React"| Main

    subgraph "React Application"
        App["App.tsx"]:::code
        click App "https://github.com/hnthap/car-ride/blob/main/src/App.tsx"

        MS["MainScene.tsx"]:::code
        click MS "https://github.com/hnthap/car-ride/blob/main/src/MainScene.tsx"

        LC["LandmarkChart.tsx"]:::code
        click LC "https://github.com/hnthap/car-ride/blob/main/src/LandmarkChart.tsx"

        subgraph "Scene & Model Components"
            Car["Car.tsx"]:::code
            click Car "https://github.com/hnthap/car-ride/blob/main/src/components/Car.tsx"
            ET["EiffelTower.tsx"]:::code
            click ET "https://github.com/hnthap/car-ride/blob/main/src/components/EiffelTower.tsx"
            ADT["ArcDeTriomphe.tsx"]:::code
            click ADT "https://github.com/hnthap/car-ride/blob/main/src/components/ArcDeTriomphe.tsx"
            GD["Ground.tsx"]:::code
            click GD "https://github.com/hnthap/car-ride/blob/main/src/components/Ground.tsx"
            ND["NotreDameDeParis.tsx"]:::code
            click ND "https://github.com/hnthap/car-ride/blob/main/src/components/NotreDameDeParis.tsx"
            Tree["Tree.tsx"]:::code
            click Tree "https://github.com/hnthap/car-ride/blob/main/src/components/Tree.tsx"
            WheelComp["Wheel.tsx"]:::code
            click WheelComp "https://github.com/hnthap/car-ride/blob/main/src/components/Wheel.tsx"
        end

        subgraph "Model Preloaders"
            WCar["WheellessCar.jsx"]:::code
            click WCar "https://github.com/hnthap/car-ride/blob/main/src/models/WheellessCar.jsx"
            WA["WheelA.jsx"]:::code
            click WA "https://github.com/hnthap/car-ride/blob/main/src/models/WheelA.jsx"
            ETm["EiffelTower.jsx"]:::code
            click ETm "https://github.com/hnthap/car-ride/blob/main/src/models/EiffelTower.jsx"
            ADTm["ArcDeTriomphe.jsx"]:::code
            click ADTm "https://github.com/hnthap/car-ride/blob/main/src/models/ArcDeTriomphe.jsx"
            NDm["NotreDameDeParis.jsx"]:::code
            click NDm "https://github.com/hnthap/car-ride/blob/main/src/models/NotreDameDeParis.jsx"
            Birch["Birch1.jsx"]:::code
            click Birch "https://github.com/hnthap/car-ride/blob/main/src/models/Birch1.jsx"
            Fancy["FancyHouse.jsx"]:::code
            click Fancy "https://github.com/hnthap/car-ride/blob/main/src/models/FancyHouse.jsx"
            Modern["ModernHouse.jsx"]:::code
            click Modern "https://github.com/hnthap/car-ride/blob/main/src/models/ModernHouse.jsx"
            Newground["Newground.jsx"]:::code
            click Newground "https://github.com/hnthap/car-ride/blob/main/src/models/Newground.jsx"
            Oggy["OggyHouse.jsx"]:::code
            click Oggy "https://github.com/hnthap/car-ride/blob/main/src/models/OggyHouse.jsx"
        end

        subgraph "Custom Hooks"
            HC["useControls.ts"]:::code
            click HC "https://github.com/hnthap/car-ride/blob/main/src/hooks/useControls.ts"
            HW["useWheels.ts"]:::code
            click HW "https://github.com/hnthap/car-ride/blob/main/src/hooks/useWheels.ts"
            HM["useMessages.ts"]:::code
            click HM "https://github.com/hnthap/car-ride/blob/main/src/hooks/useMessages.ts"
            HIDX["index.ts"]:::code
            click HIDX "https://github.com/hnthap/car-ride/blob/main/src/hooks/index.ts"
        end

        UTIL["utils.ts"]:::code
        click UTIL "https://github.com/hnthap/car-ride/blob/main/src/utils.ts"
        Style["src/index.css"]:::code
        click Style "https://github.com/hnthap/car-ride/blob/main/src/index.css"

        App --> MS
        App --> LC
        MS --> Car
        Car --> WCar
        WheelComp --> WA
        Car --> WheelComp
        MS --> ET
        ET --> ETm
        MS --> ADT
        ADT --> ADTm
        MS --> ND
        ND --> NDm
        MS --> GD
        MS --> Tree
        Tree --> Birch
        Tree --> Fancy
        Tree --> Modern
        Tree --> Newground
        Tree --> Oggy

        App --> HC
        App --> HW
        App --> HM
        HC --> HIDX
        HW --> HIDX
        HM --> HIDX
        App --> UTIL
        App --> Style
    end

    Browser -->|"renders"| App
    Browser -->|"keyboard input"| HC
    HC -->|"updates props"| MS

    WebGL["Three.js Renderer / WebGL Context"]:::runtime
    MS -->|"renders scene via"| WebGL

    subgraph "Static Asset Store"
        ModelAssets["public/ParisScene/*.glb"]:::assets
        click ModelAssets "https://github.com/hnthap/car-ride/tree/main/public/ParisScene/"
        CarAssets["public/CarAndWheels/*.glb"]:::assets
        click CarAssets "https://github.com/hnthap/car-ride/tree/main/public/CarAndWheels/"
        NDAsset["public/NotreDameDeParis/notre_dame_de_paris.glb"]:::assets
        click NDAsset "https://github.com/hnthap/car-ride/blob/main/public/NotreDameDeParis/notre_dame_de_paris.glb"
        Config["public/appconfig.json"]:::assets
        click Config "https://github.com/hnthap/car-ride/blob/main/public/appconfig.json"
    end

    WebGL -->|"loads assets"| ModelAssets
    WebGL --> CarAssets
    WebGL --> NDAsset
    WebGL --> Config

    classDef code fill:#ddeeff,stroke:#336699;
    classDef assets fill:#ddffdd,stroke:#33aa33;
    classDef runtime fill:#ffe0b3,stroke:#cc8400;
    classDef toolchain fill:#eeeeee,stroke:#888888;
```
