# wecode-ai/wegent architecture

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

- Interactive diagram: https://gitdiagram.com/wecode-ai/wegent
- Repository: https://github.com/wecode-ai/wegent

## Overview

Wegent combines a local coding workbench, browser-based agents, and a self-hostable backend for shared projects and remote execution. The main workflow is a user creating a task in the workbench, which routes it to Executor; Executor drives Codex against a project and returns activity and results for review. Project-space collaboration and backend services extend that workflow across people and devices. Relationships among documented product pieces use README evidence; source-level edges are limited to relationships visible in the supplied excerpts or SOURCE INDEX.

Main entry points: [`backend/app/api/router.py`](https://github.com/wecode-ai/wegent/blob/main/backend/app/api/router.py) (Backend APIs), [`wework/src/features/workbench/useWorkbenchRuntimeTasks.ts`](https://github.com/wecode-ai/wegent/blob/main/wework/src/features/workbench/useWorkbenchRuntimeTasks.ts) (Desktop workbench), [`executor/src/agents/codex/standard_engine.rs`](https://github.com/wecode-ai/wegent/blob/main/executor/src/agents/codex/standard_engine.rs) (Executor), [`backend/app/services/rag/retrieval_service.py`](https://github.com/wecode-ai/wegent/blob/main/backend/app/services/rag/retrieval_service.py) (RAG retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop execution"]
  node_workbench["Desktop workbench"]
  node_executor["Executor<br/>[standard_engine.rs]"]
  node_codex["Codex agent"]
  node_conversation_scroll["Conversation scrolling"]
  node_runtime_transcripts["Runtime transcripts"]
end

subgraph group_collaboration["Project collaboration"]
  node_workspace_controller["Workspace controller"]
  node_platform_controller["Platform controller"]
  node_workspace_api["Shared workspace API"]
  node_board["Project board<br/>[board.ts]"]
  node_web["Wegent Web"]
end

subgraph group_backend["Backend services"]
  node_backend_api["Backend APIs<br/>[router.py]"]
  node_backend_config["Backend configuration<br/>[config.rs]"]
  node_backend_state["Backend state<br/>[state.rs]"]
  node_device_management["Execution devices<br/>[devices.rs]"]
  node_task_routing["Task routing<br/>[task_routing.rs]"]
  node_pipeline_stages["Pipeline stages"]
  node_json_compat["JSON compatibility<br/>[json_compat.rs]"]
  node_skills["Skills<br/>[skills_unified.rs]"]
  node_logging["Backend logging<br/>[logging.py]"]
end

subgraph group_knowledge["Knowledge services"]
  node_rag_retrieval["RAG retrieval"]
  node_knowledge_ingestion["Knowledge ingestion<br/>[pipeline.py]"]
end

node_user(("User"))
node_local_project["Local project"]

node_user -->|"creates tasks"| node_workbench
node_workbench -->|"sends tasks"| node_executor
node_executor -->|"drives agent"| node_codex
node_codex -->|"works on files"| node_local_project
node_executor -->|"returns activity"| node_workbench
node_user -->|"uses agents"| node_web
node_web -->|"uses backend"| node_backend_api
node_workbench -->|"shares project work"| node_workspace_api
node_workspace_controller -->|"loads snapshots"| node_workspace_api
node_platform_controller -->|"loads workspace data"| node_workspace_api
node_workspace_controller -->|"uses board helpers"| node_board
node_backend_api -.->|"routes tasks"| node_task_routing
node_backend_api -->|"manages devices"| node_device_management
node_backend_api -.->|"offers Skills"| node_skills
node_backend_api -->|"serves knowledge"| node_rag_retrieval
node_knowledge_ingestion -.->|"supplies indexed content"| node_rag_retrieval
node_backend_config -.->|"configures services"| node_backend_state
node_backend_state -->|"provides task state"| node_pipeline_stages
node_pipeline_stages -->|"uses JSON types"| node_json_compat
node_rag_retrieval -->|"logs retrieval"| node_logging
node_workbench -->|"fetches transcripts"| node_runtime_transcripts
node_conversation_scroll -->|"renders transcript gaps"| node_runtime_transcripts

click node_workbench "https://github.com/wecode-ai/wegent/blob/main/wework/src/features/workbench/useWorkbenchRuntimeTasks.ts"
click node_executor "https://github.com/wecode-ai/wegent/blob/main/executor/src/agents/codex/standard_engine.rs"
click node_workspace_controller "https://github.com/wecode-ai/wegent/blob/main/packages/collaboration/src/workspace-controller/useCollaborationWorkspaceController.ts"
click node_platform_controller "https://github.com/wecode-ai/wegent/blob/main/packages/collaboration/src/platform/useCollaborationPlatformController.ts"
click node_workspace_api "https://github.com/wecode-ai/wegent/blob/main/packages/collaboration/src/ports/SharedWorkspaceApi.ts"
click node_board "https://github.com/wecode-ai/wegent/blob/main/packages/collaboration/src/board.ts"
click node_backend_api "https://github.com/wecode-ai/wegent/blob/main/backend/app/api/router.py"
click node_backend_config "https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/config.rs"
click node_backend_state "https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/state.rs"
click node_device_management "https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/devices.rs"
click node_task_routing "https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/task_routing.rs"
click node_pipeline_stages "https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/task_pipeline_stage_info.rs"
click node_json_compat "https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/json_compat.rs"
click node_skills "https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/skills/skills_unified.rs"
click node_rag_retrieval "https://github.com/wecode-ai/wegent/blob/main/backend/app/services/rag/retrieval_service.py"
click node_knowledge_ingestion "https://github.com/wecode-ai/wegent/blob/main/knowledge_engine/knowledge_engine/ingestion/pipeline.py"
click node_logging "https://github.com/wecode-ai/wegent/blob/main/backend/app/core/logging.py"
click node_conversation_scroll "https://github.com/wecode-ai/wegent/blob/main/packages/collaboration/src/conversation/useConversationScrollController.tsx"
click node_runtime_transcripts "https://github.com/wecode-ai/wegent/blob/main/wework/src/features/workbench/useWorkbenchRuntimeTasks.ts"

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_workbench,node_executor,node_codex,node_conversation_scroll,node_runtime_transcripts,node_user toneBlue
class node_workspace_controller,node_platform_controller,node_workspace_api,node_board,node_web toneAmber
class node_backend_api,node_backend_config,node_backend_state,node_device_management,node_task_routing,node_pipeline_stages,node_json_compat,node_skills,node_logging toneMint
class node_rag_retrieval,node_knowledge_ingestion toneRose
class node_local_project toneIndigo
```

## Components

### Desktop execution

- [Desktop workbench](https://github.com/wecode-ai/wegent/blob/main/wework/src/features/workbench/useWorkbenchRuntimeTasks.ts): `wework/src/features/workbench/useWorkbenchRuntimeTasks.ts`
- [Executor](https://github.com/wecode-ai/wegent/blob/main/executor/src/agents/codex/standard_engine.rs): `executor/src/agents/codex/standard_engine.rs`
- **Codex agent**
- [Conversation scrolling](https://github.com/wecode-ai/wegent/blob/main/packages/collaboration/src/conversation/useConversationScrollController.tsx): `packages/collaboration/src/conversation/useConversationScrollController.tsx`
- [Runtime transcripts](https://github.com/wecode-ai/wegent/blob/main/wework/src/features/workbench/useWorkbenchRuntimeTasks.ts): `wework/src/features/workbench/useWorkbenchRuntimeTasks.ts`

### Project collaboration

- [Workspace controller](https://github.com/wecode-ai/wegent/blob/main/packages/collaboration/src/workspace-controller/useCollaborationWorkspaceController.ts): `packages/collaboration/src/workspace-controller/useCollaborationWorkspaceController.ts`
- [Platform controller](https://github.com/wecode-ai/wegent/blob/main/packages/collaboration/src/platform/useCollaborationPlatformController.ts): `packages/collaboration/src/platform/useCollaborationPlatformController.ts`
- [Shared workspace API](https://github.com/wecode-ai/wegent/blob/main/packages/collaboration/src/ports/SharedWorkspaceApi.ts): `packages/collaboration/src/ports/SharedWorkspaceApi.ts`
- [Project board](https://github.com/wecode-ai/wegent/blob/main/packages/collaboration/src/board.ts): `packages/collaboration/src/board.ts`
- **Wegent Web**

### Backend services

- [Backend APIs](https://github.com/wecode-ai/wegent/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Backend configuration](https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/config.rs): `backend-rs/src/config.rs`
- [Backend state](https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/state.rs): `backend-rs/src/state.rs`
- [Execution devices](https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/devices.rs): `backend-rs/src/devices.rs`
- [Task routing](https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/task_routing.rs): `backend-rs/src/task_routing.rs`
- [Pipeline stages](https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/task_pipeline_stage_info.rs): `backend-rs/src/task_pipeline_stage_info.rs`
- [JSON compatibility](https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/json_compat.rs): `backend-rs/src/json_compat.rs`
- [Skills](https://github.com/wecode-ai/wegent/blob/main/backend-rs/src/skills/skills_unified.rs): `backend-rs/src/skills/skills_unified.rs`
- [Backend logging](https://github.com/wecode-ai/wegent/blob/main/backend/app/core/logging.py): `backend/app/core/logging.py`

### Knowledge services

- [RAG retrieval](https://github.com/wecode-ai/wegent/blob/main/backend/app/services/rag/retrieval_service.py): `backend/app/services/rag/retrieval_service.py`
- [Knowledge ingestion](https://github.com/wecode-ai/wegent/blob/main/knowledge_engine/knowledge_engine/ingestion/pipeline.py): `knowledge_engine/knowledge_engine/ingestion/pipeline.py`

### Other components

- **User**
- **Local project**

## Connections

- User → Desktop workbench: creates tasks (evidence: `README.md`)
- Desktop workbench → Executor: sends tasks (evidence: `README.md`)
- Executor → Codex agent: drives agent (evidence: `README.md`)
- Codex agent → Local project: works on files (evidence: `README.md`)
- Executor → Desktop workbench: returns activity (evidence: `README.md`)
- User → Wegent Web: uses agents (evidence: `README.md`)
- Wegent Web → Backend APIs: uses backend (evidence: `README.md`)
- Desktop workbench → Shared workspace API: shares project work (evidence: `README.md`)
- Workspace controller → Shared workspace API: loads snapshots (evidence: `packages/collaboration/src/workspace-controller/useCollaborationWorkspaceController.ts`)
- Platform controller → Shared workspace API: loads workspace data (evidence: `packages/collaboration/src/platform/useCollaborationPlatformController.ts`)
- Workspace controller → Project board: uses board helpers (evidence: `packages/collaboration/src/workspace-controller/useCollaborationWorkspaceController.ts`)
- Backend APIs → Task routing: routes tasks
- Backend APIs → Execution devices: manages devices (evidence: `README.md`)
- Backend APIs → Skills: offers Skills
- Backend APIs → RAG retrieval: serves knowledge (evidence: `README.md`)
- Knowledge ingestion → RAG retrieval: supplies indexed content
- Backend configuration → Backend state: configures services (evidence: `backend-rs/src/state.rs`)
- Backend state → Pipeline stages: provides task state (evidence: `backend-rs/src/task_pipeline_stage_info.rs`)
- Pipeline stages → JSON compatibility: uses JSON types (evidence: `backend-rs/src/task_pipeline_stage_info.rs`)
- RAG retrieval → Backend logging: logs retrieval (evidence: `backend/app/services/rag/retrieval_service.py`)
- Desktop workbench → Runtime transcripts: fetches transcripts (evidence: `wework/src/features/workbench/useWorkbenchRuntimeTasks.ts`)
- Conversation scrolling → Runtime transcripts: renders transcript gaps (evidence: `packages/collaboration/src/conversation/useConversationScrollController.tsx`)
