# openonion/oo-chat architecture

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

- Interactive diagram: https://gitdiagram.com/openonion/oo-chat
- Repository: https://github.com/openonion/oo-chat

## Overview

oo-chat is a Next.js client for discovering ConnectOnion agents and chatting with them. The main flow is address entry and profile lookup, then a session page delegates connection, streaming, and session persistence to @connectonion/react through useAgentSDK; chat UI renders the normalized events and handles approvals and user prompts. Separate surfaces support identity and settings, agent discovery, recent-chat synchronization, dashboards, and agent wikis. The SDK and relay internals are external; several UI subsystems are represented from the tree and README rather than sampled implementation.

Main entry points: [`app/[address]/page.tsx`](https://github.com/openonion/oo-chat/blob/main/app/%5Baddress%5D/page.tsx) (Agent profile), [`app/[address]/[sessionId]/page.tsx`](https://github.com/openonion/oo-chat/blob/main/app/%5Baddress%5D/%5BsessionId%5D/page.tsx) (Session route), [`hooks/use-agent-info.ts`](https://github.com/openonion/oo-chat/blob/main/hooks/use-agent-info.ts) (Agent info lookup), [`app/page.tsx`](https://github.com/openonion/oo-chat/blob/main/app/page.tsx) (Agent picker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_navigation["Navigation and discovery"]
  node_agent_picker["Agent picker<br/>[page.tsx]"]
  node_agent_profile["Agent profile<br/>[page.tsx]"]
  node_agent_lookup["Agent info lookup<br/>[use-agent-info.ts]"]
  node_explore["Agent discovery<br/>[page.tsx]"]
  node_online_agents["Online agents API<br/>[route.ts]"]
end

subgraph group_chat["Chat experience"]
  node_session_page["Session route<br/>[page.tsx]"]
  node_sdk_adapter["Agent SDK adapter<br/>[use-agent-sdk.ts]"]
  node_chat_ui["Chat interface<br/>[chat.tsx]"]
  node_message_rendering["Message rendering<br/>[chat-messages.tsx]"]
  node_workroom["Coding workroom"]
  node_onboarding["Onboarding gate<br/>[onboard-gate.tsx]"]
end

subgraph group_identity["Identity and session index"]
  node_identity_hook["Browser identity<br/>[use-identity.ts]"]
  node_auth_api["Authentication proxy<br/>[route.ts]"]
  node_chat_store[("Recent chat index<br/>[chat-store.ts]")]
  node_recent_sync["Recent chat sync"]
  node_settings["Settings<br/>[page.tsx]"]
end

subgraph group_agent_surfaces["Agent workspaces"]
  node_dashboard["Dashboard pane<br/>[dashboard-pane.tsx]"]
  node_workspace["Workspace shell"]
  node_wiki["Agent wiki<br/>[wiki-view.tsx]"]
  node_wiki_route["Wiki route<br/>[page.tsx]"]
end

node_user(("User"))
node_connectonion_sdk["ConnectOnion React SDK"]
node_relay["Agent relay"]
node_remote_agent(("Remote agent"))

node_user -->|"chooses address"| node_agent_picker
node_agent_picker -->|"opens profile"| node_agent_profile
node_agent_picker -->|"loads agent info"| node_agent_lookup
node_agent_profile -->|"loads agent info"| node_agent_lookup
node_agent_lookup -->|"fetches profile"| node_connectonion_sdk
node_user -->|"browses agents"| node_explore
node_explore -.->|"requests online list"| node_online_agents
node_online_agents -->|"queries capabilities"| node_connectonion_sdk
node_agent_profile -->|"starts session"| node_session_page
node_session_page -->|"binds session"| node_sdk_adapter
node_sdk_adapter -->|"opens agent session"| node_connectonion_sdk
node_connectonion_sdk -->|"streams over WebSocket"| node_relay
node_relay -->|"relays events"| node_remote_agent
node_session_page -->|"renders conversation"| node_chat_ui
node_chat_ui -.->|"renders messages"| node_message_rendering
node_message_rendering -.->|"renders workroom"| node_workroom
node_agent_profile -->|"gates access"| node_onboarding
node_user -->|"manages identity"| node_identity_hook
node_identity_hook -->|"authenticates via"| node_auth_api
node_identity_hook -->|"stores profile state"| node_chat_store
node_recent_sync -->|"reconciles sessions"| node_chat_store
node_connectonion_sdk -->|"provides host history"| node_recent_sync
node_user -->|"configures account"| node_settings
node_session_page -->|"hosts chat pane"| node_workspace
node_workspace -->|"shows dashboard"| node_dashboard
node_wiki_route -->|"renders wiki"| node_wiki
node_wiki_route -->|"loads agent info"| node_agent_lookup

click node_agent_picker "https://github.com/openonion/oo-chat/blob/main/app/page.tsx"
click node_agent_profile "https://github.com/openonion/oo-chat/blob/main/app/%5Baddress%5D/page.tsx"
click node_agent_lookup "https://github.com/openonion/oo-chat/blob/main/hooks/use-agent-info.ts"
click node_explore "https://github.com/openonion/oo-chat/blob/main/app/explore/page.tsx"
click node_online_agents "https://github.com/openonion/oo-chat/blob/main/app/api/agents/online/route.ts"
click node_session_page "https://github.com/openonion/oo-chat/blob/main/app/%5Baddress%5D/%5BsessionId%5D/page.tsx"
click node_sdk_adapter "https://github.com/openonion/oo-chat/blob/main/components/chat/use-agent-sdk.ts"
click node_chat_ui "https://github.com/openonion/oo-chat/blob/main/components/chat/chat.tsx"
click node_message_rendering "https://github.com/openonion/oo-chat/blob/main/components/chat/chat-messages.tsx"
click node_workroom "https://github.com/openonion/oo-chat/blob/main/components/chat/messages/coding-agent-workroom.tsx"
click node_onboarding "https://github.com/openonion/oo-chat/blob/main/components/chat/onboard-gate.tsx"
click node_identity_hook "https://github.com/openonion/oo-chat/blob/main/hooks/use-identity.ts"
click node_auth_api "https://github.com/openonion/oo-chat/blob/main/app/api/auth/route.ts"
click node_chat_store "https://github.com/openonion/oo-chat/blob/main/store/chat-store.ts"
click node_recent_sync "https://github.com/openonion/oo-chat/blob/main/hooks/use-recent-chat-sync.ts"
click node_settings "https://github.com/openonion/oo-chat/blob/main/app/settings/page.tsx"
click node_dashboard "https://github.com/openonion/oo-chat/blob/main/components/dashboard/dashboard-pane.tsx"
click node_workspace "https://github.com/openonion/oo-chat/blob/main/components/dashboard/workspace-shell.tsx"
click node_wiki "https://github.com/openonion/oo-chat/blob/main/components/wiki/wiki-view.tsx"
click node_wiki_route "https://github.com/openonion/oo-chat/blob/main/app/%5Baddress%5D/wiki/page.tsx"

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_agent_picker,node_agent_profile,node_agent_lookup,node_explore,node_online_agents,node_user toneBlue
class node_session_page,node_sdk_adapter,node_chat_ui,node_message_rendering,node_workroom,node_onboarding toneAmber
class node_identity_hook,node_auth_api,node_chat_store,node_recent_sync,node_settings toneMint
class node_dashboard,node_workspace,node_wiki,node_wiki_route toneRose
class node_connectonion_sdk,node_relay,node_remote_agent toneIndigo
```

## Components

### Navigation and discovery

- [Agent picker](https://github.com/openonion/oo-chat/blob/main/app/page.tsx): `app/page.tsx`
- [Agent profile](https://github.com/openonion/oo-chat/blob/main/app/%5Baddress%5D/page.tsx): `app/[address]/page.tsx`
- [Agent info lookup](https://github.com/openonion/oo-chat/blob/main/hooks/use-agent-info.ts): `hooks/use-agent-info.ts`
- [Agent discovery](https://github.com/openonion/oo-chat/blob/main/app/explore/page.tsx): `app/explore/page.tsx`
- [Online agents API](https://github.com/openonion/oo-chat/blob/main/app/api/agents/online/route.ts): `app/api/agents/online/route.ts`

### Chat experience

- [Session route](https://github.com/openonion/oo-chat/blob/main/app/%5Baddress%5D/%5BsessionId%5D/page.tsx): `app/[address]/[sessionId]/page.tsx`
- [Agent SDK adapter](https://github.com/openonion/oo-chat/blob/main/components/chat/use-agent-sdk.ts): `components/chat/use-agent-sdk.ts`
- [Chat interface](https://github.com/openonion/oo-chat/blob/main/components/chat/chat.tsx): `components/chat/chat.tsx`
- [Message rendering](https://github.com/openonion/oo-chat/blob/main/components/chat/chat-messages.tsx): `components/chat/chat-messages.tsx`
- [Coding workroom](https://github.com/openonion/oo-chat/blob/main/components/chat/messages/coding-agent-workroom.tsx): `components/chat/messages/coding-agent-workroom.tsx`
- [Onboarding gate](https://github.com/openonion/oo-chat/blob/main/components/chat/onboard-gate.tsx): `components/chat/onboard-gate.tsx`

### Identity and session index

- [Browser identity](https://github.com/openonion/oo-chat/blob/main/hooks/use-identity.ts): `hooks/use-identity.ts`
- [Authentication proxy](https://github.com/openonion/oo-chat/blob/main/app/api/auth/route.ts): `app/api/auth/route.ts`
- [Recent chat index](https://github.com/openonion/oo-chat/blob/main/store/chat-store.ts): `store/chat-store.ts`
- [Recent chat sync](https://github.com/openonion/oo-chat/blob/main/hooks/use-recent-chat-sync.ts): `hooks/use-recent-chat-sync.ts`
- [Settings](https://github.com/openonion/oo-chat/blob/main/app/settings/page.tsx): `app/settings/page.tsx`

### Agent workspaces

- [Dashboard pane](https://github.com/openonion/oo-chat/blob/main/components/dashboard/dashboard-pane.tsx): `components/dashboard/dashboard-pane.tsx`
- [Workspace shell](https://github.com/openonion/oo-chat/blob/main/components/dashboard/workspace-shell.tsx): `components/dashboard/workspace-shell.tsx`
- [Agent wiki](https://github.com/openonion/oo-chat/blob/main/components/wiki/wiki-view.tsx): `components/wiki/wiki-view.tsx`
- [Wiki route](https://github.com/openonion/oo-chat/blob/main/app/%5Baddress%5D/wiki/page.tsx): `app/[address]/wiki/page.tsx`

### Other components

- **User**
- **ConnectOnion React SDK**
- **Agent relay**
- **Remote agent**

## Connections

- User → Agent picker: chooses address (evidence: `README.md`)
- Agent picker → Agent profile: opens profile (evidence: `README.md`)
- Agent picker → Agent info lookup: loads agent info (evidence: `app/page.tsx`)
- Agent profile → Agent info lookup: loads agent info (evidence: `app/[address]/page.tsx`)
- Agent info lookup → ConnectOnion React SDK: fetches profile (evidence: `hooks/use-agent-info.ts`)
- User → Agent discovery: browses agents (evidence: `app/explore/page.tsx`)
- Agent discovery → Online agents API: requests online list
- Online agents API → ConnectOnion React SDK: queries capabilities (evidence: `app/api/agents/online/route.ts`)
- Agent profile → Session route: starts session (evidence: `README.md`)
- Session route → Agent SDK adapter: binds session (evidence: `app/[address]/[sessionId]/page.tsx`)
- Agent SDK adapter → ConnectOnion React SDK: opens agent session (evidence: `components/chat/use-agent-sdk.ts`)
- ConnectOnion React SDK → Agent relay: streams over WebSocket (evidence: `README.md`)
- Agent relay → Remote agent: relays events (evidence: `README.md`)
- Session route → Chat interface: renders conversation (evidence: `app/[address]/[sessionId]/page.tsx`)
- Chat interface → Message rendering: renders messages
- Message rendering → Coding workroom: renders workroom
- Agent profile → Onboarding gate: gates access (evidence: `app/[address]/page.tsx`)
- User → Browser identity: manages identity (evidence: `hooks/use-identity.ts`)
- Browser identity → Authentication proxy: authenticates via (evidence: `README.md`)
- Browser identity → Recent chat index: stores profile state (evidence: `hooks/use-identity.ts`)
- Recent chat sync → Recent chat index: reconciles sessions (evidence: `hooks/use-recent-chat-sync.ts`)
- ConnectOnion React SDK → Recent chat sync: provides host history (evidence: `README.md`)
- User → Settings: configures account (evidence: `app/settings/page.tsx`)
- Session route → Workspace shell: hosts chat pane (evidence: `app/[address]/[sessionId]/page.tsx`)
- Workspace shell → Dashboard pane: shows dashboard (evidence: `components/dashboard/workspace-shell.tsx`)
- Wiki route → Agent wiki: renders wiki (evidence: `app/[address]/wiki/page.tsx`)
- Wiki route → Agent info lookup: loads agent info (evidence: `app/[address]/wiki/page.tsx`)
