# i365dev/free4chat architecture

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

- Interactive diagram: https://gitdiagram.com/i365dev/free4chat
- Repository: https://github.com/i365dev/free4chat

## Overview

Free4Chat is a temporary collaboration Room for humans and independently operated Agents. A browser or Agent joins a Room; the Room coordinates presence, shared context, focused Tasks, artifacts, approvals, and bounded Apps, while realtime media uses a separate SFU path. Agents can connect through stateless MCP or the optional Go Runtime, which also supports local Harnesses, media, speech, and bounded device capabilities. The README establishes the product workflow; source excerpts and the index show Worker dispatch and Room-control calls. Unsampled internals are represented conservatively.

Main entry points: [`app/src/do/RoomSession.ts`](https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/do/RoomSession.ts) (Room session), [`app/worker.ts`](https://github.com/i365dev/free4chat/blob/cf-sfu/app/worker.ts) (Worker router), [`agent/internal/runtime/runtime.go`](https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/runtime/runtime.go) (Agent runtime), [`app/src/room/server.ts`](https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/room/server.ts) (Room API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_browser["Room browser<br/>[RoomContent.tsx]"]
end

subgraph group_room["Room services"]
  node_worker["Worker router<br/>[worker.ts]"]
  node_roomapi["Room API<br/>[server.ts]"]
  node_roomdo[("Room session<br/>[RoomSession.ts]")]
  node_taskscope["Task scope<br/>[taskScope.ts]"]
  node_roomapps["Room Apps<br/>[roomApp.ts]"]
  node_taskapps["Generated Apps"]
  node_mcp["MCP tools<br/>[server.ts]"]
end

subgraph group_agent["Agent runtime"]
  node_agentcli["Agent CLI<br/>[cli.go]"]
  node_agentclient["Room client<br/>[client.go]"]
  node_runtime["Agent runtime<br/>[runtime.go]"]
  node_harness["Harness<br/>[acp.go]"]
  node_daemon["Runtime daemon<br/>[daemon.go]"]
  node_capability["Local capabilities<br/>[controller.go]"]
  node_daemoncap["Capability relay"]
  node_agentmedia["Agent media<br/>[controller.go]"]
  node_speech["Speech<br/>[transcriber.go]"]
  node_voice["Voice output<br/>[speaker.go]"]
end

subgraph group_realtime["Realtime media"]
  node_sfu["SFU service<br/>[server.ts]"]
  node_mediaeffects["Media effects<br/>[mediaEffects.ts]"]
end

node_human(("Human"))
node_agent(("Agent"))

node_human -->|"uses"| node_browser
node_browser -->|"requests Room"| node_worker
node_worker -->|"routes Room"| node_roomapi
node_worker -->|"routes MCP"| node_mcp
node_worker -->|"routes SFU"| node_sfu
node_roomapi -->|"controls Room"| node_roomdo
node_mcp -->|"controls Room"| node_roomdo
node_sfu -->|"controls Room"| node_roomdo
node_roomdo -->|"resolves Tasks"| node_taskscope
node_roomdo -->|"executes effects"| node_mediaeffects
node_agent -->|"uses stateless API"| node_mcp
node_agent -->|"runs Runtime"| node_agentcli
node_agentcli -.->|"Room operations"| node_agentclient
node_agent -.->|"joins Room"| node_runtime
node_runtime -.->|"uses Harness"| node_harness
node_runtime -.->|"resident services"| node_daemon
node_daemon -->|"handles capability requests"| node_daemoncap
node_daemoncap -->|"delegates requests"| node_capability
node_runtime -.->|"manages media"| node_agentmedia
node_agentmedia -->|"uses speech"| node_speech
node_agentmedia -->|"uses voice"| node_voice
node_roomapi -->|"validates App data"| node_roomapps

click node_browser "https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/components/RoomContent.tsx"
click node_worker "https://github.com/i365dev/free4chat/blob/cf-sfu/app/worker.ts"
click node_roomapi "https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/room/server.ts"
click node_roomdo "https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/do/RoomSession.ts"
click node_taskscope "https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/do/taskScope.ts"
click node_roomapps "https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/common/roomApp.ts"
click node_taskapps "https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/common/generatedRoomApp.ts"
click node_mcp "https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/mcp/server.ts"
click node_sfu "https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/sfu/server.ts"
click node_mediaeffects "https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/do/mediaEffects.ts"
click node_agentcli "https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/cli/cli.go"
click node_agentclient "https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/free4chat/client.go"
click node_runtime "https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/runtime/runtime.go"
click node_harness "https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/harness/acp.go"
click node_daemon "https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/daemon/daemon.go"
click node_capability "https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/capability/controller.go"
click node_daemoncap "https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/daemon/capability_controller.go"
click node_agentmedia "https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/media/controller.go"
click node_speech "https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/speech/transcriber.go"
click node_voice "https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/voice/speaker.go"

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_browser toneBlue
class node_worker,node_roomapi,node_roomdo,node_taskscope,node_roomapps,node_taskapps,node_mcp toneAmber
class node_agentcli,node_agentclient,node_runtime,node_harness,node_daemon,node_capability,node_daemoncap,node_agentmedia,node_speech,node_voice toneMint
class node_sfu,node_mediaeffects toneRose
class node_human,node_agent toneIndigo
```

## Components

### Web experience

- [Room browser](https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/components/RoomContent.tsx): `app/src/components/RoomContent.tsx`

### Room services

- [Worker router](https://github.com/i365dev/free4chat/blob/cf-sfu/app/worker.ts): `app/worker.ts`
- [Room API](https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/room/server.ts): `app/src/room/server.ts`
- [Room session](https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/do/RoomSession.ts): `app/src/do/RoomSession.ts`
- [Task scope](https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/do/taskScope.ts): `app/src/do/taskScope.ts`
- [Room Apps](https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/common/roomApp.ts): `app/src/common/roomApp.ts`
- [Generated Apps](https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/common/generatedRoomApp.ts): `app/src/common/generatedRoomApp.ts`
- [MCP tools](https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/mcp/server.ts): `app/src/mcp/server.ts`

### Agent runtime

- [Agent CLI](https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/cli/cli.go): `agent/internal/cli/cli.go`
- [Room client](https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/free4chat/client.go): `agent/internal/free4chat/client.go`
- [Agent runtime](https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/runtime/runtime.go): `agent/internal/runtime/runtime.go`
- [Harness](https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/harness/acp.go): `agent/internal/harness/acp.go`
- [Runtime daemon](https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/daemon/daemon.go): `agent/internal/daemon/daemon.go`
- [Local capabilities](https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/capability/controller.go): `agent/internal/capability/controller.go`
- [Capability relay](https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/daemon/capability_controller.go): `agent/internal/daemon/capability_controller.go`
- [Agent media](https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/media/controller.go): `agent/internal/media/controller.go`
- [Speech](https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/speech/transcriber.go): `agent/internal/speech/transcriber.go`
- [Voice output](https://github.com/i365dev/free4chat/blob/cf-sfu/agent/internal/voice/speaker.go): `agent/internal/voice/speaker.go`

### Realtime media

- [SFU service](https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/sfu/server.ts): `app/src/sfu/server.ts`
- [Media effects](https://github.com/i365dev/free4chat/blob/cf-sfu/app/src/do/mediaEffects.ts): `app/src/do/mediaEffects.ts`

### Other components

- **Human**
- **Agent**

## Connections

- Human → Room browser: uses (evidence: `README.md`)
- Room browser → Worker router: requests Room (evidence: `README.md`)
- Worker router → Room API: routes Room (evidence: `app/worker.ts`)
- Worker router → MCP tools: routes MCP (evidence: `app/worker.ts`)
- Worker router → SFU service: routes SFU (evidence: `app/worker.ts`)
- Room API → Room session: controls Room (evidence: `app/src/room/server.ts`)
- MCP tools → Room session: controls Room (evidence: `app/src/mcp/server.ts`)
- SFU service → Room session: controls Room (evidence: `app/src/sfu/server.ts`)
- Room session → Task scope: resolves Tasks (evidence: `app/src/do/RoomSession.ts`)
- Room session → Media effects: executes effects (evidence: `app/src/do/RoomSession.ts`)
- Agent → MCP tools: uses stateless API (evidence: `README.md`)
- Agent → Agent CLI: runs Runtime (evidence: `README.md`)
- Agent CLI → Room client: Room operations
- Agent → Agent runtime: joins Room (evidence: `README.md`)
- Agent runtime → Harness: uses Harness (evidence: `README.md`)
- Agent runtime → Runtime daemon: resident services
- Runtime daemon → Capability relay: handles capability requests (evidence: `agent/internal/daemon/capability_controller.go`)
- Capability relay → Local capabilities: delegates requests (evidence: `agent/internal/daemon/capability_controller.go`)
- Agent runtime → Agent media: manages media
- Agent media → Speech: uses speech (evidence: `agent/internal/media/controller.go`)
- Agent media → Voice output: uses voice (evidence: `agent/internal/media/controller.go`)
- Room API → Room Apps: validates App data (evidence: `app/src/room/server.ts`)