# mhentuniverse/mhent-aisa architecture

> Architecture diagram of the GitHub repository mhentuniverse/mhent-aisa, 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/mhentuniverse/mhent-aisa
- Repository: https://github.com/mhentuniverse/mhent-aisa

## Overview

AISA is a private AI companion delivered as a browser SPA and Electron desktop app. Its main user journey is to unlock the sanctuary, select or start a chat, send text, image, or audio input, receive Harmony/Echo replies, and optionally hear them spoken alongside Live2D companions. The README also documents long-term memory, calendar/data connectivity, and vision analysis. Desktop IPC and local chat persistence are visible in the sampled code; several README-described integrations are not sampled, so their links are documented rather than source-verified.

Main entry points: [`js/app.js`](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/app.js) (Chat controller), [`js/ai-engine.js`](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/ai-engine.js) (AI conversation engine), [`js/voice.js`](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/voice.js) (Voice input and output), [`js/live2d-stage.js`](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/live2d-stage.js) (Live2D stage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Sanctuary UI"]
  node_spa["Sanctuary SPA<br/>[index.html]"]
  node_auth["Passcode access<br/>[auth.js]"]
  node_controller["Chat controller<br/>[app.js]"]
  node_markdown["Markdown rendering<br/>[markdown.js]"]
end

subgraph group_conversation["Conversation AI"]
  node_ai["AI conversation engine<br/>[ai-engine.js]"]
  node_vision["Vision analysis<br/>[vision.js]"]
  node_cloudai{{"Cloud AI services"}}
  node_ollama{{"Local Ollama"}}
end

subgraph group_companion["Companion Media"]
  node_voice["Voice input and output<br/>[voice.js]"]
  node_stage["Live2D stage<br/>[live2d-stage.js]"]
  node_cubism["Cubism runtime"]
  node_models["Live2D model assets"]
end

subgraph group_state["Memory and Data"]
  node_memory["Long-term memory<br/>[memory.js]"]
  node_memorycloud[("Cloudflare D1")]
  node_calendar["Calendar data bridge"]
  node_supabase{{"Supabase REST"}}
  node_chatfiles[("Local chat files")]
end

subgraph group_desktop["Desktop Runtime"]
  node_webserver["Local web server<br/>[server.js]"]
  node_bridge["Desktop bridge<br/>[desktop-bridge.js]"]
  node_preload["Electron preload<br/>[preload.js]"]
  node_main["Electron main process<br/>[main.js]"]
  node_tts["Gemini voice engine"]
end

node_owner(("Sanctuary user"))

node_owner -->|"opens"| node_spa
node_spa -->|"presents access"| node_auth
node_auth -->|"notifies unlock"| node_controller
node_owner -->|"sends chat"| node_controller
node_controller -->|"requests replies"| node_ai
node_ai -->|"calls cloud models"| node_cloudai
node_ai -->|"falls back locally"| node_ollama
node_ai -.->|"routes image analysis"| node_vision
node_controller -.->|"renders messages"| node_markdown
node_controller -->|"adds facts"| node_memory
node_memory -->|"syncs memory"| node_memorycloud
node_controller -->|"uses schedule data"| node_calendar
node_calendar -->|"accesses REST API"| node_supabase
node_owner -->|"speaks or listens"| node_voice
node_voice -->|"submits audio prompt"| node_controller
node_voice -->|"drives lip sync"| node_stage
node_stage -.->|"uses runtime"| node_cubism
node_stage -->|"loads models"| node_models
node_voice -->|"requests desktop speech"| node_bridge
node_bridge -.->|"invokes IPC"| node_preload
node_preload -->|"dispatches IPC"| node_main
node_main -->|"synthesizes speech"| node_tts
node_main -->|"writes session logs"| node_chatfiles
node_owner -->|"opens web edition"| node_webserver
node_webserver -->|"serves application"| node_spa

click node_spa "https://github.com/mhentuniverse/mhent-aisa/blob/main/index.html"
click node_auth "https://github.com/mhentuniverse/mhent-aisa/blob/main/js/auth.js"
click node_controller "https://github.com/mhentuniverse/mhent-aisa/blob/main/js/app.js"
click node_markdown "https://github.com/mhentuniverse/mhent-aisa/blob/main/js/markdown.js"
click node_ai "https://github.com/mhentuniverse/mhent-aisa/blob/main/js/ai-engine.js"
click node_vision "https://github.com/mhentuniverse/mhent-aisa/blob/main/js/vision.js"
click node_voice "https://github.com/mhentuniverse/mhent-aisa/blob/main/js/voice.js"
click node_stage "https://github.com/mhentuniverse/mhent-aisa/blob/main/js/live2d-stage.js"
click node_cubism "https://github.com/mhentuniverse/mhent-aisa/blob/main/js/live2d/live2dcubismcore.js"
click node_models "https://github.com/mhentuniverse/mhent-aisa/tree/main/assets/live2d-models"
click node_memory "https://github.com/mhentuniverse/mhent-aisa/blob/main/js/memory.js"
click node_webserver "https://github.com/mhentuniverse/mhent-aisa/blob/main/server.js"
click node_bridge "https://github.com/mhentuniverse/mhent-aisa/blob/main/js/desktop-bridge.js"
click node_preload "https://github.com/mhentuniverse/mhent-aisa/blob/main/desktop/preload.js"
click node_main "https://github.com/mhentuniverse/mhent-aisa/blob/main/desktop/main.js"
click node_tts "https://github.com/mhentuniverse/mhent-aisa/blob/main/desktop/gemini-voice-engine.js"
click node_chatfiles "https://github.com/mhentuniverse/mhent-aisa/tree/main/data/chats"

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_spa,node_auth,node_controller,node_markdown,node_owner toneBlue
class node_ai,node_vision,node_cloudai,node_ollama toneAmber
class node_voice,node_stage,node_cubism,node_models toneMint
class node_memory,node_memorycloud,node_calendar,node_supabase,node_chatfiles toneRose
class node_webserver,node_bridge,node_preload,node_main,node_tts toneIndigo
```

## Components

### Sanctuary UI

- [Sanctuary SPA](https://github.com/mhentuniverse/mhent-aisa/blob/main/index.html): `index.html`
- [Passcode access](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/auth.js): `js/auth.js`
- [Chat controller](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/app.js): `js/app.js`
- [Markdown rendering](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/markdown.js): `js/markdown.js`

### Conversation AI

- [AI conversation engine](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/ai-engine.js): `js/ai-engine.js`
- [Vision analysis](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/vision.js): `js/vision.js`
- **Cloud AI services**
- **Local Ollama**

### Companion Media

- [Voice input and output](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/voice.js): `js/voice.js`
- [Live2D stage](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/live2d-stage.js): `js/live2d-stage.js`
- [Cubism runtime](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/live2d/live2dcubismcore.js): `js/live2d/live2dcubismcore.js`
- [Live2D model assets](https://github.com/mhentuniverse/mhent-aisa/tree/main/assets/live2d-models): `assets/live2d-models`

### Memory and Data

- [Long-term memory](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/memory.js): `js/memory.js`
- **Cloudflare D1**
- **Calendar data bridge**
- **Supabase REST**
- [Local chat files](https://github.com/mhentuniverse/mhent-aisa/tree/main/data/chats): `data/chats`

### Desktop Runtime

- [Local web server](https://github.com/mhentuniverse/mhent-aisa/blob/main/server.js): `server.js`
- [Desktop bridge](https://github.com/mhentuniverse/mhent-aisa/blob/main/js/desktop-bridge.js): `js/desktop-bridge.js`
- [Electron preload](https://github.com/mhentuniverse/mhent-aisa/blob/main/desktop/preload.js): `desktop/preload.js`
- [Electron main process](https://github.com/mhentuniverse/mhent-aisa/blob/main/desktop/main.js): `desktop/main.js`
- [Gemini voice engine](https://github.com/mhentuniverse/mhent-aisa/blob/main/desktop/gemini-voice-engine.js): `desktop/gemini-voice-engine.js`

### Other components

- **Sanctuary user**

## Connections

- Sanctuary user → Sanctuary SPA: opens (evidence: `README.md`)
- Sanctuary SPA → Passcode access: presents access (evidence: `js/auth.js`)
- Passcode access → Chat controller: notifies unlock (evidence: `js/auth.js`)
- Sanctuary user → Chat controller: sends chat (evidence: `README.md`)
- Chat controller → AI conversation engine: requests replies (evidence: `js/app.js`)
- AI conversation engine → Cloud AI services: calls cloud models (evidence: `README.md`)
- AI conversation engine → Local Ollama: falls back locally (evidence: `js/ai-engine.js`)
- AI conversation engine → Vision analysis: routes image analysis
- Chat controller → Markdown rendering: renders messages
- Chat controller → Long-term memory: adds facts (evidence: `js/app.js`)
- Long-term memory → Cloudflare D1: syncs memory (evidence: `README.md`)
- Chat controller → Calendar data bridge: uses schedule data (evidence: `README.md`)
- Calendar data bridge → Supabase REST: accesses REST API (evidence: `README.md`)
- Sanctuary user → Voice input and output: speaks or listens (evidence: `README.md`)
- Voice input and output → Chat controller: submits audio prompt (evidence: `js/voice.js`)
- Voice input and output → Live2D stage: drives lip sync (evidence: `js/voice.js`)
- Live2D stage → Cubism runtime: uses runtime
- Live2D stage → Live2D model assets: loads models (evidence: `js/live2d-stage.js`)
- Voice input and output → Desktop bridge: requests desktop speech (evidence: `js/voice.js`)
- Desktop bridge → Electron preload: invokes IPC
- Electron preload → Electron main process: dispatches IPC (evidence: `desktop/preload.js`)
- Electron main process → Gemini voice engine: synthesizes speech (evidence: `desktop/main.js`)
- Electron main process → Local chat files: writes session logs (evidence: `desktop/main.js`)
- Sanctuary user → Local web server: opens web edition (evidence: `server.js`)
- Local web server → Sanctuary SPA: serves application (evidence: `server.js`)
