# maurdekye/orgtree architecture

> Architecture diagram of the GitHub repository maurdekye/orgtree, 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/maurdekye/orgtree
- Repository: https://github.com/maurdekye/orgtree

## Overview

Orgtree is a Windows desktop workspace for operating persistent, multi-provider coding-agent teams. A user creates or opens an organization, configures agents and permissions, assigns work, then follows conversations and coordinates through the shared docket, mail, questions, and Attention view. The renderer talks to a local Python engine; the engine runs agent/provider integrations and persists organization state and transcript records, with PostgreSQL as the documented database. The map preserves major README capabilities; some subsystem links are documented rather than confirmed in sampled implementation excerpts.

Main entry points: [`apps/desktop/renderer/src/App.tsx`](https://github.com/maurdekye/orgtree/blob/main/apps/desktop/renderer/src/App.tsx) (Workspace UI), [`engine/backend/orgtree/providers.py`](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/providers.py) (Provider runners), [`engine/backend/orgtree/supervisor.py`](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/supervisor.py) (Agent supervisor), [`engine/launch.py`](https://github.com/maurdekye/orgtree/blob/main/engine/launch.py) (Local engine API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_renderer["Workspace UI<br/>[App.tsx]"]
  node_renderer_api["UI API client<br/>[api.ts]"]
  node_desktop_engine["Engine manager<br/>[engine.ts]"]
  node_attention["Attention view<br/>[AttentionView.tsx]"]
end

subgraph group_engine["Engine and agents"]
  node_engine_api["Local engine API<br/>[launch.py]"]
  node_supervisor["Agent supervisor<br/>[supervisor.py]"]
end

subgraph group_workspace["Organization workspace"]
  node_org_state["Org state<br/>[ledger.py]"]
  node_work_docket["Work docket<br/>[workread.py]"]
  node_mail_coordination["Mail and decisions<br/>[reply_events.py]"]
  node_transcript_capture["Transcript capture"]
  node_transcript_records["Transcript records"]
  node_chat_projection["Conversation history<br/>[chat_window.py]"]
  node_migration["V2 data import<br/>[desktop_import.py]"]
end

subgraph group_persistence["Persistence"]
  node_store["Store interface<br/>[store.py]"]
  node_pgstore["PostgreSQL adapter<br/>[pgstore.py]"]
  node_postgres[("PostgreSQL database")]
end

subgraph group_providers["Provider integrations"]
  node_provider_runtime["Provider runners<br/>[providers.py]"]
  node_claude["Claude Code"]
  node_codex["Codex"]
  node_antigravity["Antigravity"]
  node_openrouter["OpenRouter<br/>[openrouter.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_renderer
node_renderer -.->|"requests data"| node_renderer_api
node_renderer_api -.->|"calls API"| node_engine_api
node_desktop_engine -->|"starts and attaches"| node_engine_api
node_engine_api -->|"initializes"| node_supervisor
node_supervisor -.->|"runs agents"| node_provider_runtime
node_provider_runtime -.->|"launches"| node_claude
node_provider_runtime -.->|"launches"| node_codex
node_provider_runtime -.->|"launches"| node_antigravity
node_provider_runtime -.->|"routes models"| node_openrouter
node_supervisor -.->|"updates"| node_org_state
node_renderer -.->|"manages tickets"| node_work_docket
node_renderer -.->|"coordinates work"| node_mail_coordination
node_renderer -->|"shows attention"| node_attention
node_supervisor -->|"captures history"| node_transcript_capture
node_transcript_capture -->|"commits records"| node_transcript_records
node_renderer -.->|"reads conversations"| node_chat_projection
node_chat_projection -->|"reads records"| node_transcript_records
node_store -->|"uses adapter"| node_pgstore
node_pgstore -.->|"persists state"| node_postgres
node_engine_api -->|"offers import"| node_migration
node_migration -.->|"imports organizations"| node_store

click node_renderer "https://github.com/maurdekye/orgtree/blob/main/apps/desktop/renderer/src/App.tsx"
click node_renderer_api "https://github.com/maurdekye/orgtree/blob/main/apps/desktop/renderer/src/api.ts"
click node_desktop_engine "https://github.com/maurdekye/orgtree/blob/main/apps/desktop/main/engine.ts"
click node_engine_api "https://github.com/maurdekye/orgtree/blob/main/engine/launch.py"
click node_supervisor "https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/supervisor.py"
click node_provider_runtime "https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/providers.py"
click node_openrouter "https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/openrouter.py"
click node_org_state "https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/ledger.py"
click node_work_docket "https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/workread.py"
click node_mail_coordination "https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/reply_events.py"
click node_attention "https://github.com/maurdekye/orgtree/blob/main/apps/desktop/renderer/src/attention/AttentionView.tsx"
click node_transcript_capture "https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/transcript_ingest.py"
click node_transcript_records "https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/transcript_records.py"
click node_chat_projection "https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/chat_window.py"
click node_store "https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/store.py"
click node_pgstore "https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/pgstore.py"
click node_migration "https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/desktop_import.py"

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_renderer,node_renderer_api,node_desktop_engine,node_attention,node_user toneBlue
class node_engine_api,node_supervisor toneAmber
class node_org_state,node_work_docket,node_mail_coordination,node_transcript_capture,node_transcript_records,node_chat_projection,node_migration toneMint
class node_store,node_pgstore,node_postgres toneRose
class node_provider_runtime,node_claude,node_codex,node_antigravity,node_openrouter toneIndigo
```

## Components

### Desktop experience

- [Workspace UI](https://github.com/maurdekye/orgtree/blob/main/apps/desktop/renderer/src/App.tsx): `apps/desktop/renderer/src/App.tsx`
- [UI API client](https://github.com/maurdekye/orgtree/blob/main/apps/desktop/renderer/src/api.ts): `apps/desktop/renderer/src/api.ts`
- [Engine manager](https://github.com/maurdekye/orgtree/blob/main/apps/desktop/main/engine.ts): `apps/desktop/main/engine.ts`
- [Attention view](https://github.com/maurdekye/orgtree/blob/main/apps/desktop/renderer/src/attention/AttentionView.tsx): `apps/desktop/renderer/src/attention/AttentionView.tsx`

### Engine and agents

- [Local engine API](https://github.com/maurdekye/orgtree/blob/main/engine/launch.py): `engine/launch.py`
- [Agent supervisor](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/supervisor.py): `engine/backend/orgtree/supervisor.py`

### Organization workspace

- [Org state](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/ledger.py): `engine/backend/orgtree/ledger.py`
- [Work docket](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/workread.py): `engine/backend/orgtree/workread.py`
- [Mail and decisions](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/reply_events.py): `engine/backend/orgtree/reply_events.py`
- [Transcript capture](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/transcript_ingest.py): `engine/backend/orgtree/transcript_ingest.py`
- [Transcript records](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/transcript_records.py): `engine/backend/orgtree/transcript_records.py`
- [Conversation history](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/chat_window.py): `engine/backend/orgtree/chat_window.py`
- [V2 data import](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/desktop_import.py): `engine/backend/orgtree/desktop_import.py`

### Persistence

- [Store interface](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/store.py): `engine/backend/orgtree/store.py`
- [PostgreSQL adapter](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/pgstore.py): `engine/backend/orgtree/pgstore.py`
- **PostgreSQL database**

### Provider integrations

- [Provider runners](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/providers.py): `engine/backend/orgtree/providers.py`
- **Claude Code**
- **Codex**
- **Antigravity**
- [OpenRouter](https://github.com/maurdekye/orgtree/blob/main/engine/backend/orgtree/openrouter.py): `engine/backend/orgtree/openrouter.py`

### Other components

- **User**

## Connections

- User → Workspace UI: uses
- Workspace UI → UI API client: requests data (evidence: `apps/desktop/renderer/src/App.tsx`)
- UI API client → Local engine API: calls API
- Engine manager → Local engine API: starts and attaches (evidence: `apps/desktop/main/engine.ts`)
- Local engine API → Agent supervisor: initializes (evidence: `engine/launch.py`)
- Agent supervisor → Provider runners: runs agents
- Provider runners → Claude Code: launches
- Provider runners → Codex: launches
- Provider runners → Antigravity: launches
- Provider runners → OpenRouter: routes models
- Agent supervisor → Org state: updates
- Workspace UI → Work docket: manages tickets
- Workspace UI → Mail and decisions: coordinates work
- Workspace UI → Attention view: shows attention (evidence: `apps/desktop/renderer/src/App.tsx`)
- Agent supervisor → Transcript capture: captures history (evidence: `engine/backend/orgtree/transcript_ingest.py`)
- Transcript capture → Transcript records: commits records (evidence: `engine/backend/orgtree/transcript_ingest.py`)
- Workspace UI → Conversation history: reads conversations
- Conversation history → Transcript records: reads records (evidence: `engine/backend/orgtree/chat_window.py`)
- Store interface → PostgreSQL adapter: uses adapter (evidence: `engine/backend/orgtree/store.py`)
- PostgreSQL adapter → PostgreSQL database: persists state
- Local engine API → V2 data import: offers import (evidence: `engine/launch.py`)
- V2 data import → Store interface: imports organizations
