# zhangcongmr/clover architecture

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

## Overview

Clover is a browser-based development assistant paired with a local proxy agent. The main workflow is using the assistant’s editor, terminal, and ACP chat to work with local projects through the agent; the agent exposes file and agent-session APIs and can connect to external ACP processes. The monorepo also contains community, account, and service-management surfaces. Relationships below rely on README statements and the supplied source index or excerpts; unsampled modules are represented by their exact tree paths, with uncertain links omitted.

Main entry points: [`packages/agent/src/server.ts`](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/server.ts) (Agent server), [`packages/agent/src/api/acp-routes.ts`](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/api/acp-routes.ts) (ACP API routes), [`packages/assistant/src/app/app.component.ts`](https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/app.component.ts) (Browser assistant), [`packages/agent/src/acp/session-manager.ts`](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/acp/session-manager.ts) (ACP sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_assistant["Assistant app"]
  node_assistant_app["Browser assistant<br/>[app.component.ts]"]
  node_assistant_core["Core services<br/>[core.service.ts]"]
  node_acp_client["ACP client<br/>[acp.service.ts]"]
  node_acp_chat["ACP chat UI"]
  node_editor_terminal["Editor and terminal"]
  node_server_manager["Server manager"]
  node_service_manager["Service manager"]
  node_mcp_manager["MCP manager"]
  node_skill_manager["Skill manager"]
end

subgraph group_agent["Local proxy agent"]
  node_agent_server["Agent server<br/>[server.ts]"]
  node_agent_routes["Local file API<br/>[routes.ts]"]
  node_auth_middleware["Token security<br/>[middleware.ts]"]
  node_file_service["File operations<br/>[file-service.ts]"]
  node_pty_manager["PTY manager<br/>[pty-manager.ts]"]
  node_acp_routes["ACP API routes<br/>[acp-routes.ts]"]
end

subgraph group_integrations["Agent integrations"]
  node_session_manager["ACP sessions<br/>[session-manager.ts]"]
  node_agent_registry["Agent registry<br/>[agent-registry.ts]"]
  node_sse_client["ACP process client<br/>[sse-client.ts]"]
  node_sse_manager["SSE events<br/>[sse-manager.ts]"]
  node_mcp_registry["MCP registry<br/>[registry.ts]"]
  node_skill_registry["Skill registry<br/>[registry.ts]"]
end

subgraph group_web["Web surfaces"]
  node_community["Community widget<br/>[App.tsx]"]
  node_home["Home dashboard<br/>[App.tsx]"]
  node_editor_site["Editor surface<br/>[App.tsx]"]
  node_account_flows["Account flows<br/>[App.tsx]"]
end

subgraph group_shared["Shared services"]
  node_redis[("Redis or memory<br/>[client.ts]")]
  node_common["Shared contracts<br/>[model.ts]"]
  node_supabase_auth["Supabase auth<br/>[node_auth_api.tsx]"]
end

node_developer(("Developer"))
node_acp_agent(("External ACP agent"))

node_developer -->|"uses"| node_assistant_app
node_assistant_app -.->|"uses services"| node_assistant_core
node_assistant_app -.->|"starts ACP chat"| node_acp_client
node_acp_client -.->|"connects to proxy"| node_agent_server
node_assistant_app -->|"offers tools"| node_editor_terminal
node_agent_server -->|"registers routes"| node_agent_routes
node_agent_server -->|"registers routes"| node_acp_routes
node_agent_server -->|"creates manager"| node_pty_manager
node_agent_routes -->|"handles file requests"| node_file_service
node_agent_routes -->|"guards requests"| node_auth_middleware
node_auth_middleware -.->|"verifies tokens"| node_auth_middleware
node_acp_routes -->|"manages sessions"| node_session_manager
node_acp_routes -->|"streams events"| node_sse_manager
node_acp_routes -->|"selects agents"| node_agent_registry
node_acp_routes -->|"uses registry"| node_mcp_registry
node_session_manager -->|"gets connections"| node_agent_registry
node_session_manager -->|"publishes prompts"| node_redis
node_session_manager -->|"sends ACP messages"| node_sse_client
node_agent_registry -->|"creates clients"| node_sse_client
node_sse_client -.->|"runs process"| node_acp_agent
node_sse_manager -->|"subscribes events"| node_redis
node_agent_server -->|"initializes registry"| node_mcp_registry
node_agent_server -->|"initializes registry"| node_skill_registry
node_assistant_core -->|"uses contracts"| node_common
node_assistant_core -.->|"supports account UI"| node_account_flows
node_home -->|"uses shared types"| node_common
node_community -.->|"presents community"| node_developer
node_editor_site -->|"offers editor"| node_developer
node_account_flows -.->|"authenticates"| node_supabase_auth

click node_assistant_app "https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/app.component.ts"
click node_assistant_core "https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/core.service.ts"
click node_acp_client "https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/acp/acp.service.ts"
click node_acp_chat "https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/acp/acp-chat.component.ts"
click node_editor_terminal "https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/notebook/notebook.component.ts"
click node_server_manager "https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/server-manager/server-manager.component.ts"
click node_service_manager "https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/service-manager/service-manager.component.ts"
click node_mcp_manager "https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/mcp-manager/mcp-manager.component.ts"
click node_skill_manager "https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/skill-manager/skill-manager.component.ts"
click node_agent_server "https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/server.ts"
click node_agent_routes "https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/api/routes.ts"
click node_auth_middleware "https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/api/middleware.ts"
click node_file_service "https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/agent/file-service.ts"
click node_pty_manager "https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/agent/pty-manager.ts"
click node_acp_routes "https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/api/acp-routes.ts"
click node_session_manager "https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/acp/session-manager.ts"
click node_agent_registry "https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/acp/agent-registry.ts"
click node_sse_client "https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/acp/sse-client.ts"
click node_sse_manager "https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/acp/sse-manager.ts"
click node_mcp_registry "https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/mcp/registry.ts"
click node_skill_registry "https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/skills/registry.ts"
click node_redis "https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/redis/client.ts"
click node_common "https://github.com/zhangcongmr/clover/blob/main/packages/common/src/model.ts"
click node_community "https://github.com/zhangcongmr/clover/blob/main/packages/community-widget/src/app/App.tsx"
click node_home "https://github.com/zhangcongmr/clover/blob/main/packages/home/src/app/App.tsx"
click node_editor_site "https://github.com/zhangcongmr/clover/blob/main/packages/editor/src/app/App.tsx"
click node_account_flows "https://github.com/zhangcongmr/clover/blob/main/packages/signin/src/app/App.tsx"
click node_supabase_auth "https://github.com/zhangcongmr/clover/blob/main/supabase/functions/server/node_auth_api.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_assistant_app,node_assistant_core,node_acp_client,node_acp_chat,node_editor_terminal,node_server_manager,node_service_manager,node_mcp_manager,node_skill_manager toneBlue
class node_agent_server,node_agent_routes,node_auth_middleware,node_file_service,node_pty_manager,node_acp_routes toneAmber
class node_session_manager,node_agent_registry,node_sse_client,node_sse_manager,node_mcp_registry,node_skill_registry toneMint
class node_community,node_home,node_editor_site,node_account_flows toneRose
class node_redis,node_common,node_supabase_auth,node_developer,node_acp_agent toneIndigo
```

## Components

### Assistant app

- [Browser assistant](https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/app.component.ts): `packages/assistant/src/app/app.component.ts`
- [Core services](https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/core.service.ts): `packages/assistant/src/app/core.service.ts`
- [ACP client](https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/acp/acp.service.ts): `packages/assistant/src/app/shared/acp/acp.service.ts`
- [ACP chat UI](https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/acp/acp-chat.component.ts): `packages/assistant/src/app/shared/acp/acp-chat.component.ts`
- [Editor and terminal](https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/notebook/notebook.component.ts): `packages/assistant/src/app/shared/notebook/notebook.component.ts`
- [Server manager](https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/server-manager/server-manager.component.ts): `packages/assistant/src/app/shared/server-manager/server-manager.component.ts`
- [Service manager](https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/service-manager/service-manager.component.ts): `packages/assistant/src/app/shared/service-manager/service-manager.component.ts`
- [MCP manager](https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/mcp-manager/mcp-manager.component.ts): `packages/assistant/src/app/shared/mcp-manager/mcp-manager.component.ts`
- [Skill manager](https://github.com/zhangcongmr/clover/blob/main/packages/assistant/src/app/shared/skill-manager/skill-manager.component.ts): `packages/assistant/src/app/shared/skill-manager/skill-manager.component.ts`

### Local proxy agent

- [Agent server](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/server.ts): `packages/agent/src/server.ts`
- [Local file API](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/api/routes.ts): `packages/agent/src/api/routes.ts`
- [Token security](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/api/middleware.ts): `packages/agent/src/api/middleware.ts`
- [File operations](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/agent/file-service.ts): `packages/agent/src/agent/file-service.ts`
- [PTY manager](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/agent/pty-manager.ts): `packages/agent/src/agent/pty-manager.ts`
- [ACP API routes](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/api/acp-routes.ts): `packages/agent/src/api/acp-routes.ts`

### Agent integrations

- [ACP sessions](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/acp/session-manager.ts): `packages/agent/src/acp/session-manager.ts`
- [Agent registry](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/acp/agent-registry.ts): `packages/agent/src/acp/agent-registry.ts`
- [ACP process client](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/acp/sse-client.ts): `packages/agent/src/acp/sse-client.ts`
- [SSE events](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/acp/sse-manager.ts): `packages/agent/src/acp/sse-manager.ts`
- [MCP registry](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/mcp/registry.ts): `packages/agent/src/mcp/registry.ts`
- [Skill registry](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/skills/registry.ts): `packages/agent/src/skills/registry.ts`

### Web surfaces

- [Community widget](https://github.com/zhangcongmr/clover/blob/main/packages/community-widget/src/app/App.tsx): `packages/community-widget/src/app/App.tsx`
- [Home dashboard](https://github.com/zhangcongmr/clover/blob/main/packages/home/src/app/App.tsx): `packages/home/src/app/App.tsx`
- [Editor surface](https://github.com/zhangcongmr/clover/blob/main/packages/editor/src/app/App.tsx): `packages/editor/src/app/App.tsx`
- [Account flows](https://github.com/zhangcongmr/clover/blob/main/packages/signin/src/app/App.tsx): `packages/signin/src/app/App.tsx`

### Shared services

- [Redis or memory](https://github.com/zhangcongmr/clover/blob/main/packages/agent/src/redis/client.ts): `packages/agent/src/redis/client.ts`
- [Shared contracts](https://github.com/zhangcongmr/clover/blob/main/packages/common/src/model.ts): `packages/common/src/model.ts`
- [Supabase auth](https://github.com/zhangcongmr/clover/blob/main/supabase/functions/server/node_auth_api.tsx): `supabase/functions/server/node_auth_api.tsx`

### Other components

- **Developer**
- **External ACP agent**

## Connections

- Developer → Browser assistant: uses (evidence: `README.md`)
- Browser assistant → Core services: uses services
- Browser assistant → ACP client: starts ACP chat
- ACP client → Agent server: connects to proxy
- Browser assistant → Editor and terminal: offers tools (evidence: `README.md`)
- Agent server → Local file API: registers routes (evidence: `packages/agent/src/server.ts`)
- Agent server → ACP API routes: registers routes (evidence: `packages/agent/src/server.ts`)
- Agent server → PTY manager: creates manager (evidence: `packages/agent/src/server.ts`)
- Local file API → File operations: handles file requests (evidence: `packages/agent/src/api/routes.ts`)
- Local file API → Token security: guards requests (evidence: `packages/agent/src/api/routes.ts`)
- Token security → Token security: verifies tokens (evidence: `packages/agent/src/api/middleware.ts`)
- ACP API routes → ACP sessions: manages sessions (evidence: `packages/agent/src/api/acp-routes.ts`)
- ACP API routes → SSE events: streams events (evidence: `packages/agent/src/api/acp-routes.ts`)
- ACP API routes → Agent registry: selects agents (evidence: `packages/agent/src/api/acp-routes.ts`)
- ACP API routes → MCP registry: uses registry (evidence: `packages/agent/src/api/acp-routes.ts`)
- ACP sessions → Agent registry: gets connections (evidence: `packages/agent/src/acp/session-manager.ts`)
- ACP sessions → Redis or memory: publishes prompts (evidence: `packages/agent/src/acp/session-manager.ts`)
- ACP sessions → ACP process client: sends ACP messages (evidence: `packages/agent/src/acp/session-manager.ts`)
- Agent registry → ACP process client: creates clients (evidence: `packages/agent/src/acp/agent-registry.ts`)
- ACP process client → External ACP agent: runs process
- SSE events → Redis or memory: subscribes events (evidence: `packages/agent/src/acp/sse-manager.ts`)
- Agent server → MCP registry: initializes registry (evidence: `packages/agent/src/server.ts`)
- Agent server → Skill registry: initializes registry (evidence: `packages/agent/src/server.ts`)
- Core services → Shared contracts: uses contracts (evidence: `packages/assistant/src/app/core.service.ts`)
- Core services → Account flows: supports account UI
- Home dashboard → Shared contracts: uses shared types (evidence: `packages/home/src/app/App.tsx`)
- Community widget → Developer: presents community
- Editor surface → Developer: offers editor (evidence: `README.md`)
- Account flows → Supabase auth: authenticates
