# kody-hq/kody architecture

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

- Interactive diagram: https://gitdiagram.com/kody-hq/kody
- Repository: https://github.com/kody-hq/kody

## Overview

Kody is a Cloudflare-based cloud for AI agents, centered on OAuth-protected MCP access to account-scoped packages, storage, credentials, and automations. A host reaches the origin Worker, which routes MCP and website traffic; MCP capabilities authorize access and invoke package storage. The repository also contains jobs, backup, status, desktop, and CLI subsystems. Relationships are limited to README topology and the sampled source references/calls; several major feature implementations are unsampled, so their internal connections are not inferred.

Main entry points: [`packages/worker`](https://github.com/kody-hq/kody/tree/main/packages/worker) (Origin Worker), [`packages/worker/src/mcp/capabilities/storage/storage-query.ts`](https://github.com/kody-hq/kody/blob/main/packages/worker/src/mcp/capabilities/storage/storage-query.ts) (Storage capability), [`packages/backup-control-plane/immutable-storage.ts`](https://github.com/kody-hq/kody/blob/main/packages/backup-control-plane/immutable-storage.ts) (Immutable backup storage), [`packages/status/worker.ts`](https://github.com/kody-hq/kody/blob/main/packages/status/worker.ts) (Status service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and clients"]
  node_origin["Origin Worker"]
  node_website["TanStack website"]
  node_cli["Developer CLI<br/>[cli.ts]"]
  node_desktop["Desktop app<br/>[main.cjs]"]
end

subgraph group_mcp["MCP and storage"]
  node_mcp_oauth["MCP OAuth client"]
  node_sealed_oauth["Sealed OAuth storage"]
  node_storage_cap["Storage capability<br/>[storage-query.ts]"]
  node_storage_runner["Storage runner<br/>[storage-runner.ts]"]
  node_sql_policy["SQL read policy"]
  node_package_codemods["Package codemods<br/>[engine.ts]"]
  node_codemod_ledger[("Codemod ledger<br/>[ledger.ts]")]
end

subgraph group_operations["Platform operations"]
  node_jobs["Job scheduler<br/>[manager-do.ts]"]
  node_job_store[("Job store<br/>[store.ts]")]
end

subgraph group_reliability["Reliability services"]
  node_backup["Backup control plane<br/>[worker.ts]"]
  node_backup_policy["Backup policy<br/>[backup-policy.ts]"]
  node_backup_types["Backup types<br/>[backup-types.ts]"]
  node_immutable_storage["Immutable backup storage"]
  node_status_worker["Status service<br/>[worker.ts]"]
  node_status_page["Status page<br/>[status-page.ts]"]
  node_status_store[("Status store<br/>[status-store.ts]")]
end

subgraph group_internal["Runtime internals"]
  node_cli_service["Execution context<br/>[service.ts]"]
  node_cli_update["Auto update<br/>[auto-update.ts]"]
  node_cli_key["Credential keystore<br/>[keystore.ts]"]
  node_desktop_execution["Desktop execution<br/>[execution.cjs]"]
end

node_agent(("MCP host"))

node_agent -->|"sends MCP requests"| node_origin
node_origin -->|"routes web requests"| node_website
node_origin -->|"handles OAuth requests"| node_mcp_oauth
node_origin -->|"routes MCP requests"| node_storage_cap
node_storage_cap -->|"invokes storage RPC"| node_storage_runner
node_storage_cap -.->|"applies read policy"| node_sql_policy
node_sealed_oauth -->|"loads client metadata"| node_mcp_oauth
node_package_codemods -->|"records runs"| node_codemod_ledger
node_jobs -->|"finds runnable jobs"| node_job_store
node_backup -.->|"uses policy"| node_backup_policy
node_immutable_storage -->|"raises backup errors"| node_backup_policy
node_immutable_storage -->|"uses backup types"| node_backup_types
node_status_worker -->|"serves status page"| node_status_page
node_status_worker -->|"uses status store"| node_status_store
node_cli_service -->|"manages updates"| node_cli_update
node_cli_service -->|"uses keystore"| node_cli_key
node_desktop -->|"coordinates execution"| node_desktop_execution

click node_origin "https://github.com/kody-hq/kody/tree/main/packages/worker"
click node_website "https://github.com/kody-hq/kody/tree/main/packages/worker/start"
click node_cli "https://github.com/kody-hq/kody/blob/main/packages/cli/src/cli.ts"
click node_desktop "https://github.com/kody-hq/kody/blob/main/packages/desktop/main.cjs"
click node_mcp_oauth "https://github.com/kody-hq/kody/blob/main/packages/worker/src/mcp-client/client-id-metadata.ts"
click node_sealed_oauth "https://github.com/kody-hq/kody/blob/main/packages/worker/src/mcp-client/sealed-oauth-storage.ts"
click node_storage_cap "https://github.com/kody-hq/kody/blob/main/packages/worker/src/mcp/capabilities/storage/storage-query.ts"
click node_storage_runner "https://github.com/kody-hq/kody/blob/main/packages/worker/src/storage-runner.ts"
click node_sql_policy "https://github.com/kody-hq/kody/blob/main/packages/shared/src/storage-sql-read-policy.ts"
click node_package_codemods "https://github.com/kody-hq/kody/blob/main/packages/worker/src/package-codemods/engine.ts"
click node_codemod_ledger "https://github.com/kody-hq/kody/blob/main/packages/worker/src/package-codemods/ledger.ts"
click node_jobs "https://github.com/kody-hq/kody/blob/main/packages/jobs-worker/src/manager-do.ts"
click node_job_store "https://github.com/kody-hq/kody/blob/main/packages/jobs-worker/src/store.ts"
click node_backup "https://github.com/kody-hq/kody/blob/main/packages/backup-control-plane/worker.ts"
click node_backup_policy "https://github.com/kody-hq/kody/blob/main/packages/backup-control-plane/backup-policy.ts"
click node_backup_types "https://github.com/kody-hq/kody/blob/main/packages/backup-control-plane/backup-types.ts"
click node_immutable_storage "https://github.com/kody-hq/kody/blob/main/packages/backup-control-plane/immutable-storage.ts"
click node_status_worker "https://github.com/kody-hq/kody/blob/main/packages/status/worker.ts"
click node_status_page "https://github.com/kody-hq/kody/blob/main/packages/status/status-page.ts"
click node_status_store "https://github.com/kody-hq/kody/blob/main/packages/status/status-store.ts"
click node_cli_service "https://github.com/kody-hq/kody/blob/main/packages/cli/src/execution-context/service.ts"
click node_cli_update "https://github.com/kody-hq/kody/blob/main/packages/cli/src/execution-context/auto-update.ts"
click node_cli_key "https://github.com/kody-hq/kody/blob/main/packages/cli/src/execution-context/keystore.ts"
click node_desktop_execution "https://github.com/kody-hq/kody/blob/main/packages/desktop/execution.cjs"

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_origin,node_website,node_cli,node_desktop toneBlue
class node_mcp_oauth,node_sealed_oauth,node_storage_cap,node_storage_runner,node_sql_policy,node_package_codemods,node_codemod_ledger toneAmber
class node_jobs,node_job_store toneMint
class node_backup,node_backup_policy,node_backup_types,node_immutable_storage,node_status_worker,node_status_page,node_status_store toneRose
class node_cli_service,node_cli_update,node_cli_key,node_desktop_execution,node_agent toneIndigo
```

## Components

### Entry and clients

- [Origin Worker](https://github.com/kody-hq/kody/tree/main/packages/worker): `packages/worker`
- [TanStack website](https://github.com/kody-hq/kody/tree/main/packages/worker/start): `packages/worker/start`
- [Developer CLI](https://github.com/kody-hq/kody/blob/main/packages/cli/src/cli.ts): `packages/cli/src/cli.ts`
- [Desktop app](https://github.com/kody-hq/kody/blob/main/packages/desktop/main.cjs): `packages/desktop/main.cjs`

### MCP and storage

- [MCP OAuth client](https://github.com/kody-hq/kody/blob/main/packages/worker/src/mcp-client/client-id-metadata.ts): `packages/worker/src/mcp-client/client-id-metadata.ts`
- [Sealed OAuth storage](https://github.com/kody-hq/kody/blob/main/packages/worker/src/mcp-client/sealed-oauth-storage.ts): `packages/worker/src/mcp-client/sealed-oauth-storage.ts`
- [Storage capability](https://github.com/kody-hq/kody/blob/main/packages/worker/src/mcp/capabilities/storage/storage-query.ts): `packages/worker/src/mcp/capabilities/storage/storage-query.ts`
- [Storage runner](https://github.com/kody-hq/kody/blob/main/packages/worker/src/storage-runner.ts): `packages/worker/src/storage-runner.ts`
- [SQL read policy](https://github.com/kody-hq/kody/blob/main/packages/shared/src/storage-sql-read-policy.ts): `packages/shared/src/storage-sql-read-policy.ts`
- [Package codemods](https://github.com/kody-hq/kody/blob/main/packages/worker/src/package-codemods/engine.ts): `packages/worker/src/package-codemods/engine.ts`
- [Codemod ledger](https://github.com/kody-hq/kody/blob/main/packages/worker/src/package-codemods/ledger.ts): `packages/worker/src/package-codemods/ledger.ts`

### Platform operations

- [Job scheduler](https://github.com/kody-hq/kody/blob/main/packages/jobs-worker/src/manager-do.ts): `packages/jobs-worker/src/manager-do.ts`
- [Job store](https://github.com/kody-hq/kody/blob/main/packages/jobs-worker/src/store.ts): `packages/jobs-worker/src/store.ts`

### Reliability services

- [Backup control plane](https://github.com/kody-hq/kody/blob/main/packages/backup-control-plane/worker.ts): `packages/backup-control-plane/worker.ts`
- [Backup policy](https://github.com/kody-hq/kody/blob/main/packages/backup-control-plane/backup-policy.ts): `packages/backup-control-plane/backup-policy.ts`
- [Backup types](https://github.com/kody-hq/kody/blob/main/packages/backup-control-plane/backup-types.ts): `packages/backup-control-plane/backup-types.ts`
- [Immutable backup storage](https://github.com/kody-hq/kody/blob/main/packages/backup-control-plane/immutable-storage.ts): `packages/backup-control-plane/immutable-storage.ts`
- [Status service](https://github.com/kody-hq/kody/blob/main/packages/status/worker.ts): `packages/status/worker.ts`
- [Status page](https://github.com/kody-hq/kody/blob/main/packages/status/status-page.ts): `packages/status/status-page.ts`
- [Status store](https://github.com/kody-hq/kody/blob/main/packages/status/status-store.ts): `packages/status/status-store.ts`

### Runtime internals

- [Execution context](https://github.com/kody-hq/kody/blob/main/packages/cli/src/execution-context/service.ts): `packages/cli/src/execution-context/service.ts`
- [Auto update](https://github.com/kody-hq/kody/blob/main/packages/cli/src/execution-context/auto-update.ts): `packages/cli/src/execution-context/auto-update.ts`
- [Credential keystore](https://github.com/kody-hq/kody/blob/main/packages/cli/src/execution-context/keystore.ts): `packages/cli/src/execution-context/keystore.ts`
- [Desktop execution](https://github.com/kody-hq/kody/blob/main/packages/desktop/execution.cjs): `packages/desktop/execution.cjs`

### Other components

- **MCP host**

## Connections

- MCP host → Origin Worker: sends MCP requests (evidence: `README.md`)
- Origin Worker → TanStack website: routes web requests (evidence: `README.md`)
- Origin Worker → MCP OAuth client: handles OAuth requests (evidence: `README.md`)
- Origin Worker → Storage capability: routes MCP requests (evidence: `README.md`)
- Storage capability → Storage runner: invokes storage RPC (evidence: `packages/worker/src/mcp/capabilities/storage/storage-query.ts`)
- Storage capability → SQL read policy: applies read policy
- Sealed OAuth storage → MCP OAuth client: loads client metadata (evidence: `packages/worker/src/mcp-client/sealed-oauth-storage.ts`)
- Package codemods → Codemod ledger: records runs (evidence: `packages/worker/src/package-codemods/engine.ts`)
- Job scheduler → Job store: finds runnable jobs (evidence: `packages/jobs-worker/src/manager-do.ts`)
- Backup control plane → Backup policy: uses policy
- Immutable backup storage → Backup policy: raises backup errors (evidence: `packages/backup-control-plane/immutable-storage.ts`)
- Immutable backup storage → Backup types: uses backup types (evidence: `packages/backup-control-plane/backup-types.ts`)
- Status service → Status page: serves status page (evidence: `packages/status/worker.ts`)
- Status service → Status store: uses status store (evidence: `packages/status/worker.ts`)
- Execution context → Auto update: manages updates (evidence: `packages/cli/src/execution-context/service.ts`)
- Execution context → Credential keystore: uses keystore (evidence: `packages/cli/src/execution-context/service.ts`)
- Desktop app → Desktop execution: coordinates execution (evidence: `packages/desktop/main.cjs`)
