# osadeoss/osade architecture

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

- Interactive diagram: https://gitdiagram.com/osadeoss/osade
- Repository: https://github.com/osadeoss/osade

## Overview

Osade is a local-first agentic development environment: users direct coding agents in a desktop workspace, review their changes, verify work, and approve publishing actions. The README documents the user-facing workflow and capabilities; the sampled source confirms desktop task orchestration, daemon routing, and portions of the terminal API. Some runtime links—especially between desktop, daemon, and terminal backend—are not directly shown in the excerpts, so those are marked unverified rather than asserted as calls.

Main entry points: [`apps/desktop/src/renderer/App.tsx`](https://github.com/osadeoss/osade/blob/main/apps/desktop/src/renderer/App.tsx) (Desktop app), [`backend/src/ui.rs`](https://github.com/osadeoss/osade/blob/main/backend/src/ui.rs) (Terminal interface), [`packages/daemon/src/domain/launch-task.ts`](https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/launch-task.ts) (Agent execution), [`packages/daemon/src/server/router.ts`](https://github.com/osadeoss/osade/blob/main/packages/daemon/src/server/router.ts) (Task API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Desktop workspace"]
  node_desktop["Desktop app<br/>[App.tsx]"]
  node_composer["Chat composer<br/>[Composer.tsx]"]
  node_browser["Browser view<br/>[BrowserPane.tsx]"]
  node_files["Files and changes<br/>[Files.tsx]"]
  node_board["Task board<br/>[Board.tsx]"]
end

subgraph group_agents["Agent work"]
  node_task_context["Chat context<br/>[chat-context.ts]"]
  node_agent_runtime["Agent execution<br/>[launch-task.ts]"]
  node_agent_catalog["Agent catalog<br/>[agent-catalog.ts]"]
  node_git_worktrees["Git and worktrees<br/>[git.ts]"]
  node_repo_rules["Repository rules<br/>[repo-rules.ts]"]
  node_knowledge["Repository knowledge<br/>[service.ts]"]
end

subgraph group_review["Review and delivery"]
  node_verification["Verification plans<br/>[verify-plan.ts]"]
  node_approval["Approval gates<br/>[gates.ts]"]
  node_quick_notes["Quick notes<br/>[quick-notes.ts]"]
end

subgraph group_daemon["Daemon services"]
  node_task_api["Task API<br/>[router.ts]"]
  node_task_store[("Task database<br/>[index.ts]")]
end

subgraph group_terminal["Terminal platform"]
  node_terminal_ui["Terminal interface<br/>[ui.rs]"]
  node_terminal_sessions["Terminal sessions"]
  node_terminal_layout["Pane and layout state<br/>[layout.rs]"]
  node_terminal_api["Terminal API<br/>[server.rs]"]
  node_api_schema["API schema<br/>[schema.rs]"]
  node_terminal_config["Terminal configuration<br/>[config.rs]"]
  node_graphics["Terminal graphics<br/>[kitty_graphics.rs]"]
  node_protocol["Wire protocol<br/>[endpoint.rs]"]
  node_session_control["Session control<br/>[session.rs]"]
  node_ipc["Local IPC<br/>[ipc.rs]"]
  node_detection["Agent detection<br/>[manifest_update.rs]"]
  node_terminal_client["Terminal client"]
  node_terminal_events["API subscriptions<br/>[subscriptions.rs]"]
  node_terminal_state["Application state<br/>[state.rs]"]
  node_release_notes["Release notes<br/>[release_notes.rs]"]
  node_raw_input["Input handling<br/>[raw_input.rs]"]
end

node_user(("Developer"))
node_scm(("Source control host"))

node_user -->|"opens repository"| node_desktop
node_desktop -->|"starts conversations"| node_composer
node_composer -.->|"selects agents"| node_agent_catalog
node_desktop -.->|"requests task services"| node_task_api
node_task_api -->|"reads and writes"| node_task_store
node_task_api -->|"builds chat context"| node_task_context
node_task_api -->|"launches agents"| node_agent_runtime
node_agent_runtime -->|"isolates work"| node_git_worktrees
node_agent_runtime -->|"loads repository rules"| node_repo_rules
node_agent_runtime -->|"includes open notes"| node_quick_notes
node_agent_runtime -.->|"uses repository knowledge"| node_knowledge
node_desktop -->|"shows task status"| node_board
node_desktop -->|"reviews changes"| node_files
node_desktop -->|"shows running app"| node_browser
node_task_api -->|"proposes checks"| node_verification
node_verification -->|"gates outward actions"| node_approval
node_approval -->|"publishes with approval"| node_scm
node_knowledge -->|"fetches review corpus"| node_scm
node_desktop -->|"provides terminal workspace"| node_terminal_ui
node_terminal_ui -->|"restores sessions"| node_terminal_sessions
node_terminal_sessions -.->|"organizes panes"| node_terminal_layout
node_terminal_api -->|"handles requests"| node_api_schema
node_terminal_api -->|"uses local sockets"| node_ipc
node_terminal_api -.->|"dispatches API requests"| node_terminal_state
node_terminal_client -->|"connects thin clients"| node_terminal_ui
node_terminal_client -->|"uses wire protocol"| node_protocol
node_terminal_client -->|"forwards input"| node_raw_input
node_terminal_api -.->|"streams updates"| node_terminal_events
node_terminal_ui -.->|"uses configuration"| node_terminal_config
node_terminal_ui -.->|"renders terminal graphics"| node_graphics
node_session_control -->|"derives socket paths"| node_ipc
node_terminal_state -.->|"tracks agent state"| node_detection
node_terminal_ui -.->|"shows release notes"| node_release_notes

click node_desktop "https://github.com/osadeoss/osade/blob/main/apps/desktop/src/renderer/App.tsx"
click node_composer "https://github.com/osadeoss/osade/blob/main/apps/desktop/src/renderer/Composer.tsx"
click node_browser "https://github.com/osadeoss/osade/blob/main/apps/desktop/src/renderer/BrowserPane.tsx"
click node_files "https://github.com/osadeoss/osade/blob/main/apps/desktop/src/renderer/Files.tsx"
click node_board "https://github.com/osadeoss/osade/blob/main/apps/desktop/src/renderer/Board.tsx"
click node_task_api "https://github.com/osadeoss/osade/blob/main/packages/daemon/src/server/router.ts"
click node_task_store "https://github.com/osadeoss/osade/blob/main/packages/daemon/src/db/index.ts"
click node_task_context "https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/chat-context.ts"
click node_agent_runtime "https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/launch-task.ts"
click node_agent_catalog "https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/agent-catalog.ts"
click node_git_worktrees "https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/git.ts"
click node_repo_rules "https://github.com/osadeoss/osade/blob/main/packages/daemon/src/knowledge/repo-rules.ts"
click node_verification "https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/verify-plan.ts"
click node_approval "https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/gates.ts"
click node_quick_notes "https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/quick-notes.ts"
click node_knowledge "https://github.com/osadeoss/osade/blob/main/packages/daemon/src/knowledge/service.ts"
click node_terminal_ui "https://github.com/osadeoss/osade/blob/main/backend/src/ui.rs"
click node_terminal_sessions "https://github.com/osadeoss/osade/tree/main/backend/src/terminal"
click node_terminal_layout "https://github.com/osadeoss/osade/blob/main/backend/src/layout.rs"
click node_terminal_api "https://github.com/osadeoss/osade/blob/main/backend/src/api/server.rs"
click node_api_schema "https://github.com/osadeoss/osade/blob/main/backend/src/api/schema.rs"
click node_terminal_config "https://github.com/osadeoss/osade/blob/main/backend/src/config.rs"
click node_graphics "https://github.com/osadeoss/osade/blob/main/backend/src/kitty_graphics.rs"
click node_protocol "https://github.com/osadeoss/osade/blob/main/backend/src/protocol/endpoint.rs"
click node_session_control "https://github.com/osadeoss/osade/blob/main/backend/src/session.rs"
click node_ipc "https://github.com/osadeoss/osade/blob/main/backend/src/ipc.rs"
click node_detection "https://github.com/osadeoss/osade/blob/main/backend/src/detect/manifest_update.rs"
click node_terminal_client "https://github.com/osadeoss/osade/blob/main/backend/src/server/client_transport.rs"
click node_terminal_events "https://github.com/osadeoss/osade/blob/main/backend/src/api/subscriptions.rs"
click node_terminal_state "https://github.com/osadeoss/osade/blob/main/backend/src/app/state.rs"
click node_release_notes "https://github.com/osadeoss/osade/blob/main/backend/src/release_notes.rs"
click node_raw_input "https://github.com/osadeoss/osade/blob/main/backend/src/raw_input.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_desktop,node_composer,node_browser,node_files,node_board toneBlue
class node_task_context,node_agent_runtime,node_agent_catalog,node_git_worktrees,node_repo_rules,node_knowledge toneAmber
class node_verification,node_approval,node_quick_notes toneMint
class node_task_api,node_task_store toneRose
class node_terminal_ui,node_terminal_sessions,node_terminal_layout,node_terminal_api,node_api_schema,node_terminal_config,node_graphics,node_protocol,node_session_control,node_ipc,node_detection,node_terminal_client,node_terminal_events,node_terminal_state,node_release_notes,node_raw_input,node_user,node_scm toneIndigo
```

## Components

### Desktop workspace

- [Desktop app](https://github.com/osadeoss/osade/blob/main/apps/desktop/src/renderer/App.tsx): `apps/desktop/src/renderer/App.tsx`
- [Chat composer](https://github.com/osadeoss/osade/blob/main/apps/desktop/src/renderer/Composer.tsx): `apps/desktop/src/renderer/Composer.tsx`
- [Browser view](https://github.com/osadeoss/osade/blob/main/apps/desktop/src/renderer/BrowserPane.tsx): `apps/desktop/src/renderer/BrowserPane.tsx`
- [Files and changes](https://github.com/osadeoss/osade/blob/main/apps/desktop/src/renderer/Files.tsx): `apps/desktop/src/renderer/Files.tsx`
- [Task board](https://github.com/osadeoss/osade/blob/main/apps/desktop/src/renderer/Board.tsx): `apps/desktop/src/renderer/Board.tsx`

### Agent work

- [Chat context](https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/chat-context.ts): `packages/daemon/src/domain/chat-context.ts`
- [Agent execution](https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/launch-task.ts): `packages/daemon/src/domain/launch-task.ts`
- [Agent catalog](https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/agent-catalog.ts): `packages/daemon/src/domain/agent-catalog.ts`
- [Git and worktrees](https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/git.ts): `packages/daemon/src/domain/git.ts`
- [Repository rules](https://github.com/osadeoss/osade/blob/main/packages/daemon/src/knowledge/repo-rules.ts): `packages/daemon/src/knowledge/repo-rules.ts`
- [Repository knowledge](https://github.com/osadeoss/osade/blob/main/packages/daemon/src/knowledge/service.ts): `packages/daemon/src/knowledge/service.ts`

### Review and delivery

- [Verification plans](https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/verify-plan.ts): `packages/daemon/src/domain/verify-plan.ts`
- [Approval gates](https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/gates.ts): `packages/daemon/src/domain/gates.ts`
- [Quick notes](https://github.com/osadeoss/osade/blob/main/packages/daemon/src/domain/quick-notes.ts): `packages/daemon/src/domain/quick-notes.ts`

### Daemon services

- [Task API](https://github.com/osadeoss/osade/blob/main/packages/daemon/src/server/router.ts): `packages/daemon/src/server/router.ts`
- [Task database](https://github.com/osadeoss/osade/blob/main/packages/daemon/src/db/index.ts): `packages/daemon/src/db/index.ts`

### Terminal platform

- [Terminal interface](https://github.com/osadeoss/osade/blob/main/backend/src/ui.rs): `backend/src/ui.rs`
- [Terminal sessions](https://github.com/osadeoss/osade/tree/main/backend/src/terminal): `backend/src/terminal`
- [Pane and layout state](https://github.com/osadeoss/osade/blob/main/backend/src/layout.rs): `backend/src/layout.rs`
- [Terminal API](https://github.com/osadeoss/osade/blob/main/backend/src/api/server.rs): `backend/src/api/server.rs`
- [API schema](https://github.com/osadeoss/osade/blob/main/backend/src/api/schema.rs): `backend/src/api/schema.rs`
- [Terminal configuration](https://github.com/osadeoss/osade/blob/main/backend/src/config.rs): `backend/src/config.rs`
- [Terminal graphics](https://github.com/osadeoss/osade/blob/main/backend/src/kitty_graphics.rs): `backend/src/kitty_graphics.rs`
- [Wire protocol](https://github.com/osadeoss/osade/blob/main/backend/src/protocol/endpoint.rs): `backend/src/protocol/endpoint.rs`
- [Session control](https://github.com/osadeoss/osade/blob/main/backend/src/session.rs): `backend/src/session.rs`
- [Local IPC](https://github.com/osadeoss/osade/blob/main/backend/src/ipc.rs): `backend/src/ipc.rs`
- [Agent detection](https://github.com/osadeoss/osade/blob/main/backend/src/detect/manifest_update.rs): `backend/src/detect/manifest_update.rs`
- [Terminal client](https://github.com/osadeoss/osade/blob/main/backend/src/server/client_transport.rs): `backend/src/server/client_transport.rs`
- [API subscriptions](https://github.com/osadeoss/osade/blob/main/backend/src/api/subscriptions.rs): `backend/src/api/subscriptions.rs`
- [Application state](https://github.com/osadeoss/osade/blob/main/backend/src/app/state.rs): `backend/src/app/state.rs`
- [Release notes](https://github.com/osadeoss/osade/blob/main/backend/src/release_notes.rs): `backend/src/release_notes.rs`
- [Input handling](https://github.com/osadeoss/osade/blob/main/backend/src/raw_input.rs): `backend/src/raw_input.rs`

### Other components

- **Developer**
- **Source control host**

## Connections

- Developer → Desktop app: opens repository (evidence: `README.md`)
- Desktop app → Chat composer: starts conversations (evidence: `README.md`)
- Chat composer → Agent catalog: selects agents
- Desktop app → Task API: requests task services
- Task API → Task database: reads and writes (evidence: `packages/daemon/src/server/router.ts`)
- Task API → Chat context: builds chat context (evidence: `packages/daemon/src/server/router.ts`)
- Task API → Agent execution: launches agents (evidence: `packages/daemon/src/server/router.ts`)
- Agent execution → Git and worktrees: isolates work (evidence: `README.md`)
- Agent execution → Repository rules: loads repository rules (evidence: `README.md`)
- Agent execution → Quick notes: includes open notes (evidence: `README.md`)
- Agent execution → Repository knowledge: uses repository knowledge
- Desktop app → Task board: shows task status (evidence: `README.md`)
- Desktop app → Files and changes: reviews changes (evidence: `README.md`)
- Desktop app → Browser view: shows running app (evidence: `README.md`)
- Task API → Verification plans: proposes checks (evidence: `README.md`)
- Verification plans → Approval gates: gates outward actions (evidence: `README.md`)
- Approval gates → Source control host: publishes with approval (evidence: `README.md`)
- Repository knowledge → Source control host: fetches review corpus (evidence: `packages/daemon/src/knowledge/service.ts`)
- Desktop app → Terminal interface: provides terminal workspace (evidence: `README.md`)
- Terminal interface → Terminal sessions: restores sessions (evidence: `README.md`)
- Terminal sessions → Pane and layout state: organizes panes
- Terminal API → API schema: handles requests (evidence: `backend/src/api/server.rs`)
- Terminal API → Local IPC: uses local sockets (evidence: `backend/src/api/server.rs`)
- Terminal API → Application state: dispatches API requests
- Terminal client → Terminal interface: connects thin clients (evidence: `backend/src/server/client_transport.rs`)
- Terminal client → Wire protocol: uses wire protocol (evidence: `backend/src/server/client_transport.rs`)
- Terminal client → Input handling: forwards input (evidence: `backend/src/server/client_transport.rs`)
- Terminal API → API subscriptions: streams updates (evidence: `backend/src/api/server.rs`)
- Terminal interface → Terminal configuration: uses configuration
- Terminal interface → Terminal graphics: renders terminal graphics (evidence: `backend/src/kitty_graphics.rs`)
- Session control → Local IPC: derives socket paths (evidence: `backend/src/session.rs`)
- Application state → Agent detection: tracks agent state
- Terminal interface → Release notes: shows release notes
