# tencent/loopforge architecture

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

- Interactive diagram: https://gitdiagram.com/tencent/loopforge
- Repository: https://github.com/tencent/loopforge

## Overview

LoopForge is a self-hosted coding-agent workspace with two user paths: interactive Main Bot conversations and repeatable SOP runs. Both connect work to requirements, execute agents in isolated workspaces, and deliver reviewable code or artifacts. The README documents these product relationships; the source excerpts are incomplete, so internal call paths are shown only where documentation supports them, not inferred from directory names.

Main entry points: [`internal/engine/engine.go`](https://github.com/tencent/loopforge/blob/main/internal/engine/engine.go) (SOP engine), [`internal/httpapi`](https://github.com/tencent/loopforge/tree/main/internal/httpapi) (HTTP API), [`chatbot/src/useChat.js`](https://github.com/tencent/loopforge/blob/main/chatbot/src/useChat.js) (Chat session), [`internal/engine/workflow_graph.go`](https://github.com/tencent/loopforge/blob/main/internal/engine/workflow_graph.go) (SOP node stages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_workbench["Chat workbench<br/>[App.jsx]"]
  node_chat_state["Chat session<br/>[useChat.js]"]
  node_run_views["Run and artifact views<br/>[ArtifactPanel.jsx]"]
end

subgraph group_workflow["Delivery workflows"]
  node_requirements["Requirements<br/>[requirement.go]"]
  node_sop_engine["SOP engine<br/>[engine.go]"]
  node_workflow_graph["SOP node stages<br/>[workflow_graph.go]"]
  node_human_gates["Human approval gates<br/>[gate_submit.go]"]
end

subgraph group_execution["Agent execution"]
  node_agent_runtime["Coding-agent runtime<br/>[runtime.go]"]
  node_sandbox["Sandbox manager<br/>[sandbox_manager.go]"]
  node_runner["Remote runner<br/>[daemon.go]"]
  node_workspace["Conversation workspace"]
end

subgraph group_platform["Platform services"]
  node_api["HTTP API"]
  node_database[("Platform database<br/>[repo.go]")]
  node_observability["Run observability<br/>[engine_observe.go]"]
  node_notifications["Notifications<br/>[service.go]"]
end

subgraph group_delivery["Results and integrations"]
  node_git_host["Git hosting"]
  node_artifacts["Artifacts and logs<br/>[artifacts.go]"]
  node_tracker["Issue and PR tracker<br/>[service.go]"]
end

node_user(("Team member"))

node_user -->|"starts chat"| node_workbench
node_workbench -->|"sends requests"| node_api
node_api -.->|"opens conversation"| node_chat_state
node_chat_state -->|"requests workspace"| node_workspace
node_workspace -->|"opens sandbox"| node_sandbox
node_workspace -->|"calls agent"| node_agent_runtime
node_agent_runtime -.->|"dispatches work"| node_runner
node_user -->|"starts SOP"| node_api
node_api -.->|"starts run"| node_sop_engine
node_sop_engine -->|"runs stages"| node_workflow_graph
node_workflow_graph -->|"runs agent nodes"| node_agent_runtime
node_workflow_graph -->|"pauses for approval"| node_human_gates
node_sop_engine -->|"isolates execution"| node_sandbox
node_chat_state -->|"links requirement"| node_requirements
node_sop_engine -->|"tracks delivery"| node_requirements
node_api -.->|"persists platform data"| node_database
node_sop_engine -->|"records outputs"| node_artifacts
node_sop_engine -->|"tracks run state"| node_observability
node_sop_engine -->|"opens PR or MR"| node_git_host
node_chat_state -->|"delivers code"| node_git_host
node_api -.->|"integrates issues"| node_tracker
node_sop_engine -.->|"sends updates"| node_notifications
node_api -.->|"serves run results"| node_run_views
node_run_views -.->|"shows artifacts"| node_user

click node_workbench "https://github.com/tencent/loopforge/blob/main/chatbot/src/App.jsx"
click node_chat_state "https://github.com/tencent/loopforge/blob/main/chatbot/src/useChat.js"
click node_run_views "https://github.com/tencent/loopforge/blob/main/chatbot/src/ArtifactPanel.jsx"
click node_api "https://github.com/tencent/loopforge/tree/main/internal/httpapi"
click node_requirements "https://github.com/tencent/loopforge/blob/main/internal/domain/requirement.go"
click node_sop_engine "https://github.com/tencent/loopforge/blob/main/internal/engine/engine.go"
click node_workflow_graph "https://github.com/tencent/loopforge/blob/main/internal/engine/workflow_graph.go"
click node_human_gates "https://github.com/tencent/loopforge/blob/main/internal/engine/gate_submit.go"
click node_agent_runtime "https://github.com/tencent/loopforge/blob/main/internal/runtime/runtime.go"
click node_sandbox "https://github.com/tencent/loopforge/blob/main/internal/runtime/sandbox_manager.go"
click node_runner "https://github.com/tencent/loopforge/blob/main/internal/runner/daemon.go"
click node_workspace "https://github.com/tencent/loopforge/blob/main/internal/engine/conversation_workspace.go"
click node_database "https://github.com/tencent/loopforge/blob/main/internal/repo/repo.go"
click node_artifacts "https://github.com/tencent/loopforge/blob/main/internal/engine/artifacts.go"
click node_tracker "https://github.com/tencent/loopforge/blob/main/internal/tracker/service.go"
click node_observability "https://github.com/tencent/loopforge/blob/main/internal/engine/engine_observe.go"
click node_notifications "https://github.com/tencent/loopforge/blob/main/internal/notification/service.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_workbench,node_chat_state,node_run_views toneBlue
class node_requirements,node_sop_engine,node_workflow_graph,node_human_gates toneAmber
class node_agent_runtime,node_sandbox,node_runner,node_workspace toneMint
class node_api,node_database,node_observability,node_notifications toneRose
class node_git_host,node_artifacts,node_tracker,node_user toneIndigo
```

## Components

### User experience

- [Chat workbench](https://github.com/tencent/loopforge/blob/main/chatbot/src/App.jsx): `chatbot/src/App.jsx`
- [Chat session](https://github.com/tencent/loopforge/blob/main/chatbot/src/useChat.js): `chatbot/src/useChat.js`
- [Run and artifact views](https://github.com/tencent/loopforge/blob/main/chatbot/src/ArtifactPanel.jsx): `chatbot/src/ArtifactPanel.jsx`

### Delivery workflows

- [Requirements](https://github.com/tencent/loopforge/blob/main/internal/domain/requirement.go): `internal/domain/requirement.go`
- [SOP engine](https://github.com/tencent/loopforge/blob/main/internal/engine/engine.go): `internal/engine/engine.go`
- [SOP node stages](https://github.com/tencent/loopforge/blob/main/internal/engine/workflow_graph.go): `internal/engine/workflow_graph.go`
- [Human approval gates](https://github.com/tencent/loopforge/blob/main/internal/engine/gate_submit.go): `internal/engine/gate_submit.go`

### Agent execution

- [Coding-agent runtime](https://github.com/tencent/loopforge/blob/main/internal/runtime/runtime.go): `internal/runtime/runtime.go`
- [Sandbox manager](https://github.com/tencent/loopforge/blob/main/internal/runtime/sandbox_manager.go): `internal/runtime/sandbox_manager.go`
- [Remote runner](https://github.com/tencent/loopforge/blob/main/internal/runner/daemon.go): `internal/runner/daemon.go`
- [Conversation workspace](https://github.com/tencent/loopforge/blob/main/internal/engine/conversation_workspace.go): `internal/engine/conversation_workspace.go`

### Platform services

- [HTTP API](https://github.com/tencent/loopforge/tree/main/internal/httpapi): `internal/httpapi`
- [Platform database](https://github.com/tencent/loopforge/blob/main/internal/repo/repo.go): `internal/repo/repo.go`
- [Run observability](https://github.com/tencent/loopforge/blob/main/internal/engine/engine_observe.go): `internal/engine/engine_observe.go`
- [Notifications](https://github.com/tencent/loopforge/blob/main/internal/notification/service.go): `internal/notification/service.go`

### Results and integrations

- **Git hosting**
- [Artifacts and logs](https://github.com/tencent/loopforge/blob/main/internal/engine/artifacts.go): `internal/engine/artifacts.go`
- [Issue and PR tracker](https://github.com/tencent/loopforge/blob/main/internal/tracker/service.go): `internal/tracker/service.go`

### Other components

- **Team member**

## Connections

- Team member → Chat workbench: starts chat (evidence: `README.md`)
- Chat workbench → HTTP API: sends requests (evidence: `README.md`)
- HTTP API → Chat session: opens conversation
- Chat session → Conversation workspace: requests workspace (evidence: `README.md`)
- Conversation workspace → Sandbox manager: opens sandbox (evidence: `README.md`)
- Conversation workspace → Coding-agent runtime: calls agent (evidence: `README.md`)
- Coding-agent runtime → Remote runner: dispatches work
- Team member → HTTP API: starts SOP (evidence: `README.md`)
- HTTP API → SOP engine: starts run
- SOP engine → SOP node stages: runs stages (evidence: `README.md`)
- SOP node stages → Coding-agent runtime: runs agent nodes (evidence: `README.md`)
- SOP node stages → Human approval gates: pauses for approval (evidence: `README.md`)
- SOP engine → Sandbox manager: isolates execution (evidence: `README.md`)
- Chat session → Requirements: links requirement (evidence: `README.md`)
- SOP engine → Requirements: tracks delivery (evidence: `README.md`)
- HTTP API → Platform database: persists platform data
- SOP engine → Artifacts and logs: records outputs (evidence: `README.md`)
- SOP engine → Run observability: tracks run state (evidence: `README.md`)
- SOP engine → Git hosting: opens PR or MR (evidence: `README.md`)
- Chat session → Git hosting: delivers code (evidence: `README.md`)
- HTTP API → Issue and PR tracker: integrates issues
- SOP engine → Notifications: sends updates
- HTTP API → Run and artifact views: serves run results
- Run and artifact views → Team member: shows artifacts