System Architecture

AgentHub’s architecture is straightforward: turn agent execution and team collaboration into an event stream you can see, review, and replay — all inside a chat interface.

You send a message to an agent in a group chat. The message travels through Desktop or Web, reaches the Hub or Edge service layer, and the service layer dispatches a real AI engine to do the work. The engine’s output flows back as structured chat messages, file diffs, and artifacts — visible to your entire team.

The Big Picture: How One Request Flows

Before diving into the five layers, here’s the end-to-end data flow:

sequenceDiagram
    participant U as User
    participant C as Client (Desktop/Web/Mobile)
    participant H as Hub Server
    participant E as Local Edge
    participant AD as Agent Adapter
    participant R as Engine CLI

    U->>C: Send message to agent in group chat
    C->>E: Create run (Desktop direct, or Web/Mobile via Hub)
    E->>E: Check workspace allowlist and approval policy
    E->>AD: Start adapter from registry
    AD->>R: Invoke Claude Code / Codex / OpenCode
    R-->>AD: Emit messages, tool calls, diffs, artifacts
    AD-->>E: Normalize events and write to store
    E-->>C: Stream structured messages and artifact references
    C-->>H: Sync session, team state, audit (Hub path)
    H-->>C: Return collaboration state and routing policy

The 5-Layer Architecture

AgentHub is organized into five layers, each doing one thing well:

Layer	Component	Responsibility
Shared UI	Shared workbench module	UI shared by Desktop, Web, and Mobile: agent message feed, file change panels, approval controls
Platform Adapter	Desktop (Tauri 2), Web, Mobile (Expo RN)	Platform-specific shell: window management, notifications, deep links, native menus
Edge / Hub	Edge Server (Go), Hub Server (Go)	Local execution and engine lifecycle (Edge); accounts, sessions, projects, messages, team collaboration (Hub)
Agent Adapter	Adapter registry in Edge	Claude Code, Codex, OpenCode adapter instances managing process lifecycle and event records
Runtime CLI	Claude Code CLI, Codex CLI, OpenCode CLI	The actual AI engine process, invoked by adapters

All three clients render the same workbench UI. The platform adapter layer handles OS-specific details so the shared UI stays clean.

Component Topology

flowchart TB
    TDID["TokenDance ID\nLogin / account binding"] --> HUB["Hub Server\nGo: auth / sessions / projects / messages / team coordination"]
    WEB["AgentHub Web"] --> HUB
    DESK["AgentHub Desktop\nTauri 2"] --> EDGE["Local Edge\nGo: workspace / runs / adapters / event store"]
    MOBILE["AgentHub Mobile\nExpo RN"] --> HUB
    DESK --> HUB
    HUB --> ROUTE["Routing policy\npermissions / target selection"]
    ROUTE --> EDGE
    FEISHU["Feishu / Lark\nbot messages / event subscriptions / card callbacks"] --> IGW["Integration Gateway\nwebhook / async queue"]
    IGW --> HUB

    subgraph SHARED["Shared workbench UI"]
        TB["Agent message feed"]
        ER["Artifact references"]
        DIFF["File diff panels"]
        APPR["Approval controls"]
    end

    subgraph EDGEL["Edge Server"]
        EDGE --> RUNS["Run lifecycle"]
        EDGE --> WS["Workspace allowlist"]
        EDGE --> ART["Diff / file / preview artifacts"]
        EDGE --> REG["Adapter registry"]
        EDGE --> ES["Event store"]
    end

    subgraph ADAPTERS["Runtime adapters"]
        CC["Claude Code"]
        CX["Codex"]
        OC["OpenCode"]
    end

    REG --> CC
    REG --> CX
    REG --> OC

    DESK -.-> SHARED
    WEB -.-> SHARED
    MOBILE -.-> SHARED

Core Components

Desktop (Tauri 2)

Desktop is a Tauri 2 native client built for local execution. It renders the shared workbench UI as an IM-form group chat: every line of agent output appears as a structured chat message, and file changes and artifacts are visible in review panels. Any action that writes files, runs commands, or connects externally requires your explicit approval. During team collaboration, Desktop syncs session and audit state to Hub.

Web

Web is the browser-based team collaboration entry point. It shares the exact same workbench UI as Desktop, so the visual and interaction model are consistent. Web connects to Hub for identity, project context, team state, and message routing. It does not start local CLI processes; file execution is handled by Edge.

Mobile

Mobile is the Expo React Native client for iOS and Android. It provides an IM-form chat workbench for reviewing agent output and creating tasks on the go. Mobile connects to Hub for collaboration state and does not hold local workspace access.

