# leeminjing/focus architecture

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

- Interactive diagram: https://gitdiagram.com/leeminjing/focus
- Repository: https://github.com/leeminjing/focus

## Overview

Focus is a local-first desktop agent built around human-governed context rather than repeated prompts. The user deploys a task, an agent runs in a Context, and Portfolio Patrol observes results and—within delegated authority—continues, curates, derives, merges, pauses, or stops work; the Kernel validates and commits decisions. Derived Context uses revision history to shape later execution, while the desktop exposes conversation, portfolio, and intervention controls. README documents the major workflow and capabilities; several subsystem links below are based on that documentation and the file tree, not sampled implementation.

Main entry points: [`backend/packages/harness/focus`](https://github.com/leeminjing/focus/tree/main/backend/packages/harness/focus) (Agent runtime), [`backend/app/desktop/agent_loop/patrol.py`](https://github.com/leeminjing/focus/blob/main/backend/app/desktop/agent_loop/patrol.py) (Portfolio Patrol), [`backend/app/desktop/agent_loop`](https://github.com/leeminjing/focus/tree/main/backend/app/desktop/agent_loop) (Agent Loop), [`backend/app/desktop/routes.py`](https://github.com/leeminjing/focus/blob/main/backend/app/desktop/routes.py) (Desktop API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Desktop experience"]
  node_desktop["Focus desktop<br/>[app.js]"]
  node_loop_console["Loop console"]
end

subgraph group_execution["Agent execution"]
  node_run_orchestration["Run orchestration"]
  node_agent_loop["Agent Loop"]
  node_agent_runtime["Agent runtime"]
  node_tooling["Tools and skills"]
  node_workspace["Workspace coordination"]
  node_spatial_plugin["Spatial Patrol plugin"]
end

subgraph group_context["Context operations"]
  node_curation["Context curation"]
  node_expansion["Context expansion"]
  node_context_service["Context service<br/>[context_service.py]"]
  node_revision_store[("Revision repository<br/>[repository.py]")]
end

subgraph group_governance["Portfolio governance"]
  node_patrol["Portfolio Patrol<br/>[patrol.py]"]
  node_kernel{{"Decision Kernel<br/>[kernel.py]"}}
end

subgraph group_platform["Runtime platform"]
  node_gateway["API gateway<br/>[app.py]"]
  node_desktop_api["Desktop API<br/>[routes.py]"]
  node_model_provider["Chat models"]
  node_persistence[("Run persistence")]
end

node_user(("User"))

node_user -->|"operates"| node_desktop
node_desktop -->|"sends API requests"| node_gateway
node_gateway -->|"routes requests"| node_desktop_api
node_desktop -->|"controls Loop"| node_loop_console
node_loop_console -->|"queries and intervenes"| node_desktop_api
node_desktop_api -->|"deploys Runs"| node_run_orchestration
node_run_orchestration -->|"starts execution"| node_agent_loop
node_agent_loop -->|"executes agent"| node_agent_runtime
node_agent_runtime -->|"calls model"| node_model_provider
node_agent_runtime -->|"invokes tools"| node_tooling
node_agent_loop -->|"reports results"| node_patrol
node_patrol -->|"submits decision"| node_kernel
node_kernel -->|"commits control"| node_agent_loop
node_patrol -->|"curates contexts"| node_curation
node_patrol -->|"plans context work"| node_expansion
node_curation -->|"publishes revisions"| node_context_service
node_context_service -->|"reads and writes"| node_revision_store
node_agent_runtime -->|"stores checkpoints"| node_persistence
node_run_orchestration -->|"coordinates workspace"| node_workspace
node_desktop_api -.->|"mounts plugin API"| node_spatial_plugin

click node_desktop "https://github.com/leeminjing/focus/blob/main/desktop/app.js"
click node_loop_console "https://github.com/leeminjing/focus/blob/main/desktop/loop-console-controller.js"
click node_gateway "https://github.com/leeminjing/focus/blob/main/backend/app/gateway/app.py"
click node_desktop_api "https://github.com/leeminjing/focus/blob/main/backend/app/desktop/routes.py"
click node_run_orchestration "https://github.com/leeminjing/focus/tree/main/backend/app/desktop/run_orchestration"
click node_agent_loop "https://github.com/leeminjing/focus/tree/main/backend/app/desktop/agent_loop"
click node_agent_runtime "https://github.com/leeminjing/focus/tree/main/backend/packages/harness/focus"
click node_model_provider "https://github.com/leeminjing/focus/tree/main/backend/packages/harness/focus/models"
click node_tooling "https://github.com/leeminjing/focus/tree/main/backend/packages/harness/focus/tools"
click node_patrol "https://github.com/leeminjing/focus/blob/main/backend/app/desktop/agent_loop/patrol.py"
click node_kernel "https://github.com/leeminjing/focus/blob/main/backend/app/desktop/agent_loop/kernel.py"
click node_curation "https://github.com/leeminjing/focus/tree/main/backend/app/desktop/context_curation"
click node_expansion "https://github.com/leeminjing/focus/tree/main/backend/app/desktop/agent_loop/context_expansion"
click node_context_service "https://github.com/leeminjing/focus/blob/main/backend/app/desktop/context_service.py"
click node_revision_store "https://github.com/leeminjing/focus/blob/main/backend/app/desktop/context_evolution/repository.py"
click node_persistence "https://github.com/leeminjing/focus/tree/main/backend/packages/harness/focus/persistence"
click node_workspace "https://github.com/leeminjing/focus/tree/main/backend/app/desktop/workspace_coordination"
click node_spatial_plugin "https://github.com/leeminjing/focus/tree/main/plugins/spatial-patrol"

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_desktop,node_loop_console,node_user toneBlue
class node_run_orchestration,node_agent_loop,node_agent_runtime,node_tooling,node_workspace,node_spatial_plugin toneAmber
class node_curation,node_expansion,node_context_service,node_revision_store toneMint
class node_patrol,node_kernel toneRose
class node_gateway,node_desktop_api,node_model_provider,node_persistence toneIndigo
```

## Components

### Desktop experience

- [Focus desktop](https://github.com/leeminjing/focus/blob/main/desktop/app.js): `desktop/app.js`
- [Loop console](https://github.com/leeminjing/focus/blob/main/desktop/loop-console-controller.js): `desktop/loop-console-controller.js`

### Agent execution

- [Run orchestration](https://github.com/leeminjing/focus/tree/main/backend/app/desktop/run_orchestration): `backend/app/desktop/run_orchestration`
- [Agent Loop](https://github.com/leeminjing/focus/tree/main/backend/app/desktop/agent_loop): `backend/app/desktop/agent_loop`
- [Agent runtime](https://github.com/leeminjing/focus/tree/main/backend/packages/harness/focus): `backend/packages/harness/focus`
- [Tools and skills](https://github.com/leeminjing/focus/tree/main/backend/packages/harness/focus/tools): `backend/packages/harness/focus/tools`
- [Workspace coordination](https://github.com/leeminjing/focus/tree/main/backend/app/desktop/workspace_coordination): `backend/app/desktop/workspace_coordination`
- [Spatial Patrol plugin](https://github.com/leeminjing/focus/tree/main/plugins/spatial-patrol): `plugins/spatial-patrol`

### Context operations

- [Context curation](https://github.com/leeminjing/focus/tree/main/backend/app/desktop/context_curation): `backend/app/desktop/context_curation`
- [Context expansion](https://github.com/leeminjing/focus/tree/main/backend/app/desktop/agent_loop/context_expansion): `backend/app/desktop/agent_loop/context_expansion`
- [Context service](https://github.com/leeminjing/focus/blob/main/backend/app/desktop/context_service.py): `backend/app/desktop/context_service.py`
- [Revision repository](https://github.com/leeminjing/focus/blob/main/backend/app/desktop/context_evolution/repository.py): `backend/app/desktop/context_evolution/repository.py`

### Portfolio governance

- [Portfolio Patrol](https://github.com/leeminjing/focus/blob/main/backend/app/desktop/agent_loop/patrol.py): `backend/app/desktop/agent_loop/patrol.py`
- [Decision Kernel](https://github.com/leeminjing/focus/blob/main/backend/app/desktop/agent_loop/kernel.py): `backend/app/desktop/agent_loop/kernel.py`

### Runtime platform

- [API gateway](https://github.com/leeminjing/focus/blob/main/backend/app/gateway/app.py): `backend/app/gateway/app.py`
- [Desktop API](https://github.com/leeminjing/focus/blob/main/backend/app/desktop/routes.py): `backend/app/desktop/routes.py`
- [Chat models](https://github.com/leeminjing/focus/tree/main/backend/packages/harness/focus/models): `backend/packages/harness/focus/models`
- [Run persistence](https://github.com/leeminjing/focus/tree/main/backend/packages/harness/focus/persistence): `backend/packages/harness/focus/persistence`

### Other components

- **User**

## Connections

- User → Focus desktop: operates
- Focus desktop → API gateway: sends API requests
- API gateway → Desktop API: routes requests
- Focus desktop → Loop console: controls Loop
- Loop console → Desktop API: queries and intervenes
- Desktop API → Run orchestration: deploys Runs
- Run orchestration → Agent Loop: starts execution
- Agent Loop → Agent runtime: executes agent
- Agent runtime → Chat models: calls model
- Agent runtime → Tools and skills: invokes tools
- Agent Loop → Portfolio Patrol: reports results
- Portfolio Patrol → Decision Kernel: submits decision
- Decision Kernel → Agent Loop: commits control
- Portfolio Patrol → Context curation: curates contexts
- Portfolio Patrol → Context expansion: plans context work
- Context curation → Context service: publishes revisions
- Context service → Revision repository: reads and writes
- Agent runtime → Run persistence: stores checkpoints
- Run orchestration → Workspace coordination: coordinates workspace
- Desktop API → Spatial Patrol plugin: mounts plugin API