# xiaomandebbie/vesper-phosphor architecture

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

- Interactive diagram: https://gitdiagram.com/xiaomandebbie/vesper-phosphor
- Repository: https://github.com/xiaomandebbie/vesper-phosphor

## Overview

Vesper-phosphor is a companion app with a periodic autonomous-wake loop and a web interface for shared moments. Its main flow gathers conversation and event context, asks a model to choose an action, executes that action, and records resulting state or activity. The README also documents optional memory, mood, heartbeat, and music integrations, plus diary, favorites, and star-jar features. Several route modules and integrations are represented from README documentation or the source index; their internal wiring was not sampled.

Main entry points: [`src/phosphor.js`](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/phosphor.js) (Wake scheduler), [`src/state.js`](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/state.js) (Shared database), [`src/context.js`](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/context.js) (Wake context), [`src/actions/index.js`](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/actions/index.js) (Action dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_wake["Wake and actions"]
  node_phosphor["Wake scheduler<br/>[phosphor.js]"]
  node_context["Wake context<br/>[context.js]"]
  node_decide["Model decision<br/>[decide.js]"]
  node_dispatcher["Action dispatcher<br/>[index.js]"]
  node_moment_action["Publish moment<br/>[moment.js]"]
  node_activity["Activity cards<br/>[activity.js]"]
  node_mcp_manager["MCP tools<br/>[mcp-manager.js]"]
end

subgraph group_shared["Shared state"]
  node_state[("Shared database<br/>[state.js]")]
  node_moments_store["Moment data<br/>[moments-store.js]"]
  node_star_jar["Star jar<br/>[star-jar.js]"]
end

subgraph group_web["Web experience"]
  node_vesper["Web server<br/>[vesper.js]"]
  node_moments_page["Moments page<br/>[moments-page.js]"]
  node_page_chrome["Shared page chrome<br/>[page-chrome.js]"]
  node_drives_page["Mood page<br/>[drives-page.js]"]
  node_diary_page["Diary page<br/>[diary-page.js]"]
  node_favorites["Favorites page<br/>[favorites.js]"]
end

subgraph group_integrations["Optional integrations"]
  node_memory_proxy["Memory proxy<br/>[memory-proxy.js]"]
  node_gateway["Model gateway<br/>[gateway.js]"]
  node_ombre["Ombre Brain"]
  node_drivesoid["Drivesoid"]
  node_heartbeat["Heartbeat"]
  node_music["Music MCP"]
end

node_user(("User"))
node_llm["Model service"]

node_phosphor -->|"gathers context"| node_context
node_phosphor -->|"requests decision"| node_decide
node_phosphor -->|"executes action"| node_dispatcher
node_phosphor -->|"reads and writes"| node_state
node_phosphor -->|"initializes tools"| node_mcp_manager
node_context -->|"reads conversation"| node_state
node_context -.->|"reads shared events"| node_heartbeat
node_decide -->|"requests completion"| node_llm
node_dispatcher -->|"dispatches action"| node_moment_action
node_dispatcher -->|"records activity"| node_activity
node_dispatcher -->|"runs tool action"| node_mcp_manager
node_moment_action -->|"stores moment"| node_state
node_moment_action -->|"checks posting interval"| node_moments_store
node_activity -->|"adds activity card"| node_moments_store
node_moments_store -->|"queries database"| node_state
node_star_jar -->|"stores star entries"| node_state
node_user -->|"uses web pages"| node_vesper
node_vesper -->|"serves moments"| node_moments_page
node_vesper -->|"serves star jar"| node_star_jar
node_moments_page -->|"reads and updates"| node_moments_store
node_moments_page -->|"renders shared chrome"| node_page_chrome
node_user -->|"views mood"| node_drives_page
node_user -->|"views diary"| node_diary_page
node_user -->|"views favorites"| node_favorites
node_user -->|"opens memory page"| node_memory_proxy
node_memory_proxy -->|"proxies requests"| node_ombre
node_context -.->|"includes mood context"| node_drivesoid
node_heartbeat -->|"provides diary files"| node_diary_page
node_mcp_manager -.->|"connects optional tools"| node_music
node_user -->|"sends chat requests"| node_gateway
node_gateway -->|"logs conversations"| node_state
node_gateway -.->|"requests model"| node_llm

click node_phosphor "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/phosphor.js"
click node_context "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/context.js"
click node_decide "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/decide.js"
click node_dispatcher "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/actions/index.js"
click node_moment_action "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/actions/moment.js"
click node_activity "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/actions/activity.js"
click node_mcp_manager "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/mcp-manager.js"
click node_state "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/state.js"
click node_moments_store "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/moments-store.js"
click node_star_jar "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/star-jar.js"
click node_vesper "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/vesper.js"
click node_moments_page "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/moments-page.js"
click node_page_chrome "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/page-chrome.js"
click node_drives_page "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/drives-page.js"
click node_diary_page "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/diary-page.js"
click node_favorites "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/favorites.js"
click node_memory_proxy "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/memory-proxy.js"
click node_gateway "https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/gateway.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_phosphor,node_context,node_decide,node_dispatcher,node_moment_action,node_activity,node_mcp_manager,node_user toneBlue
class node_state,node_moments_store,node_star_jar toneAmber
class node_vesper,node_moments_page,node_page_chrome,node_drives_page,node_diary_page,node_favorites toneMint
class node_memory_proxy,node_gateway,node_ombre,node_drivesoid,node_heartbeat,node_music toneRose
class node_llm toneIndigo
```

## Components

### Wake and actions

- [Wake scheduler](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/phosphor.js): `src/phosphor.js`
- [Wake context](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/context.js): `src/context.js`
- [Model decision](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/decide.js): `src/decide.js`
- [Action dispatcher](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/actions/index.js): `src/actions/index.js`
- [Publish moment](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/actions/moment.js): `src/actions/moment.js`
- [Activity cards](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/actions/activity.js): `src/actions/activity.js`
- [MCP tools](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/mcp-manager.js): `src/mcp-manager.js`

### Shared state

- [Shared database](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/state.js): `src/state.js`
- [Moment data](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/moments-store.js): `src/moments-store.js`
- [Star jar](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/star-jar.js): `src/star-jar.js`

### Web experience

- [Web server](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/vesper.js): `src/vesper.js`
- [Moments page](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/moments-page.js): `src/moments-page.js`
- [Shared page chrome](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/page-chrome.js): `src/page-chrome.js`
- [Mood page](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/drives-page.js): `src/drives-page.js`
- [Diary page](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/diary-page.js): `src/diary-page.js`
- [Favorites page](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/favorites.js): `src/favorites.js`

### Optional integrations

- [Memory proxy](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/memory-proxy.js): `src/memory-proxy.js`
- [Model gateway](https://github.com/xiaomandebbie/vesper-phosphor/blob/main/src/gateway.js): `src/gateway.js`
- **Ombre Brain**
- **Drivesoid**
- **Heartbeat**
- **Music MCP**

### Other components

- **User**
- **Model service**

## Connections

- Wake scheduler → Wake context: gathers context (evidence: `src/phosphor.js`)
- Wake scheduler → Model decision: requests decision (evidence: `src/phosphor.js`)
- Wake scheduler → Action dispatcher: executes action (evidence: `src/phosphor.js`)
- Wake scheduler → Shared database: reads and writes (evidence: `src/phosphor.js`)
- Wake scheduler → MCP tools: initializes tools (evidence: `src/phosphor.js`)
- Wake context → Shared database: reads conversation (evidence: `src/context.js`)
- Wake context → Heartbeat: reads shared events (evidence: `src/context.js`)
- Model decision → Model service: requests completion (evidence: `src/decide.js`)
- Action dispatcher → Publish moment: dispatches action (evidence: `src/actions/index.js`)
- Action dispatcher → Activity cards: records activity (evidence: `src/actions/index.js`)
- Action dispatcher → MCP tools: runs tool action
- Publish moment → Shared database: stores moment (evidence: `src/actions/moment.js`)
- Publish moment → Moment data: checks posting interval (evidence: `src/actions/moment.js`)
- Activity cards → Moment data: adds activity card (evidence: `src/actions/index.js`)
- Moment data → Shared database: queries database (evidence: `src/moments-store.js`)
- Star jar → Shared database: stores star entries (evidence: `src/star-jar.js`)
- User → Web server: uses web pages (evidence: `README.md`)
- Web server → Moments page: serves moments (evidence: `README.md`)
- Web server → Star jar: serves star jar (evidence: `README.md`)
- Moments page → Moment data: reads and updates (evidence: `src/moments-page.js`)
- Moments page → Shared page chrome: renders shared chrome (evidence: `src/moments-page.js`)
- User → Mood page: views mood (evidence: `README.md`)
- User → Diary page: views diary (evidence: `README.md`)
- User → Favorites page: views favorites (evidence: `README.md`)
- User → Memory proxy: opens memory page (evidence: `README.md`)
- Memory proxy → Ombre Brain: proxies requests (evidence: `README.md`)
- Wake context → Drivesoid: includes mood context (evidence: `README.md`)
- Heartbeat → Diary page: provides diary files (evidence: `README.md`)
- MCP tools → Music MCP: connects optional tools (evidence: `README.md`)
- User → Model gateway: sends chat requests (evidence: `README.md`)
- Model gateway → Shared database: logs conversations (evidence: `README.md`)
- Model gateway → Model service: requests model