# zhiwarsajadi/deep-branches architecture

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

- Interactive diagram: https://gitdiagram.com/zhiwarsajadi/deep-branches
- Repository: https://github.com/zhiwarsajadi/deep-branches

## Overview

Deep Branches is an educational interactive 3D timeline for exploring hominin lineages across more than seven million years. Users browse the branching timeline, select a species for its details and linked research, and can enter first-person mode to move along a species’ time bar and navigate its relatives. The map separates timeline data and lineage/time calculations from scene rendering and interface features. README documents skull photographs and reconstructions as optional card media; their runtime wiring is not shown in the excerpts, so that connection is omitted.

Main entry points: [`src/scene/Scene.jsx`](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/scene/Scene.jsx) (Scene orchestration), [`src/App.jsx`](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/App.jsx) (App orchestration), [`src/data/species.js`](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/data/species.js) (Species and clades), [`src/lib/lineage.js`](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/lib/lineage.js) (Lineage navigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["App orchestration<br/>[App.jsx]"]
  node_species_list["Species list<br/>[SpeciesList.jsx]"]
  node_fp_hud["First-person HUD<br/>[FpHud.jsx]"]
  node_about["About and credits<br/>[AboutContent.jsx]"]
  node_webgl_fallback["WebGL fallback<br/>[WebGLFallback.jsx]"]
end

subgraph group_rendering["3D timeline"]
  node_scene["Scene orchestration<br/>[Scene.jsx]"]
  node_branch["Lineage branches<br/>[Branch.jsx]"]
  node_species_column["Species time bars<br/>[SpeciesColumn.jsx]"]
  node_strata["Geological strata<br/>[Strata.jsx]"]
  node_now_plane["Present marker<br/>[NowPlane.jsx]"]
  node_camera["Camera controls<br/>[CameraRig.jsx]"]
end

subgraph group_domain["Lineage and data"]
  node_species_data[("Species and clades<br/>[species.js]")]
  node_sources_data[("Species citations<br/>[sources.js]")]
  node_pronunciations[("Pronunciations<br/>[pronunciations.js]")]
  node_lineage["Lineage navigation<br/>[lineage.js]"]
  node_time["Time scale<br/>[time.js]"]
  node_skull_media["Skull photographs<br/>[skulls.on.js]"]
  node_reconstruction_media["Reconstructions"]
end

subgraph group_support["Site information"]
  node_site_config["Site identity<br/>[site.js]"]
  node_feature_config["Illustration flag<br/>[config.js]"]
end

node_visitor(("Site visitor"))

node_visitor -->|"uses"| node_app
node_app -->|"renders"| node_scene
node_app -->|"renders"| node_fp_hud
node_app -->|"renders"| node_species_list
node_app -->|"opens dialog"| node_about
node_app -->|"uses navigation"| node_lineage
node_app -->|"reads"| node_species_data
node_species_list -->|"reads"| node_species_data
node_species_list -->|"formats dates"| node_time
node_fp_hud -->|"reads relatives"| node_lineage
node_fp_hud -->|"reads clades"| node_species_data
node_fp_hud -->|"formats position"| node_time
node_scene -->|"renders"| node_strata
node_scene -->|"renders"| node_branch
node_scene -->|"renders"| node_species_column
node_scene -->|"renders"| node_now_plane
node_scene -->|"renders"| node_camera
node_scene -->|"reads"| node_species_data
node_scene -->|"checks relationships"| node_lineage
node_branch -->|"reads"| node_species_data
node_branch -->|"maps dates"| node_time
node_branch -->|"uses relationships"| node_lineage
node_camera -->|"positions relatives"| node_lineage
node_camera -->|"maps time"| node_time
node_species_data -->|"attaches citations"| node_sources_data
node_about -->|"reads identity"| node_site_config
node_about -->|"checks media flag"| node_feature_config
node_webgl_fallback -->|"renders content"| node_about
node_webgl_fallback -->|"renders list"| node_species_list

click node_app "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/App.jsx"
click node_species_list "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/components/SpeciesList.jsx"
click node_fp_hud "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/components/FpHud.jsx"
click node_about "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/components/AboutContent.jsx"
click node_webgl_fallback "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/components/WebGLFallback.jsx"
click node_scene "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/scene/Scene.jsx"
click node_branch "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/scene/Branch.jsx"
click node_species_column "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/scene/SpeciesColumn.jsx"
click node_strata "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/scene/Strata.jsx"
click node_now_plane "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/scene/NowPlane.jsx"
click node_camera "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/scene/CameraRig.jsx"
click node_species_data "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/data/species.js"
click node_sources_data "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/data/sources.js"
click node_pronunciations "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/data/pronunciations.js"
click node_lineage "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/lib/lineage.js"
click node_time "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/lib/time.js"
click node_site_config "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/site.js"
click node_feature_config "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/config.js"
click node_skull_media "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/data/skulls.on.js"
click node_reconstruction_media "https://github.com/zhiwarsajadi/deep-branches/blob/main/src/data/reconstructions.on.js"

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_species_list,node_fp_hud,node_about,node_webgl_fallback toneBlue
class node_scene,node_branch,node_species_column,node_strata,node_now_plane,node_camera toneAmber
class node_species_data,node_sources_data,node_pronunciations,node_lineage,node_time,node_skull_media,node_reconstruction_media toneMint
class node_site_config,node_feature_config toneRose
class node_visitor toneIndigo
```

## Components

### User experience

- [App orchestration](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/App.jsx): `src/App.jsx`
- [Species list](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/components/SpeciesList.jsx): `src/components/SpeciesList.jsx`
- [First-person HUD](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/components/FpHud.jsx): `src/components/FpHud.jsx`
- [About and credits](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/components/AboutContent.jsx): `src/components/AboutContent.jsx`
- [WebGL fallback](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/components/WebGLFallback.jsx): `src/components/WebGLFallback.jsx`

### 3D timeline

- [Scene orchestration](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/scene/Scene.jsx): `src/scene/Scene.jsx`
- [Lineage branches](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/scene/Branch.jsx): `src/scene/Branch.jsx`
- [Species time bars](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/scene/SpeciesColumn.jsx): `src/scene/SpeciesColumn.jsx`
- [Geological strata](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/scene/Strata.jsx): `src/scene/Strata.jsx`
- [Present marker](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/scene/NowPlane.jsx): `src/scene/NowPlane.jsx`
- [Camera controls](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/scene/CameraRig.jsx): `src/scene/CameraRig.jsx`

### Lineage and data

- [Species and clades](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/data/species.js): `src/data/species.js`
- [Species citations](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/data/sources.js): `src/data/sources.js`
- [Pronunciations](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/data/pronunciations.js): `src/data/pronunciations.js`
- [Lineage navigation](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/lib/lineage.js): `src/lib/lineage.js`
- [Time scale](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/lib/time.js): `src/lib/time.js`
- [Skull photographs](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/data/skulls.on.js): `src/data/skulls.on.js`
- [Reconstructions](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/data/reconstructions.on.js): `src/data/reconstructions.on.js`

### Site information

- [Site identity](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/site.js): `src/site.js`
- [Illustration flag](https://github.com/zhiwarsajadi/deep-branches/blob/main/src/config.js): `src/config.js`

### Other components

- **Site visitor**

## Connections

- Site visitor → App orchestration: uses
- App orchestration → Scene orchestration: renders (evidence: `src/App.jsx`)
- App orchestration → First-person HUD: renders (evidence: `src/App.jsx`)
- App orchestration → Species list: renders (evidence: `src/App.jsx`)
- App orchestration → About and credits: opens dialog (evidence: `src/App.jsx`)
- App orchestration → Lineage navigation: uses navigation (evidence: `src/App.jsx`)
- App orchestration → Species and clades: reads (evidence: `src/App.jsx`)
- Species list → Species and clades: reads (evidence: `src/components/SpeciesList.jsx`)
- Species list → Time scale: formats dates (evidence: `src/components/SpeciesList.jsx`)
- First-person HUD → Lineage navigation: reads relatives (evidence: `src/components/FpHud.jsx`)
- First-person HUD → Species and clades: reads clades (evidence: `src/components/FpHud.jsx`)
- First-person HUD → Time scale: formats position (evidence: `src/components/FpHud.jsx`)
- Scene orchestration → Geological strata: renders (evidence: `src/scene/Scene.jsx`)
- Scene orchestration → Lineage branches: renders (evidence: `src/scene/Scene.jsx`)
- Scene orchestration → Species time bars: renders (evidence: `src/scene/Scene.jsx`)
- Scene orchestration → Present marker: renders (evidence: `src/scene/Scene.jsx`)
- Scene orchestration → Camera controls: renders (evidence: `src/scene/Scene.jsx`)
- Scene orchestration → Species and clades: reads (evidence: `src/scene/Scene.jsx`)
- Scene orchestration → Lineage navigation: checks relationships (evidence: `src/scene/Scene.jsx`)
- Lineage branches → Species and clades: reads (evidence: `src/scene/Branch.jsx`)
- Lineage branches → Time scale: maps dates (evidence: `src/scene/Branch.jsx`)
- Lineage branches → Lineage navigation: uses relationships (evidence: `src/scene/Branch.jsx`)
- Camera controls → Lineage navigation: positions relatives (evidence: `src/scene/CameraRig.jsx`)
- Camera controls → Time scale: maps time (evidence: `src/scene/CameraRig.jsx`)
- Species and clades → Species citations: attaches citations (evidence: `src/data/species.js`)
- About and credits → Site identity: reads identity (evidence: `src/components/AboutContent.jsx`)
- About and credits → Illustration flag: checks media flag (evidence: `src/components/AboutContent.jsx`)
- WebGL fallback → About and credits: renders content (evidence: `src/components/WebGLFallback.jsx`)
- WebGL fallback → Species list: renders list (evidence: `src/components/WebGLFallback.jsx`)