# dakshgoyal1812/waguri architecture

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

- Interactive diagram: https://gitdiagram.com/dakshgoyal1812/waguri
- Repository: https://github.com/dakshgoyal1812/waguri

## Overview

Waguri is a persistent AI persona companion spanning a React client and Node/Express API. The main turn begins with a user message, passes through chat orchestration, persona/context retrieval, LLM response, mood selection and optional speech, then returns text and audio for the client. The README also documents voice input, games, memory inspection, authentication, alarms/push, and an animated VRM avatar. Edges are limited to relationships shown in excerpts or SOURCE INDEX references; unsampled subsystem links are omitted where their caller is not evidenced.

Main entry points: [`backend/src/orchestrator/chat.js`](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/orchestrator/chat.js) (Chat orchestrator), [`frontend/src/App.jsx`](https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/App.jsx) (Companion UI), [`backend/src/server.js`](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/server.js) (HTTP API), [`frontend/src/api.js`](https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Companion client"]
  node_app["Companion UI<br/>[App.jsx]"]
  node_api["API client<br/>[api.js]"]
  node_voice["Voice input<br/>[useVoiceInput.js]"]
  node_auth["Supabase auth<br/>[supabaseClient.js]"]
end

subgraph group_conversation["Conversation runtime"]
  node_backend["HTTP API<br/>[server.js]"]
  node_chat["Chat orchestrator<br/>[chat.js]"]
  node_prompt["Prompt builder<br/>[prompt.js]"]
  node_llm["LLM caller<br/>[caller.js]"]
  node_keypool["Key pool<br/>[keyPool.js]"]
end

subgraph group_services["Persona services"]
  node_memory[("RAG memory<br/>[supabase.js]")]
  node_embeddings["Embedding provider<br/>[embeddings.js]"]
  node_chunker["Memory chunker<br/>[chunker.js]"]
  node_persona["Persona data<br/>[personaSeed.js]"]
  node_mood["Mood engine<br/>[engine.js]"]
  node_tools["Public API tools<br/>[publicApis.js]"]
  node_games["Chat games<br/>[index.js]"]
  node_tts["Speech synthesis<br/>[index.js]"]
  node_audio[("Audio cache<br/>[audioCache.js]")]
end

subgraph group_experience["Avatar and alerts"]
  node_avatar["VRM renderer<br/>[AvatarCanvas.jsx]"]
  node_vrmstore[("Avatar registry<br/>[vrmStore.js]")]
  node_memoryui["Memory inspector"]
  node_pushclient["Push client<br/>[pushClient.js]"]
  node_pushservice["Push service<br/>[index.js]"]
  node_scheduler["Push scheduler<br/>[scheduler.js]"]
end

node_user(("User"))
node_externalapis{{"Public API providers"}}
node_speechprovider{{"Speech providers"}}

node_user -->|"interacts with"| node_app
node_app -->|"sends chat"| node_api
node_app -->|"uses voice input"| node_voice
node_api -->|"HTTP requests"| node_backend
node_backend -->|"routes chat"| node_chat
node_chat -->|"builds prompts"| node_prompt
node_chat -->|"requests completion"| node_llm
node_llm -->|"rotates keys"| node_keypool
node_chat -.->|"retrieves and stores"| node_memory
node_chat -->|"embeds text"| node_embeddings
node_chat -->|"chunks exchanges"| node_chunker
node_chat -->|"loads persona"| node_persona
node_chat -.->|"selects mood"| node_mood
node_chat -->|"enriches context"| node_tools
node_backend -->|"routes game API"| node_games
node_chat -.->|"synthesizes reply"| node_tts
node_tts -->|"calls providers"| node_speechprovider
node_chat -->|"stores audio"| node_audio
node_app -->|"renders avatar"| node_avatar
node_avatar -->|"loads custom avatars"| node_vrmstore
node_app -->|"opens inspector"| node_memoryui
node_memoryui -->|"calls memory API"| node_api
node_app -->|"manages notifications"| node_pushclient
node_pushclient -.->|"calls push endpoints"| node_backend
node_backend -.->|"serves push routes"| node_pushservice
node_backend -->|"evaluates on health ping"| node_scheduler
node_tools -->|"fetches public data"| node_externalapis
node_auth -->|"fetches allowed users"| node_api

click node_app "https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/App.jsx"
click node_api "https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/api.js"
click node_voice "https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/useVoiceInput.js"
click node_auth "https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/supabaseClient.js"
click node_backend "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/server.js"
click node_chat "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/orchestrator/chat.js"
click node_prompt "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/prompt.js"
click node_llm "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/llm/caller.js"
click node_keypool "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/keys/keyPool.js"
click node_memory "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/db/supabase.js"
click node_embeddings "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/rag/embeddings.js"
click node_chunker "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/rag/chunker.js"
click node_persona "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/personaSeed.js"
click node_mood "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/mood/engine.js"
click node_tools "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/tools/publicApis.js"
click node_games "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/games/index.js"
click node_tts "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/tts/index.js"
click node_audio "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/audioCache.js"
click node_avatar "https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/components/AvatarCanvas.jsx"
click node_vrmstore "https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/lib/vrmStore.js"
click node_memoryui "https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/components/MemoryInspector.jsx"
click node_pushclient "https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/lib/pushClient.js"
click node_pushservice "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/push/index.js"
click node_scheduler "https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/push/scheduler.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_api,node_voice,node_auth,node_user toneBlue
class node_backend,node_chat,node_prompt,node_llm,node_keypool toneAmber
class node_memory,node_embeddings,node_chunker,node_persona,node_mood,node_tools,node_games,node_tts,node_audio,node_externalapis toneMint
class node_avatar,node_vrmstore,node_memoryui,node_pushclient,node_pushservice,node_scheduler toneRose
class node_speechprovider toneIndigo
```

## Components

### Companion client

- [Companion UI](https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Voice input](https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/useVoiceInput.js): `frontend/src/useVoiceInput.js`
- [Supabase auth](https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/supabaseClient.js): `frontend/src/supabaseClient.js`

### Conversation runtime

- [HTTP API](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/server.js): `backend/src/server.js`
- [Chat orchestrator](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/orchestrator/chat.js): `backend/src/orchestrator/chat.js`
- [Prompt builder](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/prompt.js): `backend/src/prompt.js`
- [LLM caller](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/llm/caller.js): `backend/src/llm/caller.js`
- [Key pool](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/keys/keyPool.js): `backend/src/keys/keyPool.js`

### Persona services

- [RAG memory](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/db/supabase.js): `backend/src/db/supabase.js`
- [Embedding provider](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/rag/embeddings.js): `backend/src/rag/embeddings.js`
- [Memory chunker](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/rag/chunker.js): `backend/src/rag/chunker.js`
- [Persona data](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/personaSeed.js): `backend/src/personaSeed.js`
- [Mood engine](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/mood/engine.js): `backend/src/mood/engine.js`
- [Public API tools](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/tools/publicApis.js): `backend/src/tools/publicApis.js`
- [Chat games](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/games/index.js): `backend/src/games/index.js`
- [Speech synthesis](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/tts/index.js): `backend/src/tts/index.js`
- [Audio cache](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/audioCache.js): `backend/src/audioCache.js`

### Avatar and alerts

- [VRM renderer](https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/components/AvatarCanvas.jsx): `frontend/src/components/AvatarCanvas.jsx`
- [Avatar registry](https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/lib/vrmStore.js): `frontend/src/lib/vrmStore.js`
- [Memory inspector](https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/components/MemoryInspector.jsx): `frontend/src/components/MemoryInspector.jsx`
- [Push client](https://github.com/dakshgoyal1812/waguri/blob/main/frontend/src/lib/pushClient.js): `frontend/src/lib/pushClient.js`
- [Push service](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/push/index.js): `backend/src/push/index.js`
- [Push scheduler](https://github.com/dakshgoyal1812/waguri/blob/main/backend/src/push/scheduler.js): `backend/src/push/scheduler.js`

### Other components

- **User**
- **Public API providers**
- **Speech providers**

## Connections

- User → Companion UI: interacts with
- Companion UI → API client: sends chat (evidence: `frontend/src/api.js`)
- Companion UI → Voice input: uses voice input (evidence: `frontend/src/App.jsx`)
- API client → HTTP API: HTTP requests (evidence: `frontend/src/api.js`)
- HTTP API → Chat orchestrator: routes chat (evidence: `backend/src/server.js`)
- Chat orchestrator → Prompt builder: builds prompts (evidence: `backend/src/orchestrator/chat.js`)
- Chat orchestrator → LLM caller: requests completion (evidence: `backend/src/orchestrator/chat.js`)
- LLM caller → Key pool: rotates keys (evidence: `backend/src/llm/caller.js`)
- Chat orchestrator → RAG memory: retrieves and stores
- Chat orchestrator → Embedding provider: embeds text (evidence: `backend/src/orchestrator/chat.js`)
- Chat orchestrator → Memory chunker: chunks exchanges (evidence: `backend/src/orchestrator/chat.js`)
- Chat orchestrator → Persona data: loads persona (evidence: `backend/src/orchestrator/chat.js`)
- Chat orchestrator → Mood engine: selects mood
- Chat orchestrator → Public API tools: enriches context (evidence: `backend/src/orchestrator/chat.js`)
- HTTP API → Chat games: routes game API (evidence: `backend/src/server.js`)
- Chat orchestrator → Speech synthesis: synthesizes reply
- Speech synthesis → Speech providers: calls providers (evidence: `backend/src/tts/index.js`)
- Chat orchestrator → Audio cache: stores audio (evidence: `backend/src/orchestrator/chat.js`)
- Companion UI → VRM renderer: renders avatar (evidence: `frontend/src/App.jsx`)
- VRM renderer → Avatar registry: loads custom avatars (evidence: `frontend/src/components/AvatarCanvas.jsx`)
- Companion UI → Memory inspector: opens inspector (evidence: `frontend/src/App.jsx`)
- Memory inspector → API client: calls memory API (evidence: `frontend/src/components/MemoryInspector.jsx`)
- Companion UI → Push client: manages notifications (evidence: `frontend/src/App.jsx`)
- Push client → HTTP API: calls push endpoints
- HTTP API → Push service: serves push routes (evidence: `backend/src/server.js`)
- HTTP API → Push scheduler: evaluates on health ping (evidence: `backend/src/server.js`)
- Public API tools → Public API providers: fetches public data (evidence: `backend/src/tools/publicApis.js`)
- Supabase auth → API client: fetches allowed users (evidence: `frontend/src/supabaseClient.js`)
