# tjing9430/cc-companion-app architecture

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

- Interactive diagram: https://gitdiagram.com/tjing9430/cc-companion-app
- Repository: https://github.com/tjing9430/cc-companion-app

## Overview

CC Companion is a self-hosted mobile AI companion: users chat privately or in groups, receive streamed agent responses, and manage memory, documents, settings, and console activity through a web app. The HTTP server routes requests into domain modules, which use shared state and local JSON/SQLite storage; chat can use OpenAI-compatible services, Claude Code Bridge, or DSH. The README documents additional attachment, search, file-editing, theme, and PWA capabilities. Several domain links are documented rather than visible in sampled handlers; those are marked dashed.

Main entry points: [`public/app.js`](https://github.com/tjing9430/cc-companion-app/blob/master/public/app.js) (Web app shell), [`server.js`](https://github.com/tjing9430/cc-companion-app/blob/master/server.js) (HTTP server), [`lib/chat.js`](https://github.com/tjing9430/cc-companion-app/blob/master/lib/chat.js) (Chat orchestration), [`lib/state.js`](https://github.com/tjing9430/cc-companion-app/blob/master/lib/state.js) (Application state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["Web app shell<br/>[app.js]"]
  node_chatui["Chat views<br/>[chat-view.js]"]
  node_memoryui["Memory views<br/>[memory-view.js]"]
  node_homeui["Home views<br/>[home-view.js]"]
  node_consoleui["Console views<br/>[console-view.js]"]
  node_settingsui["Settings views<br/>[settings-view.js]"]
  node_moreui["More views<br/>[more-view.js]"]
  node_workflowui["Workflow views<br/>[workflow-view.js]"]
  node_pwa["PWA service worker<br/>[sw.js]"]
end

subgraph group_server["HTTP and domains"]
  node_server["HTTP server<br/>[server.js]"]
  node_chat["Chat orchestration<br/>[chat.js]"]
  node_messages["Message operations<br/>[messages.js]"]
  node_memory["Memory domain<br/>[memory.js]"]
  node_docs["Documents<br/>[docs.js]"]
  node_console["Console events<br/>[console.js]"]
  node_config["Config library<br/>[config-library.js]"]
end

subgraph group_data["State and persistence"]
  node_state["Application state<br/>[state.js]"]
  node_sqlite[("SQLite backend<br/>[store-sqlite.js]")]
  node_jsondata[("JSON data files")]
end

subgraph group_agents["Agent integrations"]
  node_openai(("OpenAI-compatible API"))
  node_adapter["OpenAI adapter"]
  node_bridge["Claude Code Bridge<br/>[index.js]"]
  node_dsh["DSH integration<br/>[dsh.js]"]
  node_dshworker["DSH worker<br/>[dsh-worker.py]"]
end

subgraph group_operations["Companion capabilities"]
  node_heartbeat["Heartbeat<br/>[heartbeat.js]"]
  node_forge["Session forge<br/>[forge.js]"]
  node_rotation["Session rotation"]
  node_embedding["Embedding service<br/>[embedding.js]"]
  node_sse["Event streaming<br/>[sse.js]"]
end

node_user(("Companion user"))

node_user -->|"uses"| node_webapp
node_webapp -->|"renders"| node_chatui
node_webapp -->|"renders"| node_memoryui
node_webapp -->|"renders"| node_homeui
node_webapp -->|"renders"| node_consoleui
node_webapp -->|"renders"| node_settingsui
node_webapp -->|"loads"| node_moreui
node_webapp -.->|"renders"| node_workflowui
node_webapp -.->|"requests APIs"| node_server
node_webapp -.->|"registers"| node_pwa
node_server -->|"routes chat"| node_chat
node_server -->|"routes messages"| node_messages
node_server -->|"routes memory"| node_memory
node_server -->|"routes documents"| node_docs
node_server -->|"records events"| node_console
node_server -->|"routes config"| node_config
node_server -->|"triggers"| node_heartbeat
node_server -.->|"runs rotation"| node_rotation
node_server -->|"broadcasts"| node_sse
node_chat -->|"reads and writes"| node_state
node_chat -->|"uses"| node_messages
node_chat -->|"retrieves context"| node_memory
node_chat -->|"retrieves documents"| node_docs
node_chat -->|"dispatches"| node_dsh
node_chat -->|"streams"| node_sse
node_memory -->|"reads and writes"| node_state
node_memory -->|"embeds and searches"| node_embedding
node_memory -->|"broadcasts updates"| node_sse
node_docs -->|"reads and writes"| node_state
node_docs -->|"uses vectors"| node_embedding
node_docs -->|"broadcasts updates"| node_sse
node_console -->|"persists events"| node_state
node_console -->|"broadcasts events"| node_sse
node_rotation -->|"rotates session"| node_forge
node_rotation -->|"records rotation"| node_console
node_state -->|"opens backend"| node_sqlite
node_state -.->|"loads and saves"| node_jsondata
node_chat -.->|"calls model"| node_openai
node_adapter -->|"implements protocol"| node_openai
node_chat -.->|"uses compatible endpoint"| node_bridge
node_chat -.->|"runs worker"| node_dshworker
node_dsh -.->|"delegates"| node_dshworker

click node_webapp "https://github.com/tjing9430/cc-companion-app/blob/master/public/app.js"
click node_chatui "https://github.com/tjing9430/cc-companion-app/blob/master/public/js/chat-view.js"
click node_memoryui "https://github.com/tjing9430/cc-companion-app/blob/master/public/js/memory-view.js"
click node_homeui "https://github.com/tjing9430/cc-companion-app/blob/master/public/js/home-view.js"
click node_consoleui "https://github.com/tjing9430/cc-companion-app/blob/master/public/js/console-view.js"
click node_settingsui "https://github.com/tjing9430/cc-companion-app/blob/master/public/js/settings-view.js"
click node_moreui "https://github.com/tjing9430/cc-companion-app/blob/master/public/js/more-view.js"
click node_workflowui "https://github.com/tjing9430/cc-companion-app/blob/master/public/js/workflow-view.js"
click node_server "https://github.com/tjing9430/cc-companion-app/blob/master/server.js"
click node_chat "https://github.com/tjing9430/cc-companion-app/blob/master/lib/chat.js"
click node_messages "https://github.com/tjing9430/cc-companion-app/blob/master/lib/messages.js"
click node_memory "https://github.com/tjing9430/cc-companion-app/blob/master/lib/memory.js"
click node_docs "https://github.com/tjing9430/cc-companion-app/blob/master/lib/docs.js"
click node_console "https://github.com/tjing9430/cc-companion-app/blob/master/lib/console.js"
click node_config "https://github.com/tjing9430/cc-companion-app/blob/master/lib/config-library.js"
click node_heartbeat "https://github.com/tjing9430/cc-companion-app/blob/master/lib/heartbeat.js"
click node_forge "https://github.com/tjing9430/cc-companion-app/blob/master/lib/forge.js"
click node_rotation "https://github.com/tjing9430/cc-companion-app/blob/master/lib/session-rotation.js"
click node_embedding "https://github.com/tjing9430/cc-companion-app/blob/master/lib/embedding.js"
click node_sse "https://github.com/tjing9430/cc-companion-app/blob/master/lib/sse.js"
click node_state "https://github.com/tjing9430/cc-companion-app/blob/master/lib/state.js"
click node_sqlite "https://github.com/tjing9430/cc-companion-app/blob/master/lib/store-sqlite.js"
click node_adapter "https://github.com/tjing9430/cc-companion-app/blob/master/adapters/openai-compatible.template.js"
click node_bridge "https://github.com/tjing9430/cc-companion-app/blob/master/bridge/index.js"
click node_dsh "https://github.com/tjing9430/cc-companion-app/blob/master/lib/dsh.js"
click node_dshworker "https://github.com/tjing9430/cc-companion-app/blob/master/adapters/dsh-worker.py"
click node_pwa "https://github.com/tjing9430/cc-companion-app/blob/master/public/sw.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_webapp,node_chatui,node_memoryui,node_homeui,node_consoleui,node_settingsui,node_moreui,node_workflowui,node_pwa,node_user toneBlue
class node_server,node_chat,node_messages,node_memory,node_docs,node_console,node_config toneAmber
class node_state,node_sqlite,node_jsondata toneMint
class node_openai,node_adapter,node_bridge,node_dsh,node_dshworker toneRose
class node_heartbeat,node_forge,node_rotation,node_embedding,node_sse toneIndigo
```

## Components

### Web client

- [Web app shell](https://github.com/tjing9430/cc-companion-app/blob/master/public/app.js): `public/app.js`
- [Chat views](https://github.com/tjing9430/cc-companion-app/blob/master/public/js/chat-view.js): `public/js/chat-view.js`
- [Memory views](https://github.com/tjing9430/cc-companion-app/blob/master/public/js/memory-view.js): `public/js/memory-view.js`
- [Home views](https://github.com/tjing9430/cc-companion-app/blob/master/public/js/home-view.js): `public/js/home-view.js`
- [Console views](https://github.com/tjing9430/cc-companion-app/blob/master/public/js/console-view.js): `public/js/console-view.js`
- [Settings views](https://github.com/tjing9430/cc-companion-app/blob/master/public/js/settings-view.js): `public/js/settings-view.js`
- [More views](https://github.com/tjing9430/cc-companion-app/blob/master/public/js/more-view.js): `public/js/more-view.js`
- [Workflow views](https://github.com/tjing9430/cc-companion-app/blob/master/public/js/workflow-view.js): `public/js/workflow-view.js`
- [PWA service worker](https://github.com/tjing9430/cc-companion-app/blob/master/public/sw.js): `public/sw.js`

### HTTP and domains

- [HTTP server](https://github.com/tjing9430/cc-companion-app/blob/master/server.js): `server.js`
- [Chat orchestration](https://github.com/tjing9430/cc-companion-app/blob/master/lib/chat.js): `lib/chat.js`
- [Message operations](https://github.com/tjing9430/cc-companion-app/blob/master/lib/messages.js): `lib/messages.js`
- [Memory domain](https://github.com/tjing9430/cc-companion-app/blob/master/lib/memory.js): `lib/memory.js`
- [Documents](https://github.com/tjing9430/cc-companion-app/blob/master/lib/docs.js): `lib/docs.js`
- [Console events](https://github.com/tjing9430/cc-companion-app/blob/master/lib/console.js): `lib/console.js`
- [Config library](https://github.com/tjing9430/cc-companion-app/blob/master/lib/config-library.js): `lib/config-library.js`

### State and persistence

- [Application state](https://github.com/tjing9430/cc-companion-app/blob/master/lib/state.js): `lib/state.js`
- [SQLite backend](https://github.com/tjing9430/cc-companion-app/blob/master/lib/store-sqlite.js): `lib/store-sqlite.js`
- **JSON data files**

### Agent integrations

- **OpenAI-compatible API**
- [OpenAI adapter](https://github.com/tjing9430/cc-companion-app/blob/master/adapters/openai-compatible.template.js): `adapters/openai-compatible.template.js`
- [Claude Code Bridge](https://github.com/tjing9430/cc-companion-app/blob/master/bridge/index.js): `bridge/index.js`
- [DSH integration](https://github.com/tjing9430/cc-companion-app/blob/master/lib/dsh.js): `lib/dsh.js`
- [DSH worker](https://github.com/tjing9430/cc-companion-app/blob/master/adapters/dsh-worker.py): `adapters/dsh-worker.py`

### Companion capabilities

- [Heartbeat](https://github.com/tjing9430/cc-companion-app/blob/master/lib/heartbeat.js): `lib/heartbeat.js`
- [Session forge](https://github.com/tjing9430/cc-companion-app/blob/master/lib/forge.js): `lib/forge.js`
- [Session rotation](https://github.com/tjing9430/cc-companion-app/blob/master/lib/session-rotation.js): `lib/session-rotation.js`
- [Embedding service](https://github.com/tjing9430/cc-companion-app/blob/master/lib/embedding.js): `lib/embedding.js`
- [Event streaming](https://github.com/tjing9430/cc-companion-app/blob/master/lib/sse.js): `lib/sse.js`

### Other components

- **Companion user**

## Connections

- Companion user → Web app shell: uses (evidence: `README.md`)
- Web app shell → Chat views: renders (evidence: `public/app.js`)
- Web app shell → Memory views: renders (evidence: `public/app.js`)
- Web app shell → Home views: renders (evidence: `public/app.js`)
- Web app shell → Console views: renders (evidence: `public/app.js`)
- Web app shell → Settings views: renders (evidence: `public/app.js`)
- Web app shell → More views: loads (evidence: `public/app.js`)
- Web app shell → Workflow views: renders
- Web app shell → HTTP server: requests APIs
- Web app shell → PWA service worker: registers
- HTTP server → Chat orchestration: routes chat (evidence: `server.js`)
- HTTP server → Message operations: routes messages (evidence: `server.js`)
- HTTP server → Memory domain: routes memory (evidence: `server.js`)
- HTTP server → Documents: routes documents (evidence: `server.js`)
- HTTP server → Console events: records events (evidence: `server.js`)
- HTTP server → Config library: routes config (evidence: `server.js`)
- HTTP server → Heartbeat: triggers (evidence: `server.js`)
- HTTP server → Session rotation: runs rotation (evidence: `server.js`)
- HTTP server → Event streaming: broadcasts (evidence: `server.js`)
- Chat orchestration → Application state: reads and writes (evidence: `lib/chat.js`)
- Chat orchestration → Message operations: uses (evidence: `lib/chat.js`)
- Chat orchestration → Memory domain: retrieves context (evidence: `lib/chat.js`)
- Chat orchestration → Documents: retrieves documents (evidence: `lib/chat.js`)
- Chat orchestration → DSH integration: dispatches (evidence: `lib/chat.js`)
- Chat orchestration → Event streaming: streams (evidence: `lib/chat.js`)
- Memory domain → Application state: reads and writes (evidence: `lib/memory.js`)
- Memory domain → Embedding service: embeds and searches (evidence: `lib/memory.js`)
- Memory domain → Event streaming: broadcasts updates (evidence: `lib/memory.js`)
- Documents → Application state: reads and writes (evidence: `lib/docs.js`)
- Documents → Embedding service: uses vectors (evidence: `lib/docs.js`)
- Documents → Event streaming: broadcasts updates (evidence: `lib/docs.js`)
- Console events → Application state: persists events (evidence: `lib/console.js`)
- Console events → Event streaming: broadcasts events (evidence: `lib/console.js`)
- Session rotation → Session forge: rotates session (evidence: `lib/session-rotation.js`)
- Session rotation → Console events: records rotation (evidence: `lib/session-rotation.js`)
- Application state → SQLite backend: opens backend (evidence: `lib/state.js`)
- Application state → JSON data files: loads and saves
- Chat orchestration → OpenAI-compatible API: calls model
- OpenAI adapter → OpenAI-compatible API: implements protocol (evidence: `README.md`)
- Chat orchestration → Claude Code Bridge: uses compatible endpoint
- Chat orchestration → DSH worker: runs worker
- DSH integration → DSH worker: delegates