# gamakon/ultradim architecture

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

- Interactive diagram: https://gitdiagram.com/gamakon/ultradim
- Repository: https://github.com/gamakon/ultradim

## Overview

UltraDim is an analytical vector store; its principal workflow is to ingest vectors, build searchable structures, and run analytical queries such as exact nearest ranking, mapping, clustering, and classification. The repository exposes the engine through an MCP tool server and includes a substantial BloomMap product branch that turns hierarchical clusterings into data for poster and interactive visualizations. The engine implementation itself is not present in the sampled tree, so its internal layers and most MCP-to-engine calls cannot be mapped here; those links are documented at the product level.

Main entry points: [`BloomMap/process/bloommap_build.py`](https://github.com/gamakon/ultradim/blob/main/BloomMap/process/bloommap_build.py) (Shared map builder), [`BloomMap/renderer/visualization.js`](https://github.com/gamakon/ultradim/blob/main/BloomMap/renderer/visualization.js) (Poster renderer), [`mcp/ultradim_mcp_server_v0_5_0.py`](https://github.com/gamakon/ultradim/blob/main/mcp/ultradim_mcp_server_v0_5_0.py) (MCP tools), [`BloomMap/process/hseg_chembl.py`](https://github.com/gamakon/ultradim/blob/main/BloomMap/process/hseg_chembl.py) (ChEMBL segmentation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP interface"]
  node_mcpserver["MCP tools"]
end

subgraph group_engine["UltraDim engine"]
  node_enginecore["Vector analytics"]
end

subgraph group_bloom["BloomMap production"]
  node_segchem["ChEMBL segmentation<br/>[hseg_chembl.py]"]
  node_segmovies["Movie segmentation"]
  node_jsonchem["ChEMBL map data"]
  node_jsonmovies["Movie map data"]
  node_builder["Shared map builder<br/>[bloommap_build.py]"]
  node_galaxydata["Galaxy enrichment<br/>[build_galaxy.py]"]
end

subgraph group_render["BloomMap rendering"]
  node_poster["Poster renderer<br/>[visualization.js]"]
  node_profiles["Paper profiles<br/>[paper_profiles.js]"]
  node_renderharness["SVG export<br/>[render.mjs]"]
  node_sunburst["Sunburst export"]
end

node_assistant(("AI assistant"))
node_user(("Analyst"))

node_assistant -->|"invokes tools"| node_mcpserver
node_mcpserver -->|"wraps engine"| node_enginecore
node_user -.->|"runs analyses"| node_enginecore
node_enginecore -.->|"clusters vectors"| node_segchem
node_enginecore -.->|"clusters vectors"| node_segmovies
node_segchem -.->|"writes tree inputs"| node_jsonchem
node_segmovies -.->|"writes tree inputs"| node_jsonmovies
node_jsonchem -->|"uses shared logic"| node_builder
node_jsonmovies -->|"uses shared logic"| node_builder
node_builder -.->|"supplies map data"| node_poster
node_builder -->|"supplies tree data"| node_galaxydata
node_poster -->|"uses layout profiles"| node_profiles
node_renderharness -->|"loads HTML view"| node_poster
node_galaxydata -.->|"supplies hierarchy"| node_sunburst

click node_mcpserver "https://github.com/gamakon/ultradim/blob/main/mcp/ultradim_mcp_server_v0_5_0.py"
click node_segchem "https://github.com/gamakon/ultradim/blob/main/BloomMap/process/hseg_chembl.py"
click node_segmovies "https://github.com/gamakon/ultradim/blob/main/BloomMap/process/hseg_ml20m_movies.py"
click node_jsonchem "https://github.com/gamakon/ultradim/blob/main/BloomMap/process/build_bloommap_json_chembl.py"
click node_jsonmovies "https://github.com/gamakon/ultradim/blob/main/BloomMap/process/build_bloommap_json_ml20m.py"
click node_builder "https://github.com/gamakon/ultradim/blob/main/BloomMap/process/bloommap_build.py"
click node_galaxydata "https://github.com/gamakon/ultradim/blob/main/BloomMap/galaxy/build_galaxy.py"
click node_poster "https://github.com/gamakon/ultradim/blob/main/BloomMap/renderer/visualization.js"
click node_profiles "https://github.com/gamakon/ultradim/blob/main/BloomMap/renderer/config/paper_profiles.js"
click node_renderharness "https://github.com/gamakon/ultradim/blob/main/BloomMap/renderer/render.mjs"
click node_sunburst "https://github.com/gamakon/ultradim/blob/main/BloomMap/galaxy/build_sunburst_svg.py"

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_mcpserver toneBlue
class node_enginecore toneAmber
class node_segchem,node_segmovies,node_jsonchem,node_jsonmovies,node_builder,node_galaxydata toneMint
class node_poster,node_profiles,node_renderharness,node_sunburst toneRose
class node_assistant,node_user toneIndigo
```

## Components

### MCP interface

- [MCP tools](https://github.com/gamakon/ultradim/blob/main/mcp/ultradim_mcp_server_v0_5_0.py): `mcp/ultradim_mcp_server_v0_5_0.py`

### UltraDim engine

- **Vector analytics**

### BloomMap production

- [ChEMBL segmentation](https://github.com/gamakon/ultradim/blob/main/BloomMap/process/hseg_chembl.py): `BloomMap/process/hseg_chembl.py`
- [Movie segmentation](https://github.com/gamakon/ultradim/blob/main/BloomMap/process/hseg_ml20m_movies.py): `BloomMap/process/hseg_ml20m_movies.py`
- [ChEMBL map data](https://github.com/gamakon/ultradim/blob/main/BloomMap/process/build_bloommap_json_chembl.py): `BloomMap/process/build_bloommap_json_chembl.py`
- [Movie map data](https://github.com/gamakon/ultradim/blob/main/BloomMap/process/build_bloommap_json_ml20m.py): `BloomMap/process/build_bloommap_json_ml20m.py`
- [Shared map builder](https://github.com/gamakon/ultradim/blob/main/BloomMap/process/bloommap_build.py): `BloomMap/process/bloommap_build.py`
- [Galaxy enrichment](https://github.com/gamakon/ultradim/blob/main/BloomMap/galaxy/build_galaxy.py): `BloomMap/galaxy/build_galaxy.py`

### BloomMap rendering

- [Poster renderer](https://github.com/gamakon/ultradim/blob/main/BloomMap/renderer/visualization.js): `BloomMap/renderer/visualization.js`
- [Paper profiles](https://github.com/gamakon/ultradim/blob/main/BloomMap/renderer/config/paper_profiles.js): `BloomMap/renderer/config/paper_profiles.js`
- [SVG export](https://github.com/gamakon/ultradim/blob/main/BloomMap/renderer/render.mjs): `BloomMap/renderer/render.mjs`
- [Sunburst export](https://github.com/gamakon/ultradim/blob/main/BloomMap/galaxy/build_sunburst_svg.py): `BloomMap/galaxy/build_sunburst_svg.py`

### Other components

- **AI assistant**
- **Analyst**

## Connections

- AI assistant → MCP tools: invokes tools (evidence: `README.md`)
- MCP tools → Vector analytics: wraps engine (evidence: `README.md`)
- Analyst → Vector analytics: runs analyses
- Vector analytics → ChEMBL segmentation: clusters vectors
- Vector analytics → Movie segmentation: clusters vectors
- ChEMBL segmentation → ChEMBL map data: writes tree inputs
- Movie segmentation → Movie map data: writes tree inputs
- ChEMBL map data → Shared map builder: uses shared logic (evidence: `BloomMap/process/build_bloommap_json_chembl.py`)
- Movie map data → Shared map builder: uses shared logic (evidence: `BloomMap/process/build_bloommap_json_ml20m.py`)
- Shared map builder → Poster renderer: supplies map data
- Shared map builder → Galaxy enrichment: supplies tree data (evidence: `BloomMap/galaxy/build_galaxy.py`)
- Poster renderer → Paper profiles: uses layout profiles (evidence: `BloomMap/renderer/visualization.js`)
- SVG export → Poster renderer: loads HTML view (evidence: `BloomMap/renderer/render.mjs`)
- Galaxy enrichment → Sunburst export: supplies hierarchy
