# y0o0ng/galpi architecture

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

- Interactive diagram: https://gitdiagram.com/y0o0ng/galpi
- Repository: https://github.com/y0o0ng/galpi

## Overview

Galpi is a self-hosted personal assistant: the user interacts with Xion through a web/PWA client, and the Node/Express server runs chat against bounded retrieval and tools while persisting conversation and knowledge state. Distinct capabilities include memory organization, task scheduling, voice, attachments, papers, and optional mail/news observers. The README documents these product boundaries; sampled source confirms selected routes and services, but not every runtime wiring detail. Trading is a separate experimental track, so it is shown as an independent branch.

Main entry points: [`server.js`](https://github.com/y0o0ng/galpi/blob/main/server.js) (Express Server), [`lib/assistant-retrieval.js`](https://github.com/y0o0ng/galpi/blob/main/lib/assistant-retrieval.js) (Bounded Retrieval), [`public/app.js`](https://github.com/y0o0ng/galpi/blob/main/public/app.js) (Xion Web / PWA), [`lib/voice/halfduplex-routes.js`](https://github.com/y0o0ng/galpi/blob/main/lib/voice/halfduplex-routes.js) (Half-duplex Voice)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interaction"]
  node_webui["Xion Web / PWA<br/>[app.js]"]
  node_server["Express Server<br/>[server.js]"]
  node_voice["Half-duplex Voice"]
  node_voiceui["Voice UI<br/>[halfduplex.js]"]
end

subgraph group_memory["Memory &amp; Knowledge"]
  node_chatstate[("Conversation State<br/>[server.js]")]
  node_vault["Markdown Knowledge Vault<br/>[server.js]"]
  node_retrieval["Bounded Retrieval"]
  node_topicchunks[("Topic Chunk Index")]
  node_codex["Codex Librarian<br/>[codex-organizer.js]"]
end

subgraph group_assistant["Assistant Runtime"]
  node_modelruntime["GPT Responses Runtime"]
  node_webtools["Web Evidence Tools<br/>[tool.js]"]
  node_papers["Paper Retrieval<br/>[paper-search.js]"]
  node_documents["Attachment Library"]
end

subgraph group_workflows["Workflows"]
  node_tasks["Task &amp; Reminder API"]
  node_scheduler["Deterministic Scheduler"]
  node_push["Web Push Delivery"]
  node_mail["Mail Observer<br/>[routes.js]"]
  node_news["News Observer<br/>[routes.js]"]
end

subgraph group_research["Trading Research"]
  node_trading["Backtest Research<br/>[loop.py]"]
end

node_user(("User"))
node_externalweb(("Web Search Provider"))
node_kis(("KIS Paper API"))

node_user -->|"uses"| node_webui
node_webui -->|"sends requests"| node_server
node_server -->|"persists conversation"| node_chatstate
node_server -->|"runs chat"| node_modelruntime
node_modelruntime -->|"requests context"| node_retrieval
node_retrieval -->|"reads chunks"| node_topicchunks
node_retrieval -->|"retrieves knowledge"| node_vault
node_codex -->|"organizes metadata"| node_vault
node_server -->|"exposes tools"| node_webtools
node_webtools -->|"searches or extracts"| node_externalweb
node_server -->|"exposes retrieval"| node_papers
node_server -->|"serves attachments"| node_documents
node_user -->|"speaks"| node_voiceui
node_voiceui -->|"uploads audio"| node_voice
node_voice -->|"transcribes for chat"| node_server
node_server -->|"serves task actions"| node_tasks
node_scheduler -->|"delivers reminders"| node_push
node_server -.->|"serves observer API"| node_mail
node_server -.->|"serves briefing API"| node_news
node_trading -.->|"paper integration"| node_kis

click node_webui "https://github.com/y0o0ng/galpi/blob/main/public/app.js"
click node_server "https://github.com/y0o0ng/galpi/blob/main/server.js"
click node_chatstate "https://github.com/y0o0ng/galpi/blob/main/server.js"
click node_vault "https://github.com/y0o0ng/galpi/blob/main/server.js"
click node_retrieval "https://github.com/y0o0ng/galpi/blob/main/lib/assistant-retrieval.js"
click node_topicchunks "https://github.com/y0o0ng/galpi/blob/main/lib/topic-chunk-store.js"
click node_codex "https://github.com/y0o0ng/galpi/blob/main/lib/codex-organizer.js"
click node_modelruntime "https://github.com/y0o0ng/galpi/blob/main/lib/openai-responses-tool-loop.js"
click node_webtools "https://github.com/y0o0ng/galpi/blob/main/lib/web/tool.js"
click node_papers "https://github.com/y0o0ng/galpi/blob/main/lib/paper-search.js"
click node_documents "https://github.com/y0o0ng/galpi/blob/main/lib/attachment-library.js"
click node_voice "https://github.com/y0o0ng/galpi/blob/main/lib/voice/halfduplex-routes.js"
click node_voiceui "https://github.com/y0o0ng/galpi/blob/main/public/voice/halfduplex.js"
click node_tasks "https://github.com/y0o0ng/galpi/blob/main/lib/assistant-task-routes.js"
click node_scheduler "https://github.com/y0o0ng/galpi/blob/main/lib/assistant-scheduler.js"
click node_push "https://github.com/y0o0ng/galpi/blob/main/lib/web-push-transport.js"
click node_mail "https://github.com/y0o0ng/galpi/blob/main/lib/mail/routes.js"
click node_news "https://github.com/y0o0ng/galpi/blob/main/lib/news/routes.js"
click node_trading "https://github.com/y0o0ng/galpi/blob/main/trading/backtest/loop.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_webui,node_server,node_voice,node_voiceui,node_user toneBlue
class node_chatstate,node_vault,node_retrieval,node_topicchunks,node_codex toneAmber
class node_modelruntime,node_webtools,node_papers,node_documents,node_kis toneMint
class node_tasks,node_scheduler,node_push,node_mail,node_news toneRose
class node_trading,node_externalweb toneIndigo
```

## Components

### Interaction

- [Xion Web / PWA](https://github.com/y0o0ng/galpi/blob/main/public/app.js): `public/app.js`
- [Express Server](https://github.com/y0o0ng/galpi/blob/main/server.js): `server.js`
- [Half-duplex Voice](https://github.com/y0o0ng/galpi/blob/main/lib/voice/halfduplex-routes.js): `lib/voice/halfduplex-routes.js`
- [Voice UI](https://github.com/y0o0ng/galpi/blob/main/public/voice/halfduplex.js): `public/voice/halfduplex.js`

### Memory & Knowledge

- [Conversation State](https://github.com/y0o0ng/galpi/blob/main/server.js): `server.js`
- [Markdown Knowledge Vault](https://github.com/y0o0ng/galpi/blob/main/server.js): `server.js`
- [Bounded Retrieval](https://github.com/y0o0ng/galpi/blob/main/lib/assistant-retrieval.js): `lib/assistant-retrieval.js`
- [Topic Chunk Index](https://github.com/y0o0ng/galpi/blob/main/lib/topic-chunk-store.js): `lib/topic-chunk-store.js`
- [Codex Librarian](https://github.com/y0o0ng/galpi/blob/main/lib/codex-organizer.js): `lib/codex-organizer.js`

### Assistant Runtime

- [GPT Responses Runtime](https://github.com/y0o0ng/galpi/blob/main/lib/openai-responses-tool-loop.js): `lib/openai-responses-tool-loop.js`
- [Web Evidence Tools](https://github.com/y0o0ng/galpi/blob/main/lib/web/tool.js): `lib/web/tool.js`
- [Paper Retrieval](https://github.com/y0o0ng/galpi/blob/main/lib/paper-search.js): `lib/paper-search.js`
- [Attachment Library](https://github.com/y0o0ng/galpi/blob/main/lib/attachment-library.js): `lib/attachment-library.js`

### Workflows

- [Task & Reminder API](https://github.com/y0o0ng/galpi/blob/main/lib/assistant-task-routes.js): `lib/assistant-task-routes.js`
- [Deterministic Scheduler](https://github.com/y0o0ng/galpi/blob/main/lib/assistant-scheduler.js): `lib/assistant-scheduler.js`
- [Web Push Delivery](https://github.com/y0o0ng/galpi/blob/main/lib/web-push-transport.js): `lib/web-push-transport.js`
- [Mail Observer](https://github.com/y0o0ng/galpi/blob/main/lib/mail/routes.js): `lib/mail/routes.js`
- [News Observer](https://github.com/y0o0ng/galpi/blob/main/lib/news/routes.js): `lib/news/routes.js`

### Trading Research

- [Backtest Research](https://github.com/y0o0ng/galpi/blob/main/trading/backtest/loop.py): `trading/backtest/loop.py`

### Other components

- **User**
- **Web Search Provider**
- **KIS Paper API**

## Connections

- User → Xion Web / PWA: uses
- Xion Web / PWA → Express Server: sends requests
- Express Server → Conversation State: persists conversation
- Express Server → GPT Responses Runtime: runs chat
- GPT Responses Runtime → Bounded Retrieval: requests context
- Bounded Retrieval → Topic Chunk Index: reads chunks
- Bounded Retrieval → Markdown Knowledge Vault: retrieves knowledge
- Codex Librarian → Markdown Knowledge Vault: organizes metadata
- Express Server → Web Evidence Tools: exposes tools
- Web Evidence Tools → Web Search Provider: searches or extracts
- Express Server → Paper Retrieval: exposes retrieval
- Express Server → Attachment Library: serves attachments
- User → Voice UI: speaks
- Voice UI → Half-duplex Voice: uploads audio
- Half-duplex Voice → Express Server: transcribes for chat
- Express Server → Task & Reminder API: serves task actions
- Deterministic Scheduler → Web Push Delivery: delivers reminders
- Express Server → Mail Observer: serves observer API
- Express Server → News Observer: serves briefing API
- Backtest Research → KIS Paper API: paper integration