# anhe2021212-spec/tidal_echo architecture

> Architecture diagram of the GitHub repository anhe2021212-spec/tidal_echo, 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/anhe2021212-spec/tidal_echo
- Repository: https://github.com/anhe2021212-spec/tidal_echo

## Overview

Companion Channel is a private, single-user messaging system connecting a phone PWA to an AI companion through a self-hosted relay. The main workflow is PWA message → relay persistence and SSE delivery → AI reply through the relay → PWA display or lock-screen push. The relay can route messages to either the Claude Code channel or the optional API-based model loop. README statements support the major unsampled PWA and API-loop capabilities; edges reflect documented or excerpted relationships rather than inferred imports.

Main entry points: [`backend/app.py`](https://github.com/anhe2021212-spec/tidal_echo/blob/main/backend/app.py) (Message relay), [`channel/server.ts`](https://github.com/anhe2021212-spec/tidal_echo/blob/main/channel/server.ts) (Channel MCP plugin), [`examples/api_loop.py`](https://github.com/anhe2021212-spec/tidal_echo/blob/main/examples/api_loop.py) (Model and tool loop), [`web/index.html`](https://github.com/anhe2021212-spec/tidal_echo/blob/main/web/index.html) (Chat PWA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Phone PWA"]
  node_pwa["Chat PWA<br/>[index.html]"]
  node_service_worker["Offline and push<br/>[sw.js]"]
end

subgraph group_relay["Relay Backend"]
  node_relay_service["Message relay<br/>[app.py]"]
  node_message_store[("Message database<br/>[app.py]")]
  node_uploads[("Attachment storage<br/>[app.py]")]
end

subgraph group_desktop["Claude Channel"]
  node_channel_plugin["Channel MCP plugin<br/>[server.ts]"]
  node_plugin_inbox[("Local attachment inbox<br/>[server.ts]")]
end

subgraph group_api["API Body"]
  node_api_loop["Model and tool loop<br/>[api_loop.py]"]
  node_any_llm_bridge["Alternate LLM bridge<br/>[bridge_any_llm.py]"]
end

node_person(("Phone user"))
node_push_service["Web Push service"]
node_claude(("Claude Code session"))
node_llm["OpenAI-compatible model"]
node_mcp_servers["MCP servers"]

node_person -->|"sends messages"| node_pwa
node_pwa -->|"sends messages"| node_relay_service
node_relay_service -->|"persists messages"| node_message_store
node_relay_service -->|"streams messages"| node_channel_plugin
node_channel_plugin -->|"posts replies"| node_relay_service
node_relay_service -->|"streams replies"| node_pwa
node_relay_service -->|"sends push"| node_service_worker
node_service_worker -->|"shows notifications"| node_person
node_pwa -->|"uploads attachments"| node_relay_service
node_relay_service -->|"stores attachments"| node_uploads
node_channel_plugin -->|"saves attachments"| node_plugin_inbox
node_channel_plugin -->|"delivers channel blocks"| node_claude
node_claude -->|"invokes reply tools"| node_channel_plugin
node_relay_service -->|"routes messages"| node_api_loop
node_api_loop -->|"requests completions"| node_llm
node_api_loop -->|"calls tools"| node_mcp_servers
node_api_loop -.->|"posts replies"| node_relay_service
node_any_llm_bridge -->|"bridges SSE"| node_relay_service
node_relay_service -->|"sends notifications"| node_push_service

click node_pwa "https://github.com/anhe2021212-spec/tidal_echo/blob/main/web/index.html"
click node_service_worker "https://github.com/anhe2021212-spec/tidal_echo/blob/main/web/sw.js"
click node_relay_service "https://github.com/anhe2021212-spec/tidal_echo/blob/main/backend/app.py"
click node_message_store "https://github.com/anhe2021212-spec/tidal_echo/blob/main/backend/app.py"
click node_uploads "https://github.com/anhe2021212-spec/tidal_echo/blob/main/backend/app.py"
click node_channel_plugin "https://github.com/anhe2021212-spec/tidal_echo/blob/main/channel/server.ts"
click node_plugin_inbox "https://github.com/anhe2021212-spec/tidal_echo/blob/main/channel/server.ts"
click node_api_loop "https://github.com/anhe2021212-spec/tidal_echo/blob/main/examples/api_loop.py"
click node_any_llm_bridge "https://github.com/anhe2021212-spec/tidal_echo/blob/main/examples/bridge_any_llm.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_pwa,node_service_worker,node_person toneBlue
class node_relay_service,node_message_store,node_uploads toneAmber
class node_channel_plugin,node_plugin_inbox,node_mcp_servers toneMint
class node_api_loop,node_any_llm_bridge toneRose
class node_push_service,node_claude,node_llm toneIndigo
```

## Components

### Phone PWA

- [Chat PWA](https://github.com/anhe2021212-spec/tidal_echo/blob/main/web/index.html): `web/index.html`
- [Offline and push](https://github.com/anhe2021212-spec/tidal_echo/blob/main/web/sw.js): `web/sw.js`

### Relay Backend

- [Message relay](https://github.com/anhe2021212-spec/tidal_echo/blob/main/backend/app.py): `backend/app.py`
- [Message database](https://github.com/anhe2021212-spec/tidal_echo/blob/main/backend/app.py): `backend/app.py`
- [Attachment storage](https://github.com/anhe2021212-spec/tidal_echo/blob/main/backend/app.py): `backend/app.py`

### Claude Channel

- [Channel MCP plugin](https://github.com/anhe2021212-spec/tidal_echo/blob/main/channel/server.ts): `channel/server.ts`
- [Local attachment inbox](https://github.com/anhe2021212-spec/tidal_echo/blob/main/channel/server.ts): `channel/server.ts`

### API Body

- [Model and tool loop](https://github.com/anhe2021212-spec/tidal_echo/blob/main/examples/api_loop.py): `examples/api_loop.py`
- [Alternate LLM bridge](https://github.com/anhe2021212-spec/tidal_echo/blob/main/examples/bridge_any_llm.py): `examples/bridge_any_llm.py`

### Other components

- **Phone user**
- **Web Push service**
- **Claude Code session**
- **OpenAI-compatible model**
- **MCP servers**

## Connections

- Phone user → Chat PWA: sends messages (evidence: `README.md`)
- Chat PWA → Message relay: sends messages (evidence: `README.md`)
- Message relay → Message database: persists messages (evidence: `README.md`)
- Message relay → Channel MCP plugin: streams messages (evidence: `README.md`)
- Channel MCP plugin → Message relay: posts replies (evidence: `channel/server.ts`)
- Message relay → Chat PWA: streams replies (evidence: `README.md`)
- Message relay → Offline and push: sends push (evidence: `web/sw.js`)
- Offline and push → Phone user: shows notifications (evidence: `web/sw.js`)
- Chat PWA → Message relay: uploads attachments (evidence: `README.md`)
- Message relay → Attachment storage: stores attachments (evidence: `README.md`)
- Channel MCP plugin → Local attachment inbox: saves attachments (evidence: `channel/server.ts`)
- Channel MCP plugin → Claude Code session: delivers channel blocks (evidence: `channel/server.ts`)
- Claude Code session → Channel MCP plugin: invokes reply tools (evidence: `README.md`)
- Message relay → Model and tool loop: routes messages (evidence: `README.md`)
- Model and tool loop → OpenAI-compatible model: requests completions (evidence: `README.md`)
- Model and tool loop → MCP servers: calls tools (evidence: `README.md`)
- Model and tool loop → Message relay: posts replies
- Alternate LLM bridge → Message relay: bridges SSE (evidence: `README.md`)
- Message relay → Web Push service: sends notifications
