# shiv0xparanoid/holopad architecture

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

- Interactive diagram: https://gitdiagram.com/shiv0xparanoid/holopad
- Repository: https://github.com/shiv0xparanoid/holopad

## Overview

Holopad is a web-based spatial-creation prototype. Its main user flow is image upload, AI-assisted segmentation and 3D-model generation, then interactive viewing and editing with optional hand tracking and export. The repository also includes a separate assistant, memory, and marketplace/token API, plus marketing and showcase experiences. Several screens and backend modules were not excerpted, so their documented capabilities are represented at subsystem level; unverified connections are omitted or marked dashed.

Main entry points: [`server/src/index.js`](https://github.com/shiv0xparanoid/holopad/blob/main/server/src/index.js) (Backend API), [`web/src/App.jsx`](https://github.com/shiv0xparanoid/holopad/blob/main/web/src/App.jsx) (App Router), [`web/src/screens/Viewer.jsx`](https://github.com/shiv0xparanoid/holopad/blob/main/web/src/screens/Viewer.jsx) (Hologram Viewer), [`server/src/ai_service.js`](https://github.com/shiv0xparanoid/holopad/blob/main/server/src/ai_service.js) (AI Assistant)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Spatial Web App"]
  node_app["App Router<br/>[App.jsx]"]
  node_upload["Image Upload<br/>[Upload.jsx]"]
  node_viewer["Hologram Viewer<br/>[Viewer.jsx]"]
  node_engine["3D Engine<br/>[HologramEngine.js]"]
  node_hands["Hand Tracking<br/>[HandController.js]"]
  node_showcase["Holostage<br/>[HolostagePage.jsx]"]
  node_website["Marketing Pages<br/>[WebsiteHome.jsx]"]
  node_sound["Spatial Audio<br/>[SoundManager.js]"]
end

subgraph group_creation["Image Creation"]
  node_uploadapi["Backend API<br/>[index.js]"]
  node_imagepipeline["GLB Processing"]
  node_samclient["SAM Client<br/>[sam_client.js]"]
  node_samservice["SAM Service<br/>[sam_service.py]"]
  node_meg["Image Analysis<br/>[meg.js]"]
end

subgraph group_assistant["Assistant Services"]
  node_persona["Persona API<br/>[persona.js]"]
  node_ai["AI Assistant<br/>[ai_service.js]"]
  node_memory["Conversation Memory<br/>[memory.js]"]
end

subgraph group_platform["Platform Services"]
  node_db[("Database<br/>[db.js]")]
  node_market["Marketplace<br/>[index.js]"]
end

node_user(("Creator"))
node_ollama["Ollama"]

node_user -->|"opens"| node_app
node_app -->|"routes to"| node_upload
node_app -->|"routes to"| node_viewer
node_app -->|"routes to"| node_showcase
node_app -->|"routes to"| node_website
node_upload -.->|"submits image"| node_uploadapi
node_uploadapi -->|"requests segmentation"| node_samclient
node_uploadapi -->|"creates model"| node_imagepipeline
node_samclient -->|"sends image"| node_samservice
node_imagepipeline -->|"requests segmentation"| node_samclient
node_uploadapi -->|"requests image analysis"| node_meg
node_uploadapi -.->|"serves model URL"| node_viewer
node_viewer -->|"initializes renderer"| node_engine
node_engine -->|"initializes tracking"| node_hands
node_viewer -->|"uses audio"| node_sound
node_viewer -->|"calls chat API"| node_uploadapi
node_uploadapi -->|"mounts routes"| node_persona
node_persona -->|"delegates assistant work"| node_ai
node_ai -->|"searches and records"| node_memory
node_ai -->|"generates responses"| node_ollama
node_uploadapi -->|"connects and stores"| node_db
node_user -->|"browses and lists models"| node_market

click node_app "https://github.com/shiv0xparanoid/holopad/blob/main/web/src/App.jsx"
click node_upload "https://github.com/shiv0xparanoid/holopad/blob/main/web/src/screens/Upload.jsx"
click node_viewer "https://github.com/shiv0xparanoid/holopad/blob/main/web/src/screens/Viewer.jsx"
click node_engine "https://github.com/shiv0xparanoid/holopad/blob/main/web/src/utils/HologramEngine.js"
click node_hands "https://github.com/shiv0xparanoid/holopad/blob/main/web/src/utils/HandController.js"
click node_showcase "https://github.com/shiv0xparanoid/holopad/blob/main/web/src/screens/HolostagePage.jsx"
click node_website "https://github.com/shiv0xparanoid/holopad/blob/main/web/src/pages/WebsiteHome.jsx"
click node_uploadapi "https://github.com/shiv0xparanoid/holopad/blob/main/server/src/index.js"
click node_imagepipeline "https://github.com/shiv0xparanoid/holopad/blob/main/server/src/process_image_to_glb.js"
click node_samclient "https://github.com/shiv0xparanoid/holopad/blob/main/server/src/sam_client.js"
click node_samservice "https://github.com/shiv0xparanoid/holopad/blob/main/server/python/sam_service.py"
click node_meg "https://github.com/shiv0xparanoid/holopad/blob/main/server/src/meg.js"
click node_persona "https://github.com/shiv0xparanoid/holopad/blob/main/server/src/persona.js"
click node_ai "https://github.com/shiv0xparanoid/holopad/blob/main/server/src/ai_service.js"
click node_memory "https://github.com/shiv0xparanoid/holopad/blob/main/server/src/memory.js"
click node_db "https://github.com/shiv0xparanoid/holopad/blob/main/server/src/db.js"
click node_market "https://github.com/shiv0xparanoid/holopad/blob/main/server/src/index.js"
click node_sound "https://github.com/shiv0xparanoid/holopad/blob/main/web/src/utils/SoundManager.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_upload,node_viewer,node_engine,node_hands,node_showcase,node_website,node_sound toneBlue
class node_uploadapi,node_imagepipeline,node_samclient,node_samservice,node_meg toneAmber
class node_persona,node_ai,node_memory toneMint
class node_db,node_market toneRose
class node_user,node_ollama toneIndigo
```

## Components

### Spatial Web App

- [App Router](https://github.com/shiv0xparanoid/holopad/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [Image Upload](https://github.com/shiv0xparanoid/holopad/blob/main/web/src/screens/Upload.jsx): `web/src/screens/Upload.jsx`
- [Hologram Viewer](https://github.com/shiv0xparanoid/holopad/blob/main/web/src/screens/Viewer.jsx): `web/src/screens/Viewer.jsx`
- [3D Engine](https://github.com/shiv0xparanoid/holopad/blob/main/web/src/utils/HologramEngine.js): `web/src/utils/HologramEngine.js`
- [Hand Tracking](https://github.com/shiv0xparanoid/holopad/blob/main/web/src/utils/HandController.js): `web/src/utils/HandController.js`
- [Holostage](https://github.com/shiv0xparanoid/holopad/blob/main/web/src/screens/HolostagePage.jsx): `web/src/screens/HolostagePage.jsx`
- [Marketing Pages](https://github.com/shiv0xparanoid/holopad/blob/main/web/src/pages/WebsiteHome.jsx): `web/src/pages/WebsiteHome.jsx`
- [Spatial Audio](https://github.com/shiv0xparanoid/holopad/blob/main/web/src/utils/SoundManager.js): `web/src/utils/SoundManager.js`

### Image Creation

- [Backend API](https://github.com/shiv0xparanoid/holopad/blob/main/server/src/index.js): `server/src/index.js`
- [GLB Processing](https://github.com/shiv0xparanoid/holopad/blob/main/server/src/process_image_to_glb.js): `server/src/process_image_to_glb.js`
- [SAM Client](https://github.com/shiv0xparanoid/holopad/blob/main/server/src/sam_client.js): `server/src/sam_client.js`
- [SAM Service](https://github.com/shiv0xparanoid/holopad/blob/main/server/python/sam_service.py): `server/python/sam_service.py`
- [Image Analysis](https://github.com/shiv0xparanoid/holopad/blob/main/server/src/meg.js): `server/src/meg.js`

### Assistant Services

- [Persona API](https://github.com/shiv0xparanoid/holopad/blob/main/server/src/persona.js): `server/src/persona.js`
- [AI Assistant](https://github.com/shiv0xparanoid/holopad/blob/main/server/src/ai_service.js): `server/src/ai_service.js`
- [Conversation Memory](https://github.com/shiv0xparanoid/holopad/blob/main/server/src/memory.js): `server/src/memory.js`

### Platform Services

- [Database](https://github.com/shiv0xparanoid/holopad/blob/main/server/src/db.js): `server/src/db.js`
- [Marketplace](https://github.com/shiv0xparanoid/holopad/blob/main/server/src/index.js): `server/src/index.js`

### Other components

- **Creator**
- **Ollama**

## Connections

- Creator → App Router: opens
- App Router → Image Upload: routes to (evidence: `web/src/App.jsx`)
- App Router → Hologram Viewer: routes to (evidence: `web/src/App.jsx`)
- App Router → Holostage: routes to (evidence: `web/src/App.jsx`)
- App Router → Marketing Pages: routes to (evidence: `web/src/App.jsx`)
- Image Upload → Backend API: submits image
- Backend API → SAM Client: requests segmentation (evidence: `server/src/index.js`)
- Backend API → GLB Processing: creates model (evidence: `server/src/index.js`)
- SAM Client → SAM Service: sends image (evidence: `server/src/sam_client.js`)
- GLB Processing → SAM Client: requests segmentation (evidence: `server/src/process_image_to_glb.js`)
- Backend API → Image Analysis: requests image analysis (evidence: `server/src/index.js`)
- Backend API → Hologram Viewer: serves model URL
- Hologram Viewer → 3D Engine: initializes renderer (evidence: `web/src/screens/Viewer.jsx`)
- 3D Engine → Hand Tracking: initializes tracking (evidence: `web/src/utils/HologramEngine.js`)
- Hologram Viewer → Spatial Audio: uses audio (evidence: `web/src/screens/Viewer.jsx`)
- Hologram Viewer → Backend API: calls chat API (evidence: `web/src/screens/Viewer.jsx`)
- Backend API → Persona API: mounts routes (evidence: `server/src/index.js`)
- Persona API → AI Assistant: delegates assistant work (evidence: `server/src/persona.js`)
- AI Assistant → Conversation Memory: searches and records (evidence: `server/src/ai_service.js`)
- AI Assistant → Ollama: generates responses (evidence: `server/src/ai_service.js`)
- Backend API → Database: connects and stores (evidence: `server/src/index.js`)
- Creator → Marketplace: browses and lists models (evidence: `server/src/index.js`)
