# loopx-project/loopx architecture

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

- Interactive diagram: https://gitdiagram.com/loopx-project/loopx
- Repository: https://github.com/loopx-project/loopx
- Video tour (about a minute): https://gitdiagram.com/loopx-project/loopx/video

## Overview

LoopX is a local-first control plane for durable, long-running agent goals: a person starts work through a supported agent host, LoopX tracks governed turns and continuation, and the person reviews progress and evidence in the workspace. The README describes collaboration, recovery, scheduling, capability configuration, and cross-runtime sessions as additional product capabilities. Source excerpts show selected storage, runtime, and evidence boundaries; the wider control-plane map is based on the README and SOURCE INDEX, so unsampled connections are omitted.

Main entry points: [`loopx/control_plane/turn_driver`](https://github.com/loopx-project/loopx/tree/main/loopx/control_plane/turn_driver) (Turn driver), [`loopx/control_plane/effect_runtime.py`](https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/effect_runtime.py) (Effect runtime), [`loopx/cli_commands`](https://github.com/loopx-project/loopx/tree/main/loopx/cli_commands) (Goal setup), [`loopx/chat_manager.py`](https://github.com/loopx-project/loopx/blob/main/loopx/chat_manager.py) (Manager service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_goal_setup["Goal setup"]
  node_chat_service["Chat service<br/>[chat.py]"]
  node_manager["Manager service<br/>[chat_manager.py]"]
end

subgraph group_governance["Goal governance"]
  node_turn_controller["Turn controller<br/>[loop_controller.py]"]
  node_agent_registry["Agent registry<br/>[agent_registry.py]"]
  node_todos["Todo contracts<br/>[contract.py]"]
  node_authority["Authority coordination"]
  node_postgres_authority["PostgreSQL authority"]
  node_machine_storage["Storage configuration<br/>[goal_storage.py]"]
end

subgraph group_runtime["Turn runtime"]
  node_turn_driver["Turn driver"]
  node_effect_runtime["Effect runtime<br/>[effect_runtime.py]"]
  node_repository_context["Repository context"]
  node_runtime_selection["Runtime selection"]
end

subgraph group_durability["State and evidence"]
  node_manager_context["Manager evidence"]
  node_project_registry["Project registry<br/>[registry_codec.py]"]
  node_runtime_shadow["Runtime shadow<br/>[runtime_shadow.py]"]
  node_goal_storage_api["Storage API"]
  node_reward_memory["Reward memory<br/>[application.py]"]
end

subgraph group_workspace["Workspace and integrations"]
  node_dashboard["Personal workspace"]
  node_chat_ui["Chat interface<br/>[chat-main.tsx]"]
  node_goal_storage_ui["Storage settings"]
  node_goal_storage_data["Storage client<br/>[goal-storage.ts]"]
  node_manager_inbox["Manager inbox<br/>[manager_inbox.py]"]
  node_lark["Lark connector<br/>[manager_context.py]"]
  node_desktop_shell["Desktop shell<br/>[services.rs]"]
end

node_owner(("Goal owner"))
node_agent_host(("Agent host"))

node_owner -->|"starts work"| node_agent_host
node_agent_host -->|"requests a goal"| node_goal_setup
node_goal_setup -->|"plans as Todos"| node_todos
node_goal_setup -->|"sets continuation"| node_turn_controller
node_agent_host -->|"runs turns"| node_turn_driver
node_turn_controller -->|"governs continuation"| node_turn_driver
node_turn_driver -->|"dispatches effects"| node_effect_runtime
node_turn_driver -->|"resolves agents"| node_agent_registry
node_agent_registry -->|"reads contracts"| node_todos
node_turn_controller -->|"selects work"| node_todos
node_turn_controller -.->|"validates authority"| node_authority
node_authority -->|"uses service"| node_postgres_authority
node_effect_runtime -->|"captures effects"| node_runtime_shadow
node_runtime_shadow -->|"reads agents"| node_agent_registry
node_runtime_shadow -->|"reads registry"| node_project_registry
node_goal_setup -.->|"registers projects"| node_project_registry
node_owner -->|"reviews progress"| node_dashboard
node_dashboard -.->|"opens chat"| node_chat_ui
node_chat_ui -.->|"requests chat"| node_chat_service
node_chat_service -->|"delegates manager chat"| node_manager
node_manager -->|"uses evidence"| node_manager_context
node_dashboard -->|"configures storage"| node_goal_storage_ui
node_goal_storage_ui -->|"reads and previews"| node_goal_storage_data
node_goal_storage_data -->|"calls API"| node_goal_storage_api
node_goal_storage_api -->|"inspects source"| node_runtime_shadow
node_goal_storage_api -->|"requests effects"| node_effect_runtime
node_machine_storage -->|"resolves storage"| node_effect_runtime
node_turn_driver -.->|"uses context"| node_repository_context
node_manager -.->|"supports inbox"| node_manager_inbox
node_manager -.->|"connects conversations"| node_lark
node_effect_runtime -.->|"supports recall"| node_reward_memory
node_desktop_shell -->|"selects runtime"| node_runtime_selection
node_owner -->|"uses desktop app"| node_desktop_shell

click node_goal_setup "https://github.com/loopx-project/loopx/tree/main/loopx/cli_commands"
click node_dashboard "https://github.com/loopx-project/loopx/blob/main/apps/presentation/dashboard/src/features/personal-workspace/personal-workspace-page.tsx"
click node_chat_ui "https://github.com/loopx-project/loopx/blob/main/apps/presentation/dashboard/src/chat-main.tsx"
click node_chat_service "https://github.com/loopx-project/loopx/blob/main/loopx/chat.py"
click node_manager "https://github.com/loopx-project/loopx/blob/main/loopx/chat_manager.py"
click node_manager_context "https://github.com/loopx-project/loopx/blob/main/loopx/chat_manager_context.py"
click node_turn_controller "https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/turn_driver/loop_controller.py"
click node_turn_driver "https://github.com/loopx-project/loopx/tree/main/loopx/control_plane/turn_driver"
click node_effect_runtime "https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/effect_runtime.py"
click node_agent_registry "https://github.com/loopx-project/loopx/blob/main/loopx/agent_registry.py"
click node_todos "https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/todos/contract.py"
click node_authority "https://github.com/loopx-project/loopx/tree/main/loopx/control_plane/coordination"
click node_postgres_authority "https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/coordination/postgresql_authority_service.ts"
click node_project_registry "https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/projects/registry_codec.py"
click node_runtime_shadow "https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/coordination/runtime_shadow.py"
click node_goal_storage_api "https://github.com/loopx-project/loopx/blob/main/loopx/presentation/goal_storage_api.py"
click node_goal_storage_ui "https://github.com/loopx-project/loopx/blob/main/apps/presentation/dashboard/src/features/personal-workspace/goal-storage-settings.tsx"
click node_goal_storage_data "https://github.com/loopx-project/loopx/blob/main/apps/presentation/dashboard/src/data/goal-storage.ts"
click node_machine_storage "https://github.com/loopx-project/loopx/blob/main/loopx/capabilities/machine_configuration/goal_storage.py"
click node_reward_memory "https://github.com/loopx-project/loopx/blob/main/loopx/capabilities/reward_memory/application.py"
click node_repository_context "https://github.com/loopx-project/loopx/blob/main/loopx/capabilities/issue_fix/repository_context.py"
click node_manager_inbox "https://github.com/loopx-project/loopx/blob/main/loopx/cli_commands/manager_inbox.py"
click node_lark "https://github.com/loopx-project/loopx/blob/main/loopx/extensions/lark/manager_context.py"
click node_desktop_shell "https://github.com/loopx-project/loopx/blob/main/apps/desktop/loopx-control-plane/src-tauri/src/services.rs"
click node_runtime_selection "https://github.com/loopx-project/loopx/blob/main/apps/desktop/loopx-control-plane/src-tauri/src/runtime_selection.rs"

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_goal_setup,node_chat_service,node_manager toneBlue
class node_turn_controller,node_agent_registry,node_todos,node_authority,node_postgres_authority,node_machine_storage toneAmber
class node_turn_driver,node_effect_runtime,node_repository_context,node_runtime_selection toneMint
class node_manager_context,node_project_registry,node_runtime_shadow,node_goal_storage_api,node_reward_memory toneRose
class node_dashboard,node_chat_ui,node_goal_storage_ui,node_goal_storage_data,node_manager_inbox,node_lark,node_desktop_shell,node_owner,node_agent_host toneIndigo
```

## Components

### User entry

- [Goal setup](https://github.com/loopx-project/loopx/tree/main/loopx/cli_commands): `loopx/cli_commands`
- [Chat service](https://github.com/loopx-project/loopx/blob/main/loopx/chat.py): `loopx/chat.py`
- [Manager service](https://github.com/loopx-project/loopx/blob/main/loopx/chat_manager.py): `loopx/chat_manager.py`

### Goal governance

- [Turn controller](https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/turn_driver/loop_controller.py): `loopx/control_plane/turn_driver/loop_controller.py`
- [Agent registry](https://github.com/loopx-project/loopx/blob/main/loopx/agent_registry.py): `loopx/agent_registry.py`
- [Todo contracts](https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/todos/contract.py): `loopx/control_plane/todos/contract.py`
- [Authority coordination](https://github.com/loopx-project/loopx/tree/main/loopx/control_plane/coordination): `loopx/control_plane/coordination`
- [PostgreSQL authority](https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/coordination/postgresql_authority_service.ts): `loopx/control_plane/coordination/postgresql_authority_service.ts`
- [Storage configuration](https://github.com/loopx-project/loopx/blob/main/loopx/capabilities/machine_configuration/goal_storage.py): `loopx/capabilities/machine_configuration/goal_storage.py`

### Turn runtime

- [Turn driver](https://github.com/loopx-project/loopx/tree/main/loopx/control_plane/turn_driver): `loopx/control_plane/turn_driver`
- [Effect runtime](https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/effect_runtime.py): `loopx/control_plane/effect_runtime.py`
- [Repository context](https://github.com/loopx-project/loopx/blob/main/loopx/capabilities/issue_fix/repository_context.py): `loopx/capabilities/issue_fix/repository_context.py`
- [Runtime selection](https://github.com/loopx-project/loopx/blob/main/apps/desktop/loopx-control-plane/src-tauri/src/runtime_selection.rs): `apps/desktop/loopx-control-plane/src-tauri/src/runtime_selection.rs`

### State and evidence

- [Manager evidence](https://github.com/loopx-project/loopx/blob/main/loopx/chat_manager_context.py): `loopx/chat_manager_context.py`
- [Project registry](https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/projects/registry_codec.py): `loopx/control_plane/projects/registry_codec.py`
- [Runtime shadow](https://github.com/loopx-project/loopx/blob/main/loopx/control_plane/coordination/runtime_shadow.py): `loopx/control_plane/coordination/runtime_shadow.py`
- [Storage API](https://github.com/loopx-project/loopx/blob/main/loopx/presentation/goal_storage_api.py): `loopx/presentation/goal_storage_api.py`
- [Reward memory](https://github.com/loopx-project/loopx/blob/main/loopx/capabilities/reward_memory/application.py): `loopx/capabilities/reward_memory/application.py`

### Workspace and integrations

- [Personal workspace](https://github.com/loopx-project/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`
- [Chat interface](https://github.com/loopx-project/loopx/blob/main/apps/presentation/dashboard/src/chat-main.tsx): `apps/presentation/dashboard/src/chat-main.tsx`
- [Storage settings](https://github.com/loopx-project/loopx/blob/main/apps/presentation/dashboard/src/features/personal-workspace/goal-storage-settings.tsx): `apps/presentation/dashboard/src/features/personal-workspace/goal-storage-settings.tsx`
- [Storage client](https://github.com/loopx-project/loopx/blob/main/apps/presentation/dashboard/src/data/goal-storage.ts): `apps/presentation/dashboard/src/data/goal-storage.ts`
- [Manager inbox](https://github.com/loopx-project/loopx/blob/main/loopx/cli_commands/manager_inbox.py): `loopx/cli_commands/manager_inbox.py`
- [Lark connector](https://github.com/loopx-project/loopx/blob/main/loopx/extensions/lark/manager_context.py): `loopx/extensions/lark/manager_context.py`
- [Desktop shell](https://github.com/loopx-project/loopx/blob/main/apps/desktop/loopx-control-plane/src-tauri/src/services.rs): `apps/desktop/loopx-control-plane/src-tauri/src/services.rs`

### Other components

- **Goal owner**
- **Agent host**

## Connections

- Goal owner → Agent host: starts work (evidence: `README.md`)
- Agent host → Goal setup: requests a goal (evidence: `README.md`)
- Goal setup → Todo contracts: plans as Todos (evidence: `README.md`)
- Goal setup → Turn controller: sets continuation (evidence: `README.md`)
- Agent host → Turn driver: runs turns (evidence: `README.md`)
- Turn controller → Turn driver: governs continuation (evidence: `loopx/control_plane/turn_driver/loop_controller.py`)
- Turn driver → Effect runtime: dispatches effects (evidence: `loopx/control_plane/turn_driver/loop_controller.py`)
- Turn driver → Agent registry: resolves agents (evidence: `loopx/agent_registry.py`)
- Agent registry → Todo contracts: reads contracts (evidence: `loopx/agent_registry.py`)
- Turn controller → Todo contracts: selects work (evidence: `loopx/control_plane/turn_driver/loop_controller.py`)
- Turn controller → Authority coordination: validates authority
- Authority coordination → PostgreSQL authority: uses service (evidence: `loopx/control_plane/coordination/postgresql_authority_service.ts`)
- Effect runtime → Runtime shadow: captures effects (evidence: `loopx/control_plane/coordination/runtime_shadow.py`)
- Runtime shadow → Agent registry: reads agents (evidence: `loopx/control_plane/coordination/runtime_shadow.py`)
- Runtime shadow → Project registry: reads registry (evidence: `loopx/control_plane/coordination/runtime_shadow.py`)
- Goal setup → Project registry: registers projects (evidence: `loopx/cli_commands/manager_inbox.py`)
- Goal owner → Personal workspace: reviews progress (evidence: `README.md`)
- Personal workspace → Chat interface: opens chat
- Chat interface → Chat service: requests chat
- Chat service → Manager service: delegates manager chat (evidence: `loopx/chat_manager.py`)
- Manager service → Manager evidence: uses evidence (evidence: `loopx/chat_manager_context.py`)
- Personal workspace → Storage settings: configures storage (evidence: `README.md`)
- Storage settings → Storage client: reads and previews (evidence: `apps/presentation/dashboard/src/features/personal-workspace/goal-storage-settings.tsx`)
- Storage client → Storage API: calls API (evidence: `apps/presentation/dashboard/src/data/goal-storage.ts`)
- Storage API → Runtime shadow: inspects source (evidence: `loopx/presentation/goal_storage_api.py`)
- Storage API → Effect runtime: requests effects (evidence: `loopx/presentation/goal_storage_api.py`)
- Storage configuration → Effect runtime: resolves storage (evidence: `loopx/capabilities/machine_configuration/goal_storage.py`)
- Turn driver → Repository context: uses context
- Manager service → Manager inbox: supports inbox
- Manager service → Lark connector: connects conversations
- Effect runtime → Reward memory: supports recall
- Desktop shell → Runtime selection: selects runtime (evidence: `apps/desktop/loopx-control-plane/src-tauri/src/services.rs`)
- Goal owner → Desktop shell: uses desktop app (evidence: `README.md`)