How cartesiancs/map3d works
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: App.tsx App · Space.tsx Space · main.tsx Main · SelectMap.tsx Select Map
Components 19
Bootstrap
App entry and root composition
- Index HTML · Vite HTML entry point
index.html - Main · Bootstraps React app
src/main.tsx
UI Shell
Screens, controls, and reusable presentation components
- App · Top-level application orchestrator
src/ui/App.tsx - Top Nav · Primary app navigation bar
src/components/nav/TopNav.tsx - Select Map · Map area selection screen
src/components/map/SelectMap.tsx - Processing · Loading and build progress view
src/components/map/Processing.tsx - Modal · Generic modal container
src/components/modal/Modal.tsx - Fullscreen Modal · Full-screen modal wrapper
src/components/FullscreenModal.tsx - Bottom Button · Primary bottom action button
src/components/button/BottomButton.tsx - Layout/Text · Row, Column, Title, Description building blocks
State
Shared client state stores
- Area Store · Selected map region state
src/state/areaStore.ts - Car Store · Vehicle or marker state
src/state/carStore.ts - Export Store · GLB export lifecycle state
src/state/exportStore.ts
3D Scene
React Three Fiber scene and objects
Support
Persistence and styling
- Cookie Utils · Cookie-backed session preferences
src/utils/cookie.ts - Colors · Shared color palette
src/theme/color.ts - Global CSS · App-wide base styles
src/index.css
Connections 20
- 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