# prolix-oc/lumiverse architecture

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

- Interactive diagram: https://gitdiagram.com/prolix-oc/lumiverse
- Repository: https://github.com/prolix-oc/lumiverse

## Overview

Lumiverse is a full-stack AI chat application. Users work in the frontend chat and character interfaces; requests cross the API boundary to backend services, which generate responses and persist application data. Separate product areas provide embeddings and retrieval, image generation, speech, and Spindle extensions. The README documents the broader backend, real-time event bus, authentication, and generation pipeline; the supplied excerpts directly support only selected embedding, retrieval, and extension-storage details, so uncertain internal wiring is omitted.

Main entry points: [`frontend/src/components/chat/ChatView.tsx`](https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/components/chat/ChatView.tsx) (Chat interface), [`src`](https://github.com/prolix-oc/lumiverse/tree/main/src) (HTTP backend), [`frontend/src/api/client.ts`](https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/api/client.ts) (Frontend API), [`src/services/embeddings.service.ts`](https://github.com/prolix-oc/lumiverse/blob/main/src/services/embeddings.service.ts) (Embedding service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["Application shell<br/>[App.tsx]"]
  node_chat["Chat interface<br/>[ChatView.tsx]"]
  node_api["Frontend API<br/>[client.ts]"]
  node_characters["Characters and chats<br/>[chats.ts]"]
  node_imagegen["Image generation<br/>[ImageGenPanel.tsx]"]
  node_speech["Speech input<br/>[sttEngine.ts]"]
end

subgraph group_backend["Backend services"]
  node_backend["HTTP backend"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_generation["LLM generation"]
  node_events["Realtime events"]
  node_data[("Application data")]
end

subgraph group_knowledge["Knowledge and retrieval"]
  node_embeddings_ui["Embedding settings"]
  node_embedding_routes["Embedding routes"]
  node_embedding_service["Embedding service"]
  node_databank["Databank retrieval"]
  node_vector_store[("Vector store")]
  node_worldbooks["World books"]
end

subgraph group_extensions["Extensions and integrations"]
  node_spindle["Spindle runtime"]
  node_extension["Extensions"]
end

node_user(("User"))
node_llm_provider(("LLM provider"))
node_image_provider(("Image provider"))
node_speech_provider(("Speech service"))

node_user -->|"uses"| node_app
node_app -->|"presents"| node_chat
node_chat -->|"requests"| node_api
node_api -->|"calls"| node_backend
node_backend -->|"authenticates"| node_auth
node_backend -->|"dispatches"| node_generation
node_generation -->|"requests completion"| node_llm_provider
node_generation -->|"persists chat"| node_data
node_backend -->|"publishes"| node_events
node_chat -->|"loads chat data"| node_characters
node_embeddings_ui -->|"saves settings"| node_api
node_api -->|"calls"| node_embedding_routes
node_embedding_routes -->|"invokes"| node_embedding_service
node_embedding_service -->|"searches and writes"| node_vector_store
node_embedding_service -->|"reads and updates"| node_data
node_databank -->|"embeds and searches"| node_embedding_service
node_databank -->|"searches"| node_vector_store
node_embedding_routes -->|"uses"| node_worldbooks
node_chat -->|"requests images"| node_imagegen
node_imagegen -.->|"submits generation"| node_image_provider
node_chat -->|"captures speech"| node_speech
node_speech -.->|"transcribes"| node_speech_provider
node_extension -->|"uses runtime"| node_spindle
node_spindle -->|"accesses extension storage"| node_data

click node_app "https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/App.tsx"
click node_chat "https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/components/chat/ChatView.tsx"
click node_api "https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/api/client.ts"
click node_backend "https://github.com/prolix-oc/lumiverse/tree/main/src"
click node_auth "https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/api/auth.ts"
click node_generation "https://github.com/prolix-oc/lumiverse/tree/main/src"
click node_events "https://github.com/prolix-oc/lumiverse/tree/main/src"
click node_data "https://github.com/prolix-oc/lumiverse/tree/main/src"
click node_characters "https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/api/chats.ts"
click node_embeddings_ui "https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/components/panels/embedding-connections/EmbeddingConnectionManager.tsx"
click node_embedding_routes "https://github.com/prolix-oc/lumiverse/blob/main/src/routes/embeddings.routes.ts"
click node_embedding_service "https://github.com/prolix-oc/lumiverse/blob/main/src/services/embeddings.service.ts"
click node_databank "https://github.com/prolix-oc/lumiverse/blob/main/src/services/databank/retrieval.service.ts"
click node_vector_store "https://github.com/prolix-oc/lumiverse/tree/main/src/services/vector-store"
click node_worldbooks "https://github.com/prolix-oc/lumiverse/blob/main/src/services/world-books.service.ts"
click node_imagegen "https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/components/panels/ImageGenPanel.tsx"
click node_speech "https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/lib/sttEngine.ts"
click node_spindle "https://github.com/prolix-oc/lumiverse/blob/main/src/spindle/worker-host-storage-api.ts"
click node_extension "https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/components/spindle/SpindleAppMount.tsx"

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_chat,node_api,node_characters,node_imagegen,node_speech,node_user toneBlue
class node_backend,node_auth,node_generation,node_events,node_data toneAmber
class node_embeddings_ui,node_embedding_routes,node_embedding_service,node_databank,node_vector_store,node_worldbooks toneMint
class node_spindle,node_extension toneRose
class node_llm_provider,node_image_provider,node_speech_provider toneIndigo
```

## Components

### User experience

- [Application shell](https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Chat interface](https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/components/chat/ChatView.tsx): `frontend/src/components/chat/ChatView.tsx`
- [Frontend API](https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Characters and chats](https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/api/chats.ts): `frontend/src/api/chats.ts`
- [Image generation](https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/components/panels/ImageGenPanel.tsx): `frontend/src/components/panels/ImageGenPanel.tsx`
- [Speech input](https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/lib/sttEngine.ts): `frontend/src/lib/sttEngine.ts`

### Backend services

- [HTTP backend](https://github.com/prolix-oc/lumiverse/tree/main/src): `src`
- [Authentication](https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/api/auth.ts): `frontend/src/api/auth.ts`
- [LLM generation](https://github.com/prolix-oc/lumiverse/tree/main/src): `src`
- [Realtime events](https://github.com/prolix-oc/lumiverse/tree/main/src): `src`
- [Application data](https://github.com/prolix-oc/lumiverse/tree/main/src): `src`

### Knowledge and retrieval

- [Embedding settings](https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/components/panels/embedding-connections/EmbeddingConnectionManager.tsx): `frontend/src/components/panels/embedding-connections/EmbeddingConnectionManager.tsx`
- [Embedding routes](https://github.com/prolix-oc/lumiverse/blob/main/src/routes/embeddings.routes.ts): `src/routes/embeddings.routes.ts`
- [Embedding service](https://github.com/prolix-oc/lumiverse/blob/main/src/services/embeddings.service.ts): `src/services/embeddings.service.ts`
- [Databank retrieval](https://github.com/prolix-oc/lumiverse/blob/main/src/services/databank/retrieval.service.ts): `src/services/databank/retrieval.service.ts`
- [Vector store](https://github.com/prolix-oc/lumiverse/tree/main/src/services/vector-store): `src/services/vector-store`
- [World books](https://github.com/prolix-oc/lumiverse/blob/main/src/services/world-books.service.ts): `src/services/world-books.service.ts`

### Extensions and integrations

- [Spindle runtime](https://github.com/prolix-oc/lumiverse/blob/main/src/spindle/worker-host-storage-api.ts): `src/spindle/worker-host-storage-api.ts`
- [Extensions](https://github.com/prolix-oc/lumiverse/blob/main/frontend/src/components/spindle/SpindleAppMount.tsx): `frontend/src/components/spindle/SpindleAppMount.tsx`

### Other components

- **User**
- **LLM provider**
- **Image provider**
- **Speech service**

## Connections

- User → Application shell: uses
- Application shell → Chat interface: presents
- Chat interface → Frontend API: requests
- Frontend API → HTTP backend: calls
- HTTP backend → Authentication: authenticates
- HTTP backend → LLM generation: dispatches
- LLM generation → LLM provider: requests completion
- LLM generation → Application data: persists chat
- HTTP backend → Realtime events: publishes
- Chat interface → Characters and chats: loads chat data
- Embedding settings → Frontend API: saves settings
- Frontend API → Embedding routes: calls
- Embedding routes → Embedding service: invokes
- Embedding service → Vector store: searches and writes
- Embedding service → Application data: reads and updates
- Databank retrieval → Embedding service: embeds and searches
- Databank retrieval → Vector store: searches
- Embedding routes → World books: uses
- Chat interface → Image generation: requests images
- Image generation → Image provider: submits generation
- Chat interface → Speech input: captures speech
- Speech input → Speech service: transcribes
- Extensions → Spindle runtime: uses runtime
- Spindle runtime → Application data: accesses extension storage