# garyqian/starmap architecture

> Architecture diagram of the GitHub repository garyqian/starmap, 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/garyqian/starmap
- Repository: https://github.com/garyqian/starmap

## Overview

Starmap turns a selected local repository into an interactive 3D dependency map: it reads Git-tracked files, parses and links their structure, clusters and lays out the result, then reveals it in the browser. Users can explore with search, selections, file reading and overlays; optional AI adds summaries, points of interest, tours and chat. The README documents the principal stages and capabilities. Some internal wiring is unsampled, so those connections are omitted rather than inferred.

Main entry points: [`src/pipeline/coordinator.worker.ts`](https://github.com/garyqian/starmap/blob/main/src/pipeline/coordinator.worker.ts) (Pipeline coordinator), [`src/model/store.ts`](https://github.com/garyqian/starmap/blob/main/src/model/store.ts) (Map data model), [`src/ingest`](https://github.com/garyqian/starmap/tree/main/src/ingest) (Manifest and parsing), [`src/analysis`](https://github.com/garyqian/starmap/tree/main/src/analysis) (Dependency analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Browser experience"]
  node_app["App shell<br/>[App.tsx]"]
  node_landing["Folder selection<br/>[Landing.tsx]"]
  node_renderer["3D renderer<br/>[renderer.ts]"]
end

subgraph group_pipeline["Repository pipeline"]
  node_ingest["Manifest and parsing"]
  node_git["Git reader"]
  node_languages["Language parsers"]
  node_analysis["Dependency analysis"]
  node_bridges["Cross-language links<br/>[index.ts]"]
  node_history["Git history"]
  node_coordinator["Pipeline coordinator"]
end

subgraph group_model["Map model and layout"]
  node_model[("Map data model<br/>[store.ts]")]
  node_physics["Tiered layout<br/>[engine.ts]"]
  node_persist[("Local persistence<br/>[index.ts]")]
end

subgraph group_explore["Exploration and state"]
  node_search["File search<br/>[searchIndex.ts]"]
  node_overlays["Map overlays<br/>[view.ts]"]
  node_sidebar["File reader<br/>[Reader.tsx]"]
  node_content["Repository content<br/>[index.ts]"]
end

subgraph group_ai["Optional AI"]
  node_ai["AI digest and client<br/>[index.ts]"]
  node_ai_server["AI API handlers<br/>[handlers.ts]"]
end

node_user(("Repository user"))
node_provider["Model provider"]

node_user -->|"chooses folder"| node_landing
node_landing -.->|"starts mapping"| node_coordinator
node_coordinator -->|"runs pipeline"| node_ingest
node_ingest -->|"reads manifest"| node_git
node_ingest -->|"parses files"| node_languages
node_languages -->|"extracts references"| node_analysis
node_analysis -.->|"adds bridge links"| node_bridges
node_analysis -->|"builds map"| node_model
node_coordinator -->|"streams patches"| node_model
node_coordinator -.->|"coordinates layout"| node_physics
node_physics -.->|"supplies positions"| node_renderer
node_coordinator -->|"saves locally"| node_persist
node_coordinator -->|"walks history"| node_history
node_model -->|"supports overlays"| node_overlays
node_model -->|"enables search"| node_search
node_user -->|"opens file"| node_sidebar
node_sidebar -.->|"reads content"| node_content
node_coordinator -.->|"prepares AI notes"| node_ai
node_ai -->|"sends requests"| node_ai_server
node_ai_server -->|"calls provider"| node_provider
node_ai_server -.->|"returns results"| node_ai

click node_app "https://github.com/garyqian/starmap/blob/main/src/app/App.tsx"
click node_landing "https://github.com/garyqian/starmap/blob/main/src/app/landing/Landing.tsx"
click node_renderer "https://github.com/garyqian/starmap/blob/main/src/render/core/renderer.ts"
click node_ingest "https://github.com/garyqian/starmap/tree/main/src/ingest"
click node_git "https://github.com/garyqian/starmap/tree/main/src/git"
click node_languages "https://github.com/garyqian/starmap/tree/main/src/lang"
click node_analysis "https://github.com/garyqian/starmap/tree/main/src/analysis"
click node_bridges "https://github.com/garyqian/starmap/blob/main/src/bridges/index.ts"
click node_history "https://github.com/garyqian/starmap/tree/main/src/history"
click node_coordinator "https://github.com/garyqian/starmap/blob/main/src/pipeline/coordinator.worker.ts"
click node_model "https://github.com/garyqian/starmap/blob/main/src/model/store.ts"
click node_physics "https://github.com/garyqian/starmap/blob/main/src/physics/engine.ts"
click node_persist "https://github.com/garyqian/starmap/blob/main/src/persist/index.ts"
click node_search "https://github.com/garyqian/starmap/blob/main/src/search/searchIndex.ts"
click node_overlays "https://github.com/garyqian/starmap/blob/main/src/overlays/view.ts"
click node_sidebar "https://github.com/garyqian/starmap/blob/main/src/app/sidebar/Reader.tsx"
click node_content "https://github.com/garyqian/starmap/blob/main/src/content/index.ts"
click node_ai "https://github.com/garyqian/starmap/blob/main/src/ai/index.ts"
click node_ai_server "https://github.com/garyqian/starmap/blob/main/src/ai/server/handlers.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_landing,node_renderer,node_user toneBlue
class node_ingest,node_git,node_languages,node_analysis,node_bridges,node_history,node_coordinator toneAmber
class node_model,node_physics,node_persist toneMint
class node_search,node_overlays,node_sidebar,node_content toneRose
class node_ai,node_ai_server,node_provider toneIndigo
```

## Components

### Browser experience

- [App shell](https://github.com/garyqian/starmap/blob/main/src/app/App.tsx): `src/app/App.tsx`
- [Folder selection](https://github.com/garyqian/starmap/blob/main/src/app/landing/Landing.tsx): `src/app/landing/Landing.tsx`
- [3D renderer](https://github.com/garyqian/starmap/blob/main/src/render/core/renderer.ts): `src/render/core/renderer.ts`

### Repository pipeline

- [Manifest and parsing](https://github.com/garyqian/starmap/tree/main/src/ingest): `src/ingest`
- [Git reader](https://github.com/garyqian/starmap/tree/main/src/git): `src/git`
- [Language parsers](https://github.com/garyqian/starmap/tree/main/src/lang): `src/lang`
- [Dependency analysis](https://github.com/garyqian/starmap/tree/main/src/analysis): `src/analysis`
- [Cross-language links](https://github.com/garyqian/starmap/blob/main/src/bridges/index.ts): `src/bridges/index.ts`
- [Git history](https://github.com/garyqian/starmap/tree/main/src/history): `src/history`
- [Pipeline coordinator](https://github.com/garyqian/starmap/blob/main/src/pipeline/coordinator.worker.ts): `src/pipeline/coordinator.worker.ts`

### Map model and layout

- [Map data model](https://github.com/garyqian/starmap/blob/main/src/model/store.ts): `src/model/store.ts`
- [Tiered layout](https://github.com/garyqian/starmap/blob/main/src/physics/engine.ts): `src/physics/engine.ts`
- [Local persistence](https://github.com/garyqian/starmap/blob/main/src/persist/index.ts): `src/persist/index.ts`

### Exploration and state

- [File search](https://github.com/garyqian/starmap/blob/main/src/search/searchIndex.ts): `src/search/searchIndex.ts`
- [Map overlays](https://github.com/garyqian/starmap/blob/main/src/overlays/view.ts): `src/overlays/view.ts`
- [File reader](https://github.com/garyqian/starmap/blob/main/src/app/sidebar/Reader.tsx): `src/app/sidebar/Reader.tsx`
- [Repository content](https://github.com/garyqian/starmap/blob/main/src/content/index.ts): `src/content/index.ts`

### Optional AI

- [AI digest and client](https://github.com/garyqian/starmap/blob/main/src/ai/index.ts): `src/ai/index.ts`
- [AI API handlers](https://github.com/garyqian/starmap/blob/main/src/ai/server/handlers.ts): `src/ai/server/handlers.ts`

### Other components

- **Repository user**
- **Model provider**

## Connections

- Repository user → Folder selection: chooses folder (evidence: `README.md`)
- Folder selection → Pipeline coordinator: starts mapping
- Pipeline coordinator → Manifest and parsing: runs pipeline (evidence: `README.md`)
- Manifest and parsing → Git reader: reads manifest (evidence: `README.md`)
- Manifest and parsing → Language parsers: parses files (evidence: `README.md`)
- Language parsers → Dependency analysis: extracts references (evidence: `README.md`)
- Dependency analysis → Cross-language links: adds bridge links (evidence: `src/analysis/index.ts`)
- Dependency analysis → Map data model: builds map (evidence: `README.md`)
- Pipeline coordinator → Map data model: streams patches (evidence: `src/pipeline/coordinator.worker.ts`)
- Pipeline coordinator → Tiered layout: coordinates layout
- Tiered layout → 3D renderer: supplies positions
- Pipeline coordinator → Local persistence: saves locally (evidence: `README.md`)
- Pipeline coordinator → Git history: walks history (evidence: `README.md`)
- Map data model → Map overlays: supports overlays (evidence: `README.md`)
- Map data model → File search: enables search (evidence: `README.md`)
- Repository user → File reader: opens file (evidence: `README.md`)
- File reader → Repository content: reads content
- Pipeline coordinator → AI digest and client: prepares AI notes
- AI digest and client → AI API handlers: sends requests (evidence: `README.md`)
- AI API handlers → Model provider: calls provider (evidence: `README.md`)
- AI API handlers → AI digest and client: returns results
