# cartesiancs/map3d architecture

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

- Interactive diagram: https://gitdiagram.com/cartesiancs/map3d
- Repository: https://github.com/cartesiancs/map3d

## Overview

1. **Project shape**
   - This repo is a **single-page front-end application** built with **React + TypeScript + Vite**.
   - There is no backend code in the tree; the app appears to fetch map data over HTTP and render everything client-side.

2. **Core purpose**
   - The app generates a **real-world 3D map** from **OpenStreetMap-derived data**.
   - Its main output is an interactive 3D scene, with a primary downstream capability to **export the generated map as GLB**.

3. **Application entry and shell**
   - `index.html`, `src/main.tsx`, and `src/ui/App.tsx` form the app bootstrap and top-level composition.
   - `App` is likely the central orchestrator that wires together map selection, loading states, the 3D canvas, and export controls.

4. **UI composition layer**
   - Reusable presentation components live under `src/components/`:
     - navigation: `TopNav`
     - modal system: `Modal`, `FullscreenModal`
     - controls: `BottomButton`
     - layout primitives: `Row`, `Column`
     - text primitives: `Title`, `Description`
     - map-flow widgets: `SelectMap`, `Processing`
   - This suggests a clean separation between **screen structure** and **domain logic**.

5. **Map selection and processing flow**
   - `SelectMap` likely handles choosing the geographic area or map target.
   - `Processing` likely represents the loading/build step while map data is being fetched and transformed.
   - Together they define the front-end workflow: **select area → fetch/process data → render 3D scene → export**.

6. **Global state boundary**
   - State is split into focused stores under `src/state/`:
     - `areaStore` for the selected map region / boundaries
     - `carStore` for vehicle-related state or marker position
     - `exportStore` for export lifecycle and GLB generation state
   - These stores likely act as the main bridge between UI controls and the 3D scene.

7. **3D rendering subsystem**
   - `src/three/Space.tsx` and `src/three/Car.tsx` are the main scene objects.
   - The README confirms the project uses **React Three Fiber**, so these files likely define the 3D world, buildings/roads, and a car or marker model inside the scene.
   - This is the main visualization boundary: domain state is converted into Three.js-compatible geometry and materials here.

8. **Data access layer**
   - `src/api/axios.ts` centralizes HTTP communication through Axios.
   - This is the repository’s network boundary for retrieving map-related data and possibly export-related requests or metadata.
   - The app’s architecture likely depends on this layer to keep fetch logic separate from rendering and UI state.

9. **Persistence and session behavior**
   - `src/utils/cookie.ts` indicates some user/session preference is persisted in cookies.
   - That could include selected map settings, recent state, or UI preferences, allowing the app to restore prior choices across visits.

10. **Styling and design system**
   - Theme colors live in `src/theme/color.ts`, with global styles in `src/index.css`.
   - These files provide the visual system for the application shell and controls, while the 3D scene styling remains in the scene code itself.

11. **Likely end-to-end data flow**
   - User selects a map area in the UI.
   - Area state is stored centrally.
   - The app requests map/building data through the Axios API layer.
   - The processing view shows progress while data is transformed into 3D structures.
   - `Space` and related scene components render the result.
   - `exportStore` drives GLB export of the generated scene.

12. **Architecture boundaries to capture in a diagram**
   - **UI shell**: navigation, modals, buttons, text, selection screens.
   - **State management**: area, car, export as shared application state.
   - **Network/data ingestion**: Axios-based map fetching.
   - **3D scene runtime**: React Three Fiber objects that render the map.
   - **Persistence/theme**: cookies and shared color/styling tokens.

13. **External dependencies that matter**
   - **React Three Fiber / Three.js** is essential because it defines the rendering model.
   - **OpenStreetMap data** is the external source of geographic/building information.
   - **GLB export** is a key output format and should be shown as a distinct output path in an architecture diagram.

14. **Overall structural summary**
   - This is a **client-side 3D map generator** with a layered design: presentation components on top, shared state in the middle, HTTP data access below that, and a Three.js-based render/export pipeline at the bottom.

Main entry points: [`src/ui/App.tsx`](https://github.com/cartesiancs/map3d/blob/main/src/ui/App.tsx) (App), [`src/three/Space.tsx`](https://github.com/cartesiancs/map3d/blob/main/src/three/Space.tsx) (Space), [`src/main.tsx`](https://github.com/cartesiancs/map3d/blob/main/src/main.tsx) (Main), [`src/components/map/SelectMap.tsx`](https://github.com/cartesiancs/map3d/blob/main/src/components/map/SelectMap.tsx) (Select Map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_index_html["Index HTML<br/>entry<br/>[index.html]"]
  node_main_tsx["Main<br/>entry<br/>[main.tsx]"]
end

subgraph group_ui["UI Shell"]
  node_app_tsx["App<br/>shell<br/>[App.tsx]"]
  node_topnav["Top Nav<br/>navigation<br/>[TopNav.tsx]"]
  node_selectmap["Select Map<br/>flow ui<br/>[SelectMap.tsx]"]
  node_processing["Processing<br/>flow ui<br/>[Processing.tsx]"]
  node_modal["Modal<br/>overlay<br/>[Modal.tsx]"]
  node_fullscreen_modal["Fullscreen Modal<br/>overlay"]
  node_bottom_button["Bottom Button<br/>control<br/>[BottomButton.tsx]"]
  node_layout_text["Layout/Text<br/>primitives"]
end

subgraph group_state["State"]
  node_area_store[("Area Store<br/>state store<br/>[areaStore.ts]")]
  node_car_store[("Car Store<br/>state store<br/>[carStore.ts]")]
  node_export_store[("Export Store<br/>state store<br/>[exportStore.ts]")]
end

subgraph group_data["Data Access"]
  node_axios_api["Axios API<br/>http client<br/>[axios.ts]"]
end

subgraph group_render["3D Scene"]
  node_space["Space<br/>3d scene<br/>[Space.tsx]"]
  node_car["Car<br/>3d object<br/>[Car.tsx]"]
end

subgraph group_support["Support"]
  node_cookie_util["Cookie Utils<br/>persistence<br/>[cookie.ts]"]
  node_colors["Colors<br/>theme tokens<br/>[color.ts]"]
  node_global_css["Global CSS<br/>styles<br/>[index.css]"]
end

node_index_html -->|"loads"| node_main_tsx
node_main_tsx -->|"renders"| node_app_tsx
node_app_tsx -->|"composes"| node_topnav
node_app_tsx -->|"shows"| node_selectmap
node_app_tsx -->|"shows"| node_processing
node_app_tsx -->|"uses"| node_modal
node_app_tsx -->|"uses"| node_fullscreen_modal
node_app_tsx -->|"uses"| node_bottom_button
node_app_tsx -->|"uses"| node_layout_text
node_selectmap -->|"updates"| node_area_store
node_processing -->|"requests"| node_axios_api
node_axios_api -->|"feeds"| node_space
node_area_store -->|"drives"| node_space
node_car_store -->|"drives"| node_car
node_app_tsx -->|"triggers"| node_export_store
node_export_store -->|"exports"| node_space
node_space -->|"contains"| node_car
node_app_tsx -->|"persists"| node_cookie_util
node_app_tsx -->|"themes"| node_colors
node_app_tsx -->|"styles"| node_global_css

click node_index_html "https://github.com/cartesiancs/map3d/blob/main/index.html"
click node_main_tsx "https://github.com/cartesiancs/map3d/blob/main/src/main.tsx"
click node_app_tsx "https://github.com/cartesiancs/map3d/blob/main/src/ui/App.tsx"
click node_topnav "https://github.com/cartesiancs/map3d/blob/main/src/components/nav/TopNav.tsx"
click node_selectmap "https://github.com/cartesiancs/map3d/blob/main/src/components/map/SelectMap.tsx"
click node_processing "https://github.com/cartesiancs/map3d/blob/main/src/components/map/Processing.tsx"
click node_modal "https://github.com/cartesiancs/map3d/blob/main/src/components/modal/Modal.tsx"
click node_fullscreen_modal "https://github.com/cartesiancs/map3d/blob/main/src/components/FullscreenModal.tsx"
click node_bottom_button "https://github.com/cartesiancs/map3d/blob/main/src/components/button/BottomButton.tsx"
click node_area_store "https://github.com/cartesiancs/map3d/blob/main/src/state/areaStore.ts"
click node_car_store "https://github.com/cartesiancs/map3d/blob/main/src/state/carStore.ts"
click node_export_store "https://github.com/cartesiancs/map3d/blob/main/src/state/exportStore.ts"
click node_axios_api "https://github.com/cartesiancs/map3d/blob/main/src/api/axios.ts"
click node_space "https://github.com/cartesiancs/map3d/blob/main/src/three/Space.tsx"
click node_car "https://github.com/cartesiancs/map3d/blob/main/src/three/Car.tsx"
click node_cookie_util "https://github.com/cartesiancs/map3d/blob/main/src/utils/cookie.ts"
click node_colors "https://github.com/cartesiancs/map3d/blob/main/src/theme/color.ts"
click node_global_css "https://github.com/cartesiancs/map3d/blob/main/src/index.css"

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_main_tsx toneBlue
class node_app_tsx,node_topnav,node_selectmap,node_processing,node_modal,node_fullscreen_modal,node_bottom_button,node_layout_text toneAmber
class node_area_store,node_car_store,node_export_store toneMint
class node_axios_api toneRose
class node_space,node_car toneIndigo
class node_cookie_util,node_colors,node_global_css toneTeal
```

## Components

### Bootstrap

App entry and root composition

- [Index HTML](https://github.com/cartesiancs/map3d/blob/main/index.html): entry · Vite HTML entry point · `index.html`
- [Main](https://github.com/cartesiancs/map3d/blob/main/src/main.tsx): entry · Bootstraps React app · `src/main.tsx`

### UI Shell

Screens, controls, and reusable presentation components

- [App](https://github.com/cartesiancs/map3d/blob/main/src/ui/App.tsx): shell · Top-level application orchestrator · `src/ui/App.tsx`
- [Top Nav](https://github.com/cartesiancs/map3d/blob/main/src/components/nav/TopNav.tsx): navigation · Primary app navigation bar · `src/components/nav/TopNav.tsx`
- [Select Map](https://github.com/cartesiancs/map3d/blob/main/src/components/map/SelectMap.tsx): flow ui · Map area selection screen · `src/components/map/SelectMap.tsx`
- [Processing](https://github.com/cartesiancs/map3d/blob/main/src/components/map/Processing.tsx): flow ui · Loading and build progress view · `src/components/map/Processing.tsx`
- [Modal](https://github.com/cartesiancs/map3d/blob/main/src/components/modal/Modal.tsx): overlay · Generic modal container · `src/components/modal/Modal.tsx`
- [Fullscreen Modal](https://github.com/cartesiancs/map3d/blob/main/src/components/FullscreenModal.tsx): overlay · Full-screen modal wrapper · `src/components/FullscreenModal.tsx`
- [Bottom Button](https://github.com/cartesiancs/map3d/blob/main/src/components/button/BottomButton.tsx): control · Primary bottom action button · `src/components/button/BottomButton.tsx`
- **Layout/Text**: primitives · Row, Column, Title, Description building blocks

### State

Shared client state stores

- [Area Store](https://github.com/cartesiancs/map3d/blob/main/src/state/areaStore.ts): state store · Selected map region state · `src/state/areaStore.ts`
- [Car Store](https://github.com/cartesiancs/map3d/blob/main/src/state/carStore.ts): state store · Vehicle or marker state · `src/state/carStore.ts`
- [Export Store](https://github.com/cartesiancs/map3d/blob/main/src/state/exportStore.ts): state store · GLB export lifecycle state · `src/state/exportStore.ts`

### Data Access

HTTP boundary for map data

- [Axios API](https://github.com/cartesiancs/map3d/blob/main/src/api/axios.ts): http client · Central HTTP access layer · `src/api/axios.ts`

### 3D Scene

React Three Fiber scene and objects

- [Space](https://github.com/cartesiancs/map3d/blob/main/src/three/Space.tsx): 3d scene · Main 3D map scene · `src/three/Space.tsx`
- [Car](https://github.com/cartesiancs/map3d/blob/main/src/three/Car.tsx): 3d object · Scene vehicle or marker object · `src/three/Car.tsx`

### Support

Persistence and styling

- [Cookie Utils](https://github.com/cartesiancs/map3d/blob/main/src/utils/cookie.ts): persistence · Cookie-backed session preferences · `src/utils/cookie.ts`
- [Colors](https://github.com/cartesiancs/map3d/blob/main/src/theme/color.ts): theme tokens · Shared color palette · `src/theme/color.ts`
- [Global CSS](https://github.com/cartesiancs/map3d/blob/main/src/index.css): styles · App-wide base styles · `src/index.css`

## Connections

- Index HTML → Main: loads · HTML mounts the React bundle
- Main → App: renders · Creates the application root
- App → Top Nav: composes · Shell includes navigation
- App → Select Map: shows · Initial area selection flow
- App → Processing: shows · Processing state during data build
- App → Modal: uses · Displays dialogs and overlays
- App → Fullscreen Modal: uses · Supports full-screen overlays
- App → Bottom Button: uses · Primary action control
- App → Layout/Text: uses · Shared layout and text primitives
- Select Map → Area Store: updates · Stores chosen map area
- Processing → Axios API: requests · Fetches map data for generation
- Axios API → Space: feeds · Data is transformed for the scene
- Area Store → Space: drives · Selected region shapes the scene
- Car Store → Car: drives · Vehicle state controls scene object
- App → Export Store: triggers · Export actions originate in the shell
- Export Store → Space: exports · GLB generation uses the 3D scene
- Space → Car: contains · Scene includes vehicle/marker object
- App → Cookie Utils: persists · Restores or stores user preferences
- App → Colors: themes · Applies shared visual tokens
- App → Global CSS: styles · Loads global application styles
