# huangruiteng/loopx architecture

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

- Interactive diagram: https://gitdiagram.com/huangruiteng/loopx
- Repository: https://github.com/huangruiteng/loopx

## Overview

LoopX is a local-first control plane for durable agent goals and personal agent teams. The principal workflow is to configure a goal, let LoopX govern permitted bounded turns across sessions, preserve evidence and handoffs, then surface progress and owner decisions in the workspace. Collaboration, manager conversations, integrations, and evidence/reward-memory capabilities extend that loop. The README documents the broad product flow; sampled source confirms selected control, context, and UI behaviors, but does not expose the full turn-runner or storage wiring.

Main entry points: [`loopx/control_plane/turn_driver`](https://github.com/huangruiteng/loopx/tree/main/loopx/control_plane/turn_driver) (Turn driver), [`loopx`](https://github.com/huangruiteng/loopx/tree/main/loopx) (Goal state), [`apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx`](https://github.com/huangruiteng/loopx/blob/main/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx) (Workspace UI), [`apps/presentation/dashboard/src/data/status.ts`](https://github.com/huangruiteng/loopx/blob/main/apps/presentation/dashboard/src/data/status.ts) (Workspace data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Personal workspace"]
  node_workspace_ui["Workspace UI"]
  node_workspace_data["Workspace data<br/>[status.ts]"]
  node_goal_config["Goal settings"]
end

subgraph group_governance["Goal governance"]
  node_goal_lifecycle["Goal lifecycle"]
  node_turn_driver["Turn driver"]
  node_loop_controller["Loop controller<br/>[loop_controller.py]"]
  node_scheduler["Scheduler and quota"]
  node_goal_state[("Goal state")]
  node_authority_service["Authority service"]
  node_postgres[("PostgreSQL")]
end

subgraph group_execution["Agent execution"]
  node_agent_runtime{{"Agent runtimes"}}
  node_session_binding["Session lifecycle"]
end

subgraph group_collaboration["Team collaboration"]
  node_peer_work["Peer work"]
  node_manager_inbox["Manager inbox<br/>[manager_inbox.py]"]
  node_team_results["Team results"]
end

subgraph group_evidence["Evidence and integrations"]
  node_evidence_context["Manager evidence"]
  node_issue_context["Issue context"]
  node_reward_memory["Reward memory<br/>[application.py]"]
  node_lark_delivery["Lark delivery"]
end

node_owner(("Owner"))

node_owner -->|"steers work"| node_workspace_ui
node_workspace_ui -->|"configures goals"| node_goal_config
node_workspace_ui -->|"requests status"| node_workspace_data
node_workspace_data -->|"reads projections"| node_goal_state
node_goal_config -->|"updates settings"| node_goal_lifecycle
node_goal_lifecycle -->|"manages state"| node_goal_state
node_turn_driver -->|"requests decision"| node_scheduler
node_turn_driver -->|"dispatches turn"| node_agent_runtime
node_agent_runtime -->|"returns receipt"| node_turn_driver
node_loop_controller -->|"validates disposition"| node_turn_driver
node_turn_driver -->|"writes handoff"| node_goal_state
node_session_binding -->|"binds sessions"| node_goal_lifecycle
node_peer_work -->|"records claims"| node_goal_state
node_manager_inbox -->|"requests peer work"| node_peer_work
node_workspace_ui -->|"opens results"| node_team_results
node_team_results -->|"fetches team work"| node_workspace_data
node_evidence_context -->|"reads delivery history"| node_goal_state
node_issue_context -.->|"composes memory source"| node_reward_memory
node_manager_inbox -.->|"delivers replies"| node_lark_delivery
node_authority_service -->|"opens store"| node_postgres

click node_workspace_ui "https://github.com/huangruiteng/loopx/blob/main/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx"
click node_workspace_data "https://github.com/huangruiteng/loopx/blob/main/apps/presentation/dashboard/src/data/status.ts"
click node_goal_config "https://github.com/huangruiteng/loopx/blob/main/apps/presentation/dashboard/src/features/personal-workspace/goal-capability-settings.tsx"
click node_goal_lifecycle "https://github.com/huangruiteng/loopx/tree/main/loopx/control_plane/goals"
click node_turn_driver "https://github.com/huangruiteng/loopx/tree/main/loopx/control_plane/turn_driver"
click node_loop_controller "https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/loop_controller.py"
click node_scheduler "https://github.com/huangruiteng/loopx/tree/main/loopx/control_plane"
click node_goal_state "https://github.com/huangruiteng/loopx/tree/main/loopx"
click node_session_binding "https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/goals/source_session_services.py"
click node_peer_work "https://github.com/huangruiteng/loopx/tree/main/loopx/control_plane/collaboration"
click node_manager_inbox "https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/manager_inbox.py"
click node_team_results "https://github.com/huangruiteng/loopx/blob/main/apps/presentation/dashboard/src/features/personal-workspace/manager-team-result.tsx"
click node_evidence_context "https://github.com/huangruiteng/loopx/blob/main/loopx/chat_manager_context.py"
click node_issue_context "https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/issue_fix/repository_context.py"
click node_reward_memory "https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/reward_memory/application.py"
click node_lark_delivery "https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/manager_reply_parts.py"
click node_authority_service "https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/coordination/postgresql_authority_service.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_workspace_ui,node_workspace_data,node_goal_config toneBlue
class node_goal_lifecycle,node_turn_driver,node_loop_controller,node_scheduler,node_goal_state,node_authority_service,node_postgres toneAmber
class node_agent_runtime,node_session_binding toneMint
class node_peer_work,node_manager_inbox,node_team_results toneRose
class node_evidence_context,node_issue_context,node_reward_memory,node_lark_delivery,node_owner toneIndigo
```

## Components

### Personal workspace

- [Workspace UI](https://github.com/huangruiteng/loopx/blob/main/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx): `apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx`
- [Workspace data](https://github.com/huangruiteng/loopx/blob/main/apps/presentation/dashboard/src/data/status.ts): `apps/presentation/dashboard/src/data/status.ts`
- [Goal settings](https://github.com/huangruiteng/loopx/blob/main/apps/presentation/dashboard/src/features/personal-workspace/goal-capability-settings.tsx): `apps/presentation/dashboard/src/features/personal-workspace/goal-capability-settings.tsx`

### Goal governance

- [Goal lifecycle](https://github.com/huangruiteng/loopx/tree/main/loopx/control_plane/goals): `loopx/control_plane/goals`
- [Turn driver](https://github.com/huangruiteng/loopx/tree/main/loopx/control_plane/turn_driver): `loopx/control_plane/turn_driver`
- [Loop controller](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/loop_controller.py): `loopx/control_plane/turn_driver/loop_controller.py`
- [Scheduler and quota](https://github.com/huangruiteng/loopx/tree/main/loopx/control_plane): `loopx/control_plane`
- [Goal state](https://github.com/huangruiteng/loopx/tree/main/loopx): `loopx`
- [Authority service](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/coordination/postgresql_authority_service.ts): `loopx/control_plane/coordination/postgresql_authority_service.ts`
- **PostgreSQL**

### Agent execution

- **Agent runtimes**
- [Session lifecycle](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/goals/source_session_services.py): `loopx/control_plane/goals/source_session_services.py`

### Team collaboration

- [Peer work](https://github.com/huangruiteng/loopx/tree/main/loopx/control_plane/collaboration): `loopx/control_plane/collaboration`
- [Manager inbox](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/manager_inbox.py): `loopx/cli_commands/manager_inbox.py`
- [Team results](https://github.com/huangruiteng/loopx/blob/main/apps/presentation/dashboard/src/features/personal-workspace/manager-team-result.tsx): `apps/presentation/dashboard/src/features/personal-workspace/manager-team-result.tsx`

### Evidence and integrations

- [Manager evidence](https://github.com/huangruiteng/loopx/blob/main/loopx/chat_manager_context.py): `loopx/chat_manager_context.py`
- [Issue context](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/issue_fix/repository_context.py): `loopx/capabilities/issue_fix/repository_context.py`
- [Reward memory](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/reward_memory/application.py): `loopx/capabilities/reward_memory/application.py`
- [Lark delivery](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/manager_reply_parts.py): `loopx/extensions/lark/manager_reply_parts.py`

### Other components

- **Owner**

## Connections

- Owner → Workspace UI: steers work
- Workspace UI → Goal settings: configures goals
- Workspace UI → Workspace data: requests status
- Workspace data → Goal state: reads projections
- Goal settings → Goal lifecycle: updates settings
- Goal lifecycle → Goal state: manages state
- Turn driver → Scheduler and quota: requests decision
- Turn driver → Agent runtimes: dispatches turn
- Agent runtimes → Turn driver: returns receipt
- Loop controller → Turn driver: validates disposition
- Turn driver → Goal state: writes handoff
- Session lifecycle → Goal lifecycle: binds sessions
- Peer work → Goal state: records claims
- Manager inbox → Peer work: requests peer work
- Workspace UI → Team results: opens results
- Team results → Workspace data: fetches team work
- Manager evidence → Goal state: reads delivery history
- Issue context → Reward memory: composes memory source
- Manager inbox → Lark delivery: delivers replies
- Authority service → PostgreSQL: opens store