# nikatsg/project-dune architecture

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

- Interactive diagram: https://gitdiagram.com/nikatsg/project-dune
- Repository: https://github.com/nikatsg/project-dune

## Overview

This is a Dune-themed planetary exploration prototype: users switch among planets, inspect landmarks and lore through an archive overlay, and view a 3D globe with simulated wind and storms. The sampled code shows the frontend loading planet data from an Express API backed by Prisma/SQLite, while README describes procedural worlds and camera movement. Archive categories are documented by the API routes and UI, but several implementations were not sampled; edges are limited to visible calls, imports, and documented capabilities.

Main entry points: [`src/app/App.tsx`](https://github.com/nikatsg/project-dune/blob/main/src/app/App.tsx) (Scene Coordinator), [`src/components/environment/WindSystem/WindSimulation.tsx`](https://github.com/nikatsg/project-dune/blob/main/src/components/environment/WindSystem/WindSimulation.tsx) (Wind Simulation View), [`src/components/Planet.tsx`](https://github.com/nikatsg/project-dune/blob/main/src/components/Planet.tsx) (Planet Globe), [`src/components/environment/StormSystem/StormVisualizer.tsx`](https://github.com/nikatsg/project-dune/blob/main/src/components/environment/StormSystem/StormVisualizer.tsx) (Storm Visualizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Exploration UI"]
  node_app["Scene Coordinator<br/>[App.tsx]"]
  node_overlay["Archive Overlay<br/>[MasterOverlay.tsx]"]
  node_archive["Lore Archive"]
  node_species["Species Details<br/>[SpeciesPanel.tsx]"]
end

subgraph group_rendering["Planet Rendering"]
  node_planet["Planet Globe<br/>[Planet.tsx]"]
  node_atmosphere["Planet Atmosphere<br/>[atmosphere_v3.tsx]"]
  node_landmarks["Landmark Markers<br/>[landmarkMarker.tsx]"]
  node_coordinates["Coordinate Mapping<br/>[coordinates.ts]"]
end

subgraph group_environment["Atmospheric Simulation"]
  node_windview["Wind Simulation View<br/>[WindSimulation.tsx]"]
  node_wind["Wind Engine<br/>[WindEngine.ts]"]
  node_windconfig["Wind Configuration"]
  node_shaders["Atmosphere Shaders<br/>[shaders.ts]"]
  node_stormview["Storm Visualizer"]
  node_storm["Storm Engine<br/>[StormEngine.ts]"]
end

subgraph group_knowledge["Lore and API"]
  node_planethook["Planet Data Hook<br/>[hookPlanets.ts]"]
  node_termhook["Glossary Hook<br/>[hookTerms.ts]"]
  node_types["Lore Data Types<br/>[blueprint.ts]"]
  node_api["Lore API<br/>[index.ts]"]
  node_planetroute["Planet Endpoints<br/>[planets.ts]"]
  node_lore_routes["Lore Endpoints"]
  node_db[("SQLite Database<br/>[db.ts]")]
end

node_user(("Explorer"))

node_user -->|"explores"| node_app
node_app -->|"loads planets"| node_planethook
node_app -->|"loads terms"| node_termhook
node_app -->|"renders"| node_overlay
node_app -->|"renders"| node_planet
node_app -->|"renders"| node_windview
node_overlay -->|"renders"| node_archive
node_archive -->|"renders"| node_species
node_planet -->|"uses"| node_atmosphere
node_planet -->|"renders"| node_landmarks
node_landmarks -->|"maps positions"| node_coordinates
node_app -->|"targets camera"| node_coordinates
node_windview -->|"uses"| node_wind
node_windview -->|"renders"| node_stormview
node_windview -->|"uses"| node_shaders
node_wind -->|"reads config"| node_windconfig
node_stormview -->|"uses"| node_storm
node_stormview -->|"uses"| node_shaders
node_storm -->|"samples wind"| node_wind
node_planethook -->|"fetches planets"| node_planetroute
node_termhook -.->|"fetches terms"| node_lore_routes
node_api -->|"mounts routes"| node_planetroute
node_api -->|"mounts routes"| node_lore_routes
node_planetroute -->|"queries"| node_db
node_lore_routes -.->|"queries"| node_db

click node_app "https://github.com/nikatsg/project-dune/blob/main/src/app/App.tsx"
click node_overlay "https://github.com/nikatsg/project-dune/blob/main/src/components/uiShit/MasterOverlay.tsx"
click node_archive "https://github.com/nikatsg/project-dune/blob/main/src/components/uiShit/databaseArchive.tsx"
click node_species "https://github.com/nikatsg/project-dune/blob/main/src/components/uiShit/SpeciesPanel.tsx"
click node_planet "https://github.com/nikatsg/project-dune/blob/main/src/components/Planet.tsx"
click node_atmosphere "https://github.com/nikatsg/project-dune/blob/main/src/components/atmosphere_v3.tsx"
click node_landmarks "https://github.com/nikatsg/project-dune/blob/main/src/components/landmarkMarker.tsx"
click node_coordinates "https://github.com/nikatsg/project-dune/blob/main/src/lib/coordinates.ts"
click node_windview "https://github.com/nikatsg/project-dune/blob/main/src/components/environment/WindSystem/WindSimulation.tsx"
click node_wind "https://github.com/nikatsg/project-dune/blob/main/src/components/environment/WindSystem/WindEngine.ts"
click node_windconfig "https://github.com/nikatsg/project-dune/blob/main/src/components/environment/WindSystem/EnvironmentConfig.ts"
click node_shaders "https://github.com/nikatsg/project-dune/blob/main/src/components/environment/WindSystem/shaders.ts"
click node_stormview "https://github.com/nikatsg/project-dune/blob/main/src/components/environment/StormSystem/StormVisualizer.tsx"
click node_storm "https://github.com/nikatsg/project-dune/blob/main/src/components/environment/StormSystem/StormEngine.ts"
click node_planethook "https://github.com/nikatsg/project-dune/blob/main/src/hooks/hookPlanets.ts"
click node_termhook "https://github.com/nikatsg/project-dune/blob/main/src/hooks/hookTerms.ts"
click node_types "https://github.com/nikatsg/project-dune/blob/main/src/lib/blueprint.ts"
click node_api "https://github.com/nikatsg/project-dune/blob/main/backend/index.ts"
click node_planetroute "https://github.com/nikatsg/project-dune/blob/main/backend/routes/planets.ts"
click node_lore_routes "https://github.com/nikatsg/project-dune/tree/main/backend/routes"
click node_db "https://github.com/nikatsg/project-dune/blob/main/backend/db.ts"

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_overlay,node_archive,node_species toneBlue
class node_planet,node_atmosphere,node_landmarks,node_coordinates toneAmber
class node_windview,node_wind,node_windconfig,node_shaders,node_stormview,node_storm toneMint
class node_planethook,node_termhook,node_types,node_api,node_planetroute,node_lore_routes,node_db toneRose
class node_user toneIndigo
```

## Components

### Exploration UI

- [Scene Coordinator](https://github.com/nikatsg/project-dune/blob/main/src/app/App.tsx): `src/app/App.tsx`
- [Archive Overlay](https://github.com/nikatsg/project-dune/blob/main/src/components/uiShit/MasterOverlay.tsx): `src/components/uiShit/MasterOverlay.tsx`
- [Lore Archive](https://github.com/nikatsg/project-dune/blob/main/src/components/uiShit/databaseArchive.tsx): `src/components/uiShit/databaseArchive.tsx`
- [Species Details](https://github.com/nikatsg/project-dune/blob/main/src/components/uiShit/SpeciesPanel.tsx): `src/components/uiShit/SpeciesPanel.tsx`

### Planet Rendering

- [Planet Globe](https://github.com/nikatsg/project-dune/blob/main/src/components/Planet.tsx): `src/components/Planet.tsx`
- [Planet Atmosphere](https://github.com/nikatsg/project-dune/blob/main/src/components/atmosphere_v3.tsx): `src/components/atmosphere_v3.tsx`
- [Landmark Markers](https://github.com/nikatsg/project-dune/blob/main/src/components/landmarkMarker.tsx): `src/components/landmarkMarker.tsx`
- [Coordinate Mapping](https://github.com/nikatsg/project-dune/blob/main/src/lib/coordinates.ts): `src/lib/coordinates.ts`

### Atmospheric Simulation

- [Wind Simulation View](https://github.com/nikatsg/project-dune/blob/main/src/components/environment/WindSystem/WindSimulation.tsx): `src/components/environment/WindSystem/WindSimulation.tsx`
- [Wind Engine](https://github.com/nikatsg/project-dune/blob/main/src/components/environment/WindSystem/WindEngine.ts): `src/components/environment/WindSystem/WindEngine.ts`
- [Wind Configuration](https://github.com/nikatsg/project-dune/blob/main/src/components/environment/WindSystem/EnvironmentConfig.ts): `src/components/environment/WindSystem/EnvironmentConfig.ts`
- [Atmosphere Shaders](https://github.com/nikatsg/project-dune/blob/main/src/components/environment/WindSystem/shaders.ts): `src/components/environment/WindSystem/shaders.ts`
- [Storm Visualizer](https://github.com/nikatsg/project-dune/blob/main/src/components/environment/StormSystem/StormVisualizer.tsx): `src/components/environment/StormSystem/StormVisualizer.tsx`
- [Storm Engine](https://github.com/nikatsg/project-dune/blob/main/src/components/environment/StormSystem/StormEngine.ts): `src/components/environment/StormSystem/StormEngine.ts`

### Lore and API

- [Planet Data Hook](https://github.com/nikatsg/project-dune/blob/main/src/hooks/hookPlanets.ts): `src/hooks/hookPlanets.ts`
- [Glossary Hook](https://github.com/nikatsg/project-dune/blob/main/src/hooks/hookTerms.ts): `src/hooks/hookTerms.ts`
- [Lore Data Types](https://github.com/nikatsg/project-dune/blob/main/src/lib/blueprint.ts): `src/lib/blueprint.ts`
- [Lore API](https://github.com/nikatsg/project-dune/blob/main/backend/index.ts): `backend/index.ts`
- [Planet Endpoints](https://github.com/nikatsg/project-dune/blob/main/backend/routes/planets.ts): `backend/routes/planets.ts`
- [Lore Endpoints](https://github.com/nikatsg/project-dune/tree/main/backend/routes): `backend/routes`
- [SQLite Database](https://github.com/nikatsg/project-dune/blob/main/backend/db.ts): `backend/db.ts`

### Other components

- **Explorer**

## Connections

- Explorer → Scene Coordinator: explores
- Scene Coordinator → Planet Data Hook: loads planets (evidence: `src/app/App.tsx`)
- Scene Coordinator → Glossary Hook: loads terms (evidence: `src/app/App.tsx`)
- Scene Coordinator → Archive Overlay: renders (evidence: `src/app/App.tsx`)
- Scene Coordinator → Planet Globe: renders (evidence: `src/app/App.tsx`)
- Scene Coordinator → Wind Simulation View: renders (evidence: `src/app/App.tsx`)
- Archive Overlay → Lore Archive: renders (evidence: `src/components/uiShit/MasterOverlay.tsx`)
- Lore Archive → Species Details: renders (evidence: `src/components/uiShit/databaseArchive.tsx`)
- Planet Globe → Planet Atmosphere: uses (evidence: `src/components/Planet.tsx`)
- Planet Globe → Landmark Markers: renders (evidence: `src/components/Planet.tsx`)
- Landmark Markers → Coordinate Mapping: maps positions (evidence: `src/components/landmarkMarker.tsx`)
- Scene Coordinator → Coordinate Mapping: targets camera (evidence: `src/app/App.tsx`)
- Wind Simulation View → Wind Engine: uses (evidence: `src/components/environment/WindSystem/WindSimulation.tsx`)
- Wind Simulation View → Storm Visualizer: renders (evidence: `src/components/environment/WindSystem/WindSimulation.tsx`)
- Wind Simulation View → Atmosphere Shaders: uses (evidence: `src/components/environment/WindSystem/WindSimulation.tsx`)
- Wind Engine → Wind Configuration: reads config (evidence: `src/components/environment/WindSystem/WindEngine.ts`)
- Storm Visualizer → Storm Engine: uses (evidence: `src/components/environment/StormSystem/StormVisualizer.tsx`)
- Storm Visualizer → Atmosphere Shaders: uses (evidence: `src/components/environment/StormSystem/StormVisualizer.tsx`)
- Storm Engine → Wind Engine: samples wind (evidence: `src/components/environment/StormSystem/StormEngine.ts`)
- Planet Data Hook → Planet Endpoints: fetches planets (evidence: `src/hooks/hookPlanets.ts`)
- Glossary Hook → Lore Endpoints: fetches terms
- Lore API → Planet Endpoints: mounts routes (evidence: `backend/index.ts`)
- Lore API → Lore Endpoints: mounts routes (evidence: `backend/index.ts`)
- Planet Endpoints → SQLite Database: queries (evidence: `backend/routes/planets.ts`)
- Lore Endpoints → SQLite Database: queries (evidence: `backend/routes/planets.ts`)
