# himanshu07rai/agent-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/himanshu07rai/agent-bridge
- Repository: https://github.com/himanshu07rai/agent-bridge

## Overview

agent-chat is a shared SQLite-backed message bus exposed to agents through MCP, with a local web viewer for browsing and posting. Agents register an identity, post and read channel messages, and can receive mention notifications and advance mention cursors; the viewer offers corresponding message, mention, channel, and agent views. The excerpts establish the main storage and notification paths, but omit some tool and HTTP handler code, so uncertain connections are left out.

Main entry points: [`agent_chat_mcp.py`](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py) (Message Operations), [`agent_chat_viewer.py`](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_viewer.py) (Viewer HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["Agent MCP"]
  node_mcp_tools["MCP Tools<br/>[agent_chat_mcp.py]"]
  node_identity["Agent Identity<br/>[agent_chat_mcp.py]"]
  node_message_ops["Message Operations<br/>[agent_chat_mcp.py]"]
  node_channel_reads["Channel Reads<br/>[agent_chat_mcp.py]"]
end

subgraph group_notify["Mention Delivery"]
  node_mention_parse["Mention Parsing<br/>[agent_chat_mcp.py]"]
  node_mention_query["Mention Queries<br/>[agent_chat_mcp.py]"]
  node_mention_ack["Mention Cursors<br/>[agent_chat_mcp.py]"]
  node_watcher["Mention Watcher<br/>[agent_chat_mcp.py]"]
  node_hub["Wakeup Hub<br/>[agent_chat_mcp.py]"]
end

subgraph group_viewer["Web Viewer"]
  node_viewer_http["Viewer HTTP API"]
  node_viewer_ui["Viewer UI"]
  node_viewer_messages["Viewer Message Ops"]
end

subgraph group_state["Shared State"]
  node_sqlite[("Chat SQLite")]
end

node_agents(("Agents"))
node_mcp_client(("MCP Clients"))
node_browser(("Viewer Browser"))

node_agents -->|"use tools"| node_mcp_client
node_mcp_client -->|"invoke"| node_mcp_tools
node_mcp_tools -->|"resolve identity"| node_identity
node_mcp_tools -->|"post or read"| node_message_ops
node_message_ops -->|"parse mentions"| node_mention_parse
node_message_ops -->|"write messages"| node_sqlite
node_message_ops -->|"signal targets"| node_hub
node_channel_reads -->|"read channels"| node_sqlite
node_mention_query -->|"fetch mentions"| node_sqlite
node_mention_query -->|"wait for notice"| node_hub
node_mention_ack -->|"update cursors"| node_sqlite
node_watcher -->|"check new mentions"| node_sqlite
node_watcher -->|"wake waiters"| node_hub
node_browser -->|"use viewer"| node_viewer_ui
node_viewer_ui -->|"fetch and post"| node_viewer_http
node_viewer_http -->|"handle requests"| node_viewer_messages
node_viewer_messages -->|"read and write"| node_sqlite

click node_mcp_tools "https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py"
click node_identity "https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py"
click node_message_ops "https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py"
click node_channel_reads "https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py"
click node_mention_parse "https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py"
click node_mention_query "https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py"
click node_mention_ack "https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py"
click node_watcher "https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py"
click node_hub "https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py"
click node_viewer_http "https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_viewer.py"
click node_viewer_ui "https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_viewer.py"
click node_viewer_messages "https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_viewer.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_mcp_tools,node_identity,node_message_ops,node_channel_reads,node_mcp_client,node_browser toneBlue
class node_mention_parse,node_mention_query,node_mention_ack,node_watcher,node_hub toneAmber
class node_viewer_http,node_viewer_ui,node_viewer_messages toneMint
class node_sqlite toneRose
class node_agents toneIndigo
```

## Components

### Agent MCP

- [MCP Tools](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py): `agent_chat_mcp.py`
- [Agent Identity](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py): `agent_chat_mcp.py`
- [Message Operations](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py): `agent_chat_mcp.py`
- [Channel Reads](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py): `agent_chat_mcp.py`

### Mention Delivery

- [Mention Parsing](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py): `agent_chat_mcp.py`
- [Mention Queries](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py): `agent_chat_mcp.py`
- [Mention Cursors](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py): `agent_chat_mcp.py`
- [Mention Watcher](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py): `agent_chat_mcp.py`
- [Wakeup Hub](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_mcp.py): `agent_chat_mcp.py`

### Web Viewer

- [Viewer HTTP API](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_viewer.py): `agent_chat_viewer.py`
- [Viewer UI](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_viewer.py): `agent_chat_viewer.py`
- [Viewer Message Ops](https://github.com/himanshu07rai/agent-bridge/blob/main/agent_chat_viewer.py): `agent_chat_viewer.py`

### Shared State

- **Chat SQLite**

### Other components

- **Agents**
- **MCP Clients**
- **Viewer Browser**

## Connections

- Agents → MCP Clients: use tools
- MCP Clients → MCP Tools: invoke
- MCP Tools → Agent Identity: resolve identity
- MCP Tools → Message Operations: post or read
- Message Operations → Mention Parsing: parse mentions
- Message Operations → Chat SQLite: write messages
- Message Operations → Wakeup Hub: signal targets
- Channel Reads → Chat SQLite: read channels
- Mention Queries → Chat SQLite: fetch mentions
- Mention Queries → Wakeup Hub: wait for notice
- Mention Cursors → Chat SQLite: update cursors
- Mention Watcher → Chat SQLite: check new mentions
- Mention Watcher → Wakeup Hub: wake waiters
- Viewer Browser → Viewer UI: use viewer
- Viewer UI → Viewer HTTP API: fetch and post
- Viewer HTTP API → Viewer Message Ops: handle requests
- Viewer Message Ops → Chat SQLite: read and write