Shared Workbench UI

The shared workbench is the experiential core of AgentHub. It has two key abstractions:

• Structured agent messages: Agent output in the chat stream follows a uniform format, supporting code blocks, file references, tool calls, and other rich content.
• Artifact references: Changes, diffs, and generated content produced by a run are displayed uniformly across all clients’ review panels.

Hub Server

Hub is the product’s collaboration and permission core. It consumes TokenDance ID login results, issues AgentHub sessions, and manages projects, messages, team membership, and audit records. Hub decides which clients can route work to which Edge. Hub does not hold local provider keys.

Local Edge

Local Edge sits next to the filesystem and process boundary. It manages: workspace allowlists, run lifecycle, an adapter registry (index of registered execution engines), event storage (normalized run events), and artifact production (diffs, files, previews). Local facts stream to Desktop and sync to Hub after authorization.

Adapter Registry

Edge Server maintains an adapter registry that maps engine identifiers to adapter implementations. Each adapter manages its engine’s process lifecycle, normalizes engine output into structured messages and artifact references, and writes to the event store. Currently registered adapters: Claude Code, Codex, OpenCode.

Integration Gateway

The Integration Gateway is the server-side boundary for Feishu/Lark and similar external entries. It handles webhook challenge verification, signature validation, decryption, fast card-callback acknowledgment, async queuing for long-running agent work, and minimal payload forwarding to Hub.

Responsibility Matrix

When deciding where a feature or change belongs:

Concern	Owner
Product login and account identity	TokenDance ID + Hub Server (OIDC PKCE)
Product sessions, project membership, routing policy	Hub Server
Local workspace allowlist and process execution	Local Edge
Local execution and approval UI	AgentHub Desktop (Tauri 2)
Shared workbench UI rendering	Shared workbench module
Team review, history, and routing state	Hub-backed Web / Mobile
Engine process lifecycle and event normalization	Adapter registry inside Edge
Feishu/Lark webhook verification and async queuing	Integration Gateway
Public product copy, docs, SEO, and visual QA	AgentHub Home

Data Ownership

AgentHub keeps data close to the component that enforces the matching boundary:

Data	Primary owner	Sharing rule
TokenDance ID identity and login credentials	TokenDance ID	Hub consumes verified claims; products never store provider OAuth secrets
Product sessions, projects, roles, audit	Hub Server	Web/Desktop/Mobile receive only authorized views
Workspace paths, file previews, diffs, artifacts	Local Edge	Public screenshots and docs use redacted or relative examples
Engine CLI auth state and provider keys	Local machine or server-side credential store	Never move into browser storage, docs, IM payloads, or static bundles
Run event stream	Edge event store, Hub sync after authorization	Unknown event fields stay versionable; clients ignore them safely
IM events and card actions	Integration Gateway + Hub	Full prompts, credentials, and local paths never enter card payloads

Operating Modes

AgentHub supports several operating modes, each with distinct verification standards:

Mode	Components	Current claim	Evidence required
Local preview	Desktop + Local Edge + mock engine	Preview-ready local workflow	Edge health, Desktop connection, structured messages and artifact references functional
Real local engine	Desktop + Local Edge + Claude Code/Codex/OpenCode	Engine adapter path testable locally	CLI installed/authenticated, adapter emits events, failure states visible
Hub team collaboration	Hub + Web/Mobile + Desktop/Edge sync	IM-form team workflow in progress	PKCE session, team membership, task/run sync, audit record
IM entry	Integration Gateway + Hub + Feishu/Lark	Collaboration entry in development	Signature verification, callback ack, async queue, account binding
Remote/Cloud Edge	Hub + remote Edge + routing/relay	In development until proven	Device identity, target authorization, workspace policy, degraded states, audit

Design Principles

• IM-form collaboration: AI agents join group chats as teammates. Messages are tasks; the chat is the workbench.
• Shared workbench: Desktop, Web, and Mobile render the same UI — switch devices without losing context.
• Desktop-first local execution: Local workspace and process boundaries are owned by Desktop + Local Edge.
• Hub-owned collaboration: Identity, projects, teams, routing, and audit are managed by Hub.
• Loose coupling: Components connect through explicit interfaces and are independently replaceable.
• Observable by default: Every agent action, tool call, and decision is traceable.
• Graceful degradation: One failed agent does not block unrelated work.
• Provider-neutral: Model backends remain replaceable behind provider abstractions.

Edit this page on GitHub