# homietal/zcode architecture

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

- Interactive diagram: https://gitdiagram.com/homietal/zcode
- Repository: https://github.com/homietal/zcode

## Overview

ZCode is an AI coding workbench spanning desktop, browser, and terminal experiences. The primary workflow is a user working in a project through one of those interfaces, with backend services and the Agent CLI/runtime providing coding functionality. The repository also includes provider integrations and a dynamic-workflow engine. The README documents the product surfaces and their broad runtime relationships; sampled source confirms selected storage, protocol, and workflow internals, but not every cross-package connection.

Main entry points: [`apps/zcode-cli`](https://github.com/homietal/zcode/tree/main/apps/zcode-cli) (Agent CLI and TUI), [`packages/server`](https://github.com/homietal/zcode/tree/main/packages/server) (HTTP and WS server), [`packages/web`](https://github.com/homietal/zcode/tree/main/packages/web) (Web client), [`packages/desktop`](https://github.com/homietal/zcode/tree/main/packages/desktop) (Desktop app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_desktop["Desktop app"]
  node_web["Web client"]
  node_shared_ui["Shared UI"]
  node_share_preview["Share preview"]
end

subgraph group_backend["Backend services"]
  node_server["HTTP and WS server"]
  node_server_cli["Server launcher<br/>[main.ts]"]
  node_services["Business services"]
  node_shared_protocol["Shared protocols"]
  node_rpc["RPC framework"]
end

subgraph group_agent["Agent runtime"]
  node_agent_cli["Agent CLI and TUI"]
  node_bootstrap["Agent bootstrap"]
  node_workflow["Workflow engine<br/>[engine.ts]"]
  node_artifacts["Workflow artifacts"]
end

subgraph group_integrations["Integrations and state"]
  node_adapters["Runtime adapters"]
  node_provider["Provider services"]
  node_storage[("Session storage")]
  node_desktop_storage["Desktop storage scan"]
  node_storage_ui["Storage UI hook<br/>[useStorageUsage.ts]"]
end

node_user(("Developer"))

node_user -->|"uses"| node_desktop
node_user -->|"uses"| node_web
node_user -->|"runs"| node_agent_cli
node_desktop -.->|"connects to"| node_server
node_web -->|"proxies requests"| node_server
node_desktop -.->|"presents"| node_shared_ui
node_web -.->|"presents"| node_shared_ui
node_server_cli -.->|"starts"| node_server
node_server -.->|"uses"| node_services
node_services -->|"uses"| node_shared_protocol
node_server -.->|"uses"| node_rpc
node_agent_cli -.->|"initializes"| node_bootstrap
node_agent_cli -->|"runs workflows"| node_workflow
node_workflow -->|"delegates to"| node_artifacts
node_agent_cli -.->|"uses"| node_adapters
node_agent_cli -.->|"calls providers"| node_provider
node_adapters -.->|"persists sessions"| node_storage
node_desktop_storage -->|"creates storage service"| node_services
node_storage_ui -.->|"requests scans"| node_desktop_storage
node_web -.->|"loads previews"| node_share_preview

click node_desktop "https://github.com/homietal/zcode/tree/main/packages/desktop"
click node_web "https://github.com/homietal/zcode/tree/main/packages/web"
click node_shared_ui "https://github.com/homietal/zcode/tree/main/packages/ui"
click node_server "https://github.com/homietal/zcode/tree/main/packages/server"
click node_server_cli "https://github.com/homietal/zcode/blob/main/packages/zcode-server-cli/src/main.ts"
click node_services "https://github.com/homietal/zcode/tree/main/packages/services"
click node_shared_protocol "https://github.com/homietal/zcode/tree/main/packages/shared"
click node_rpc "https://github.com/homietal/zcode/tree/main/packages/rpc"
click node_agent_cli "https://github.com/homietal/zcode/tree/main/apps/zcode-cli"
click node_bootstrap "https://github.com/homietal/zcode/tree/main/apps/zcode-cli/packages/bootstrap/src/app"
click node_workflow "https://github.com/homietal/zcode/blob/main/apps/zcode-cli/packages/dynamic-workflow/src/engine/engine.ts"
click node_artifacts "https://github.com/homietal/zcode/blob/main/apps/zcode-cli/packages/dynamic-workflow/src/engine/engine-artifacts.ts"
click node_adapters "https://github.com/homietal/zcode/tree/main/apps/zcode-cli/packages/adapters/src"
click node_provider "https://github.com/homietal/zcode/tree/main/packages/provider"
click node_storage "https://github.com/homietal/zcode/blob/main/apps/zcode-cli/packages/adapters/src/storage/session-store/sqlite-session-store.ts"
click node_desktop_storage "https://github.com/homietal/zcode/blob/main/packages/desktop/src/main/resourceManagerStorage.ts"
click node_storage_ui "https://github.com/homietal/zcode/blob/main/packages/ui/src/resource-manager/storage/useStorageUsage.ts"
click node_share_preview "https://github.com/homietal/zcode/blob/main/packages/web/src/share/conversationSharePreviewClient.ts"

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_web,node_shared_ui,node_share_preview toneBlue
class node_server,node_server_cli,node_services,node_shared_protocol,node_rpc toneAmber
class node_agent_cli,node_bootstrap,node_workflow,node_artifacts toneMint
class node_adapters,node_provider,node_storage,node_desktop_storage,node_storage_ui toneRose
class node_user toneIndigo
```

## Components

### User surfaces

- [Desktop app](https://github.com/homietal/zcode/tree/main/packages/desktop): `packages/desktop`
- [Web client](https://github.com/homietal/zcode/tree/main/packages/web): `packages/web`
- [Shared UI](https://github.com/homietal/zcode/tree/main/packages/ui): `packages/ui`
- [Share preview](https://github.com/homietal/zcode/blob/main/packages/web/src/share/conversationSharePreviewClient.ts): `packages/web/src/share/conversationSharePreviewClient.ts`

### Backend services

- [HTTP and WS server](https://github.com/homietal/zcode/tree/main/packages/server): `packages/server`
- [Server launcher](https://github.com/homietal/zcode/blob/main/packages/zcode-server-cli/src/main.ts): `packages/zcode-server-cli/src/main.ts`
- [Business services](https://github.com/homietal/zcode/tree/main/packages/services): `packages/services`
- [Shared protocols](https://github.com/homietal/zcode/tree/main/packages/shared): `packages/shared`
- [RPC framework](https://github.com/homietal/zcode/tree/main/packages/rpc): `packages/rpc`

### Agent runtime

- [Agent CLI and TUI](https://github.com/homietal/zcode/tree/main/apps/zcode-cli): `apps/zcode-cli`
- [Agent bootstrap](https://github.com/homietal/zcode/tree/main/apps/zcode-cli/packages/bootstrap/src/app): `apps/zcode-cli/packages/bootstrap/src/app`
- [Workflow engine](https://github.com/homietal/zcode/blob/main/apps/zcode-cli/packages/dynamic-workflow/src/engine/engine.ts): `apps/zcode-cli/packages/dynamic-workflow/src/engine/engine.ts`
- [Workflow artifacts](https://github.com/homietal/zcode/blob/main/apps/zcode-cli/packages/dynamic-workflow/src/engine/engine-artifacts.ts): `apps/zcode-cli/packages/dynamic-workflow/src/engine/engine-artifacts.ts`

### Integrations and state

- [Runtime adapters](https://github.com/homietal/zcode/tree/main/apps/zcode-cli/packages/adapters/src): `apps/zcode-cli/packages/adapters/src`
- [Provider services](https://github.com/homietal/zcode/tree/main/packages/provider): `packages/provider`
- [Session storage](https://github.com/homietal/zcode/blob/main/apps/zcode-cli/packages/adapters/src/storage/session-store/sqlite-session-store.ts): `apps/zcode-cli/packages/adapters/src/storage/session-store/sqlite-session-store.ts`
- [Desktop storage scan](https://github.com/homietal/zcode/blob/main/packages/desktop/src/main/resourceManagerStorage.ts): `packages/desktop/src/main/resourceManagerStorage.ts`
- [Storage UI hook](https://github.com/homietal/zcode/blob/main/packages/ui/src/resource-manager/storage/useStorageUsage.ts): `packages/ui/src/resource-manager/storage/useStorageUsage.ts`

### Other components

- **Developer**

## Connections

- Developer → Desktop app: uses (evidence: `README.md`)
- Developer → Web client: uses (evidence: `README.md`)
- Developer → Agent CLI and TUI: runs (evidence: `README.md`)
- Desktop app → HTTP and WS server: connects to
- Web client → HTTP and WS server: proxies requests (evidence: `README.md`)
- Desktop app → Shared UI: presents
- Web client → Shared UI: presents
- Server launcher → HTTP and WS server: starts
- HTTP and WS server → Business services: uses
- Business services → Shared protocols: uses (evidence: `packages/services/src/zcode-agent/zcodeStorageStartupGate.ts`)
- HTTP and WS server → RPC framework: uses
- Agent CLI and TUI → Agent bootstrap: initializes (evidence: `apps/zcode-cli/packages/bootstrap/src/app/workspace-hook-review-controller.ts`)
- Agent CLI and TUI → Workflow engine: runs workflows (evidence: `README.md`)
- Workflow engine → Workflow artifacts: delegates to (evidence: `apps/zcode-cli/packages/dynamic-workflow/src/engine/engine.ts`)
- Agent CLI and TUI → Runtime adapters: uses
- Agent CLI and TUI → Provider services: calls providers
- Runtime adapters → Session storage: persists sessions
- Desktop storage scan → Business services: creates storage service (evidence: `packages/desktop/src/main/resourceManagerStorage.ts`)
- Storage UI hook → Desktop storage scan: requests scans
- Web client → Share preview: loads previews (evidence: `packages/web/src/share/mockConversationSharePreviewClient.ts`)