# sidevworks/rare-atlas architecture

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

- Interactive diagram: https://gitdiagram.com/sidevworks/rare-atlas
- Repository: https://github.com/sidevworks/rare-atlas

## Overview

Rare Atlas turns a visitor’s typed or spoken question into source-backed graph lookups, then presents related diseases, evidence, patient-group resources, studies, and possible next steps through a 3D atlas and desk. The documented data path builds wide open-data links and a hand-checked deep layer, then serves graph lookups and short-lived voice sessions. The README documents several capabilities whose route implementations were not sampled; those relationships are cited to the README rather than inferred from filenames.

Main entry points: [`loader/build.js`](https://github.com/sidevworks/rare-atlas/blob/main/loader/build.js) (Wide-layer builder), [`api`](https://github.com/sidevworks/rare-atlas/tree/main/api) (Lookup routes), [`src/retrieval.js`](https://github.com/sidevworks/rare-atlas/blob/main/src/retrieval.js) (Retrieval tools), [`src/main.js`](https://github.com/sidevworks/rare-atlas/blob/main/src/main.js) (Atlas boot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Atlas experience"]
  node_app["Atlas boot<br/>[main.js]"]
  node_ui["Search and desk<br/>[index.js]"]
  node_searchbox["Typed search<br/>[search.js]"]
  node_retrieval["Retrieval tools<br/>[retrieval.js]"]
  node_voice["Voice agent<br/>[index.js]"]
  node_bus["Event bus<br/>[bus.js]"]
  node_world["3D atlas<br/>[index.js]"]
  node_api_client["Browser API<br/>[api.js]"]
end

subgraph group_server["Lookup service"]
  node_api_routes["Lookup routes"]
  node_search["Graph search<br/>[search.js]"]
  node_graph["Graph access<br/>[graph.js]"]
  node_realtime["Voice session"]
end

subgraph group_data["Graph data"]
  node_store[("Graph storage<br/>[store.js]")]
  node_schema["Graph schema<br/>[schema.js]"]
end

subgraph group_loader["Data preparation"]
  node_widebuild["Wide-layer builder<br/>[build.js]"]
  node_wideedges["Sourced links<br/>[edges.js]"]
  node_reconcile["Name reconciliation<br/>[reconcile.js]"]
  node_deepbuild["Deep-layer curation<br/>[run.js]"]
  node_upload["Graph upload<br/>[upload.js]"]
end

subgraph group_mondo["Mondo floor"]
  node_mondofloor["Mondo mosaic<br/>[mondo-floor.js]"]
  node_mondobuild["Mondo floor build<br/>[build.js]"]
end

node_visitor(("Visitor"))
node_openai["OpenAI Realtime"]
node_sources["Open data sources"]

node_visitor -->|"asks"| node_searchbox
node_visitor -->|"speaks to"| node_voice
node_app -->|"fetches map"| node_api_client
node_app -->|"creates UI"| node_ui
node_app -->|"creates world"| node_world
node_searchbox -->|"runs lookup"| node_retrieval
node_voice -->|"runs tool"| node_retrieval
node_retrieval -->|"emits results"| node_bus
node_ui -->|"listens"| node_bus
node_retrieval -.->|"requests lookups"| node_api_client
node_api_client -->|"calls endpoints"| node_api_routes
node_api_routes -->|"searches graph"| node_search
node_search -->|"reads index"| node_store
node_api_routes -->|"checks claims"| node_graph
node_graph -.->|"reads graph"| node_store
node_api_routes -->|"mints sessions"| node_realtime
node_realtime -->|"mints secret"| node_openai
node_voice -->|"connects directly"| node_openai
node_widebuild -->|"reads files"| node_sources
node_widebuild -->|"reconciles names"| node_reconcile
node_widebuild -->|"builds links"| node_wideedges
node_wideedges -->|"creates typed edges"| node_schema
node_deepbuild -->|"adds curated data"| node_sources
node_widebuild -->|"writes build"| node_upload
node_deepbuild -->|"uploads layer"| node_upload
node_upload -->|"writes graph"| node_store
node_mondobuild -->|"produces floor data"| node_mondofloor

click node_app "https://github.com/sidevworks/rare-atlas/blob/main/src/main.js"
click node_ui "https://github.com/sidevworks/rare-atlas/blob/main/src/ui/index.js"
click node_searchbox "https://github.com/sidevworks/rare-atlas/blob/main/src/ui/search.js"
click node_retrieval "https://github.com/sidevworks/rare-atlas/blob/main/src/retrieval.js"
click node_voice "https://github.com/sidevworks/rare-atlas/blob/main/src/voice/index.js"
click node_bus "https://github.com/sidevworks/rare-atlas/blob/main/src/bus.js"
click node_world "https://github.com/sidevworks/rare-atlas/blob/main/src/world/index.js"
click node_mondofloor "https://github.com/sidevworks/rare-atlas/blob/main/src/world/mondo-floor.js"
click node_api_client "https://github.com/sidevworks/rare-atlas/blob/main/src/api.js"
click node_api_routes "https://github.com/sidevworks/rare-atlas/tree/main/api"
click node_search "https://github.com/sidevworks/rare-atlas/blob/main/api/_lib/search.js"
click node_graph "https://github.com/sidevworks/rare-atlas/blob/main/api/_lib/graph.js"
click node_store "https://github.com/sidevworks/rare-atlas/blob/main/api/_lib/store.js"
click node_realtime "https://github.com/sidevworks/rare-atlas/blob/main/api/realtime-session.js"
click node_widebuild "https://github.com/sidevworks/rare-atlas/blob/main/loader/build.js"
click node_wideedges "https://github.com/sidevworks/rare-atlas/blob/main/loader/wide/edges.js"
click node_reconcile "https://github.com/sidevworks/rare-atlas/blob/main/loader/wide/reconcile.js"
click node_deepbuild "https://github.com/sidevworks/rare-atlas/blob/main/loader/deep/run.js"
click node_upload "https://github.com/sidevworks/rare-atlas/blob/main/loader/upload.js"
click node_mondobuild "https://github.com/sidevworks/rare-atlas/blob/main/loader/mondo/build.js"
click node_schema "https://github.com/sidevworks/rare-atlas/blob/main/shared/schema.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_ui,node_searchbox,node_retrieval,node_voice,node_bus,node_world,node_api_client toneBlue
class node_api_routes,node_search,node_graph,node_realtime toneAmber
class node_store,node_schema toneMint
class node_widebuild,node_wideedges,node_reconcile,node_deepbuild,node_upload toneRose
class node_mondofloor,node_mondobuild,node_visitor,node_openai,node_sources toneIndigo
```

## Components

### Atlas experience

- [Atlas boot](https://github.com/sidevworks/rare-atlas/blob/main/src/main.js): `src/main.js`
- [Search and desk](https://github.com/sidevworks/rare-atlas/blob/main/src/ui/index.js): `src/ui/index.js`
- [Typed search](https://github.com/sidevworks/rare-atlas/blob/main/src/ui/search.js): `src/ui/search.js`
- [Retrieval tools](https://github.com/sidevworks/rare-atlas/blob/main/src/retrieval.js): `src/retrieval.js`
- [Voice agent](https://github.com/sidevworks/rare-atlas/blob/main/src/voice/index.js): `src/voice/index.js`
- [Event bus](https://github.com/sidevworks/rare-atlas/blob/main/src/bus.js): `src/bus.js`
- [3D atlas](https://github.com/sidevworks/rare-atlas/blob/main/src/world/index.js): `src/world/index.js`
- [Browser API](https://github.com/sidevworks/rare-atlas/blob/main/src/api.js): `src/api.js`

### Lookup service

- [Lookup routes](https://github.com/sidevworks/rare-atlas/tree/main/api): `api`
- [Graph search](https://github.com/sidevworks/rare-atlas/blob/main/api/_lib/search.js): `api/_lib/search.js`
- [Graph access](https://github.com/sidevworks/rare-atlas/blob/main/api/_lib/graph.js): `api/_lib/graph.js`
- [Voice session](https://github.com/sidevworks/rare-atlas/blob/main/api/realtime-session.js): `api/realtime-session.js`

### Graph data

- [Graph storage](https://github.com/sidevworks/rare-atlas/blob/main/api/_lib/store.js): `api/_lib/store.js`
- [Graph schema](https://github.com/sidevworks/rare-atlas/blob/main/shared/schema.js): `shared/schema.js`

### Data preparation

- [Wide-layer builder](https://github.com/sidevworks/rare-atlas/blob/main/loader/build.js): `loader/build.js`
- [Sourced links](https://github.com/sidevworks/rare-atlas/blob/main/loader/wide/edges.js): `loader/wide/edges.js`
- [Name reconciliation](https://github.com/sidevworks/rare-atlas/blob/main/loader/wide/reconcile.js): `loader/wide/reconcile.js`
- [Deep-layer curation](https://github.com/sidevworks/rare-atlas/blob/main/loader/deep/run.js): `loader/deep/run.js`
- [Graph upload](https://github.com/sidevworks/rare-atlas/blob/main/loader/upload.js): `loader/upload.js`

### Mondo floor

- [Mondo mosaic](https://github.com/sidevworks/rare-atlas/blob/main/src/world/mondo-floor.js): `src/world/mondo-floor.js`
- [Mondo floor build](https://github.com/sidevworks/rare-atlas/blob/main/loader/mondo/build.js): `loader/mondo/build.js`

### Other components

- **Visitor**
- **OpenAI Realtime**
- **Open data sources**

## Connections

- Visitor → Typed search: asks
- Visitor → Voice agent: speaks to
- Atlas boot → Browser API: fetches map (evidence: `src/main.js`)
- Atlas boot → Search and desk: creates UI (evidence: `src/main.js`)
- Atlas boot → 3D atlas: creates world (evidence: `src/main.js`)
- Typed search → Retrieval tools: runs lookup (evidence: `src/ui/search.js`)
- Voice agent → Retrieval tools: runs tool (evidence: `src/voice/index.js`)
- Retrieval tools → Event bus: emits results (evidence: `src/retrieval.js`)
- Search and desk → Event bus: listens (evidence: `src/ui/index.js`)
- Retrieval tools → Browser API: requests lookups (evidence: `src/retrieval.js`)
- Browser API → Lookup routes: calls endpoints
- Lookup routes → Graph search: searches graph (evidence: `api/search.js`)
- Graph search → Graph storage: reads index (evidence: `api/_lib/search.js`)
- Lookup routes → Graph access: checks claims (evidence: `api/_lib/graph.js`)
- Graph access → Graph storage: reads graph
- Lookup routes → Voice session: mints sessions (evidence: `api/realtime-session.js`)
- Voice session → OpenAI Realtime: mints secret (evidence: `api/realtime-session.js`)
- Voice agent → OpenAI Realtime: connects directly
- Wide-layer builder → Open data sources: reads files
- Wide-layer builder → Name reconciliation: reconciles names (evidence: `loader/build.js`)
- Wide-layer builder → Sourced links: builds links (evidence: `loader/build.js`)
- Sourced links → Graph schema: creates typed edges (evidence: `loader/wide/edges.js`)
- Deep-layer curation → Open data sources: adds curated data
- Wide-layer builder → Graph upload: writes build
- Deep-layer curation → Graph upload: uploads layer
- Graph upload → Graph storage: writes graph
- Mondo floor build → Mondo mosaic: produces floor data
