# hp17695/zeron architecture

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

- Interactive diagram: https://gitdiagram.com/hp17695/zeron
- Repository: https://github.com/hp17695/zeron

## Overview

Zeron is a local-first coding-agent control app with an optional multi-device workspace. A user opens or creates a session, selects an agent, sends prompts, and follows its live transcript and workspace changes; the engine owns agent runs and local session data. The desktop UI also provides file browsing/editing, Markdown previews, comments, and composition. Optional sign-in enables remote access and sync through the edge Worker and Durable Objects. The graph emphasizes documented runtime boundaries; several larger subsystems are represented from the source index or README rather than inspected source excerpts.

Main entry points: [`crates/engine/src/sessions.rs`](https://github.com/hp17695/zeron/blob/main/crates/engine/src/sessions.rs) (Session runs), [`edge/src/index.ts`](https://github.com/hp17695/zeron/blob/main/edge/src/index.ts) (Edge router), [`crates/ui/src/state.rs`](https://github.com/hp17695/zeron/blob/main/crates/ui/src/state.rs) (App state), [`apps/zeron/src/main.rs`](https://github.com/hp17695/zeron/blob/main/apps/zeron/src/main.rs) (Zeron app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["Zeron app<br/>[main.rs]"]
  node_ui_state["App state<br/>[state.rs]"]
  node_composer["Prompt composer<br/>[composer.rs]"]
  node_transcript["Live transcript<br/>[transcript.rs]"]
  node_workspace_ui["File workspace<br/>[preview.rs]"]
  node_markdown["Markdown preview"]
  node_comments["Comments<br/>[comments.rs]"]
  node_comment_ui["Comment UI<br/>[comment_ui.rs]"]
  node_theme["Themes<br/>[theme.rs]"]
end

subgraph group_engine["Local engine"]
  node_rpc["Engine RPC<br/>[rpc.rs]"]
  node_sessions["Session runs<br/>[sessions.rs]"]
  node_doc_host[("Session documents<br/>[doc_host.rs]")]
  node_repos["Repositories<br/>[repos.rs]"]
  node_workspace_host["Workspace access<br/>[workspace_host.rs]"]
  node_uploads["Attachments<br/>[uploads.rs]"]
end

subgraph group_agents["Agent runtime"]
  node_harness["Agent adapters<br/>[lib.rs]"]
end

subgraph group_sync["Remote sync"]
  node_chat_sync["Chat sync client<br/>[chat_client.rs]"]
end

subgraph group_edge["Edge services"]
  node_edge_worker["Edge router<br/>[index.ts]"]
  node_auth_routes["Auth routes<br/>[auth-routes.ts]"]
  node_session_room["Session room<br/>[session-room.ts]"]
  node_chat_room["Chat room<br/>[chat-room.ts]"]
  node_device_room["Device relay<br/>[device-room.ts]"]
  node_preview_room["Preview room<br/>[preview-room.ts]"]
  node_blob_store[("Attachment storage<br/>[blobs.ts]")]
end

node_user(("User"))
node_remote_devices(("Other devices"))
node_agent(("Coding agent"))

node_user -->|"uses"| node_app
node_app -->|"starts engine"| node_sessions
node_ui_state -->|"calls"| node_rpc
node_composer -.->|"submits prompts"| node_ui_state
node_ui_state -.->|"updates view"| node_transcript
node_ui_state -->|"loads files"| node_workspace_ui
node_workspace_ui -->|"renders Markdown"| node_markdown
node_markdown -->|"uses comments"| node_comments
node_markdown -->|"uses comment UI"| node_comment_ui
node_ui_state -->|"manages"| node_comments
node_ui_state -.->|"configures"| node_theme
node_rpc -.->|"dispatches"| node_sessions
node_sessions -->|"streams updates"| node_doc_host
node_sessions -->|"uses"| node_repos
node_sessions -->|"uses"| node_workspace_host
node_sessions -->|"uses"| node_uploads
node_sessions -.->|"runs agents"| node_harness
node_agent -.->|"sends events"| node_sessions
node_sessions -.->|"publishes events"| node_transcript
node_app -.->|"optional sync"| node_edge_worker
node_edge_worker -->|"routes auth"| node_auth_routes
node_edge_worker -.->|"forwards requests"| node_session_room
node_edge_worker -->|"forwards chat"| node_chat_room
node_edge_worker -.->|"forwards device"| node_device_room
node_edge_worker -->|"routes preview"| node_preview_room
node_edge_worker -->|"serves attachments"| node_blob_store
node_chat_sync -.->|"syncs chat"| node_chat_room
node_remote_devices -.->|"follows sessions"| node_chat_sync
node_remote_devices -.->|"accesses workspace"| node_workspace_host

click node_app "https://github.com/hp17695/zeron/blob/main/apps/zeron/src/main.rs"
click node_ui_state "https://github.com/hp17695/zeron/blob/main/crates/ui/src/state.rs"
click node_composer "https://github.com/hp17695/zeron/blob/main/crates/ui/src/composer.rs"
click node_transcript "https://github.com/hp17695/zeron/blob/main/crates/ui/src/transcript.rs"
click node_workspace_ui "https://github.com/hp17695/zeron/blob/main/crates/ui/src/files/preview.rs"
click node_markdown "https://github.com/hp17695/zeron/blob/main/crates/ui/src/files/markdown_preview.rs"
click node_comments "https://github.com/hp17695/zeron/blob/main/crates/ui/src/comments.rs"
click node_comment_ui "https://github.com/hp17695/zeron/blob/main/crates/ui/src/comment_ui.rs"
click node_theme "https://github.com/hp17695/zeron/blob/main/crates/ui/src/theme.rs"
click node_rpc "https://github.com/hp17695/zeron/blob/main/crates/engine/src/rpc.rs"
click node_sessions "https://github.com/hp17695/zeron/blob/main/crates/engine/src/sessions.rs"
click node_doc_host "https://github.com/hp17695/zeron/blob/main/crates/engine/src/doc_host.rs"
click node_repos "https://github.com/hp17695/zeron/blob/main/crates/engine/src/repos.rs"
click node_workspace_host "https://github.com/hp17695/zeron/blob/main/crates/engine/src/workspace_host.rs"
click node_uploads "https://github.com/hp17695/zeron/blob/main/crates/engine/src/uploads.rs"
click node_harness "https://github.com/hp17695/zeron/blob/main/crates/harness/src/lib.rs"
click node_chat_sync "https://github.com/hp17695/zeron/blob/main/crates/sync/src/chat_client.rs"
click node_edge_worker "https://github.com/hp17695/zeron/blob/main/edge/src/index.ts"
click node_auth_routes "https://github.com/hp17695/zeron/blob/main/edge/src/auth-routes.ts"
click node_session_room "https://github.com/hp17695/zeron/blob/main/edge/src/session-room.ts"
click node_chat_room "https://github.com/hp17695/zeron/blob/main/edge/src/chat-room.ts"
click node_device_room "https://github.com/hp17695/zeron/blob/main/edge/src/device-room.ts"
click node_preview_room "https://github.com/hp17695/zeron/blob/main/edge/src/preview-room.ts"
click node_blob_store "https://github.com/hp17695/zeron/blob/main/edge/src/blobs.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_app,node_ui_state,node_composer,node_transcript,node_workspace_ui,node_markdown,node_comments,node_comment_ui,node_theme,node_user toneBlue
class node_rpc,node_sessions,node_doc_host,node_repos,node_workspace_host,node_uploads toneAmber
class node_harness toneMint
class node_chat_sync toneRose
class node_edge_worker,node_auth_routes,node_session_room,node_chat_room,node_device_room,node_preview_room,node_blob_store,node_remote_devices,node_agent toneIndigo
```

## Components

### Client experience

- [Zeron app](https://github.com/hp17695/zeron/blob/main/apps/zeron/src/main.rs): `apps/zeron/src/main.rs`
- [App state](https://github.com/hp17695/zeron/blob/main/crates/ui/src/state.rs): `crates/ui/src/state.rs`
- [Prompt composer](https://github.com/hp17695/zeron/blob/main/crates/ui/src/composer.rs): `crates/ui/src/composer.rs`
- [Live transcript](https://github.com/hp17695/zeron/blob/main/crates/ui/src/transcript.rs): `crates/ui/src/transcript.rs`
- [File workspace](https://github.com/hp17695/zeron/blob/main/crates/ui/src/files/preview.rs): `crates/ui/src/files/preview.rs`
- [Markdown preview](https://github.com/hp17695/zeron/blob/main/crates/ui/src/files/markdown_preview.rs): `crates/ui/src/files/markdown_preview.rs`
- [Comments](https://github.com/hp17695/zeron/blob/main/crates/ui/src/comments.rs): `crates/ui/src/comments.rs`
- [Comment UI](https://github.com/hp17695/zeron/blob/main/crates/ui/src/comment_ui.rs): `crates/ui/src/comment_ui.rs`
- [Themes](https://github.com/hp17695/zeron/blob/main/crates/ui/src/theme.rs): `crates/ui/src/theme.rs`

### Local engine

- [Engine RPC](https://github.com/hp17695/zeron/blob/main/crates/engine/src/rpc.rs): `crates/engine/src/rpc.rs`
- [Session runs](https://github.com/hp17695/zeron/blob/main/crates/engine/src/sessions.rs): `crates/engine/src/sessions.rs`
- [Session documents](https://github.com/hp17695/zeron/blob/main/crates/engine/src/doc_host.rs): `crates/engine/src/doc_host.rs`
- [Repositories](https://github.com/hp17695/zeron/blob/main/crates/engine/src/repos.rs): `crates/engine/src/repos.rs`
- [Workspace access](https://github.com/hp17695/zeron/blob/main/crates/engine/src/workspace_host.rs): `crates/engine/src/workspace_host.rs`
- [Attachments](https://github.com/hp17695/zeron/blob/main/crates/engine/src/uploads.rs): `crates/engine/src/uploads.rs`

### Agent runtime

- [Agent adapters](https://github.com/hp17695/zeron/blob/main/crates/harness/src/lib.rs): `crates/harness/src/lib.rs`

### Remote sync

- [Chat sync client](https://github.com/hp17695/zeron/blob/main/crates/sync/src/chat_client.rs): `crates/sync/src/chat_client.rs`

### Edge services

- [Edge router](https://github.com/hp17695/zeron/blob/main/edge/src/index.ts): `edge/src/index.ts`
- [Auth routes](https://github.com/hp17695/zeron/blob/main/edge/src/auth-routes.ts): `edge/src/auth-routes.ts`
- [Session room](https://github.com/hp17695/zeron/blob/main/edge/src/session-room.ts): `edge/src/session-room.ts`
- [Chat room](https://github.com/hp17695/zeron/blob/main/edge/src/chat-room.ts): `edge/src/chat-room.ts`
- [Device relay](https://github.com/hp17695/zeron/blob/main/edge/src/device-room.ts): `edge/src/device-room.ts`
- [Preview room](https://github.com/hp17695/zeron/blob/main/edge/src/preview-room.ts): `edge/src/preview-room.ts`
- [Attachment storage](https://github.com/hp17695/zeron/blob/main/edge/src/blobs.ts): `edge/src/blobs.ts`

### Other components

- **User**
- **Other devices**
- **Coding agent**

## Connections

- User → Zeron app: uses (evidence: `README.md`)
- Zeron app → Session runs: starts engine (evidence: `apps/zeron/src/main.rs`)
- App state → Engine RPC: calls (evidence: `crates/ui/src/state.rs`)
- Prompt composer → App state: submits prompts
- App state → Live transcript: updates view (evidence: `crates/ui/src/state.rs`)
- App state → File workspace: loads files (evidence: `crates/ui/src/files/preview.rs`)
- File workspace → Markdown preview: renders Markdown (evidence: `crates/ui/src/files/preview.rs`)
- Markdown preview → Comments: uses comments (evidence: `crates/ui/src/files/markdown_preview.rs`)
- Markdown preview → Comment UI: uses comment UI (evidence: `crates/ui/src/files/markdown_preview.rs`)
- App state → Comments: manages (evidence: `crates/ui/src/state.rs`)
- App state → Themes: configures
- Engine RPC → Session runs: dispatches
- Session runs → Session documents: streams updates (evidence: `crates/engine/src/sessions.rs`)
- Session runs → Repositories: uses (evidence: `crates/engine/src/sessions.rs`)
- Session runs → Workspace access: uses (evidence: `crates/engine/src/sessions.rs`)
- Session runs → Attachments: uses (evidence: `crates/engine/src/sessions.rs`)
- Session runs → Agent adapters: runs agents
- Coding agent → Session runs: sends events
- Session runs → Live transcript: publishes events
- Zeron app → Edge router: optional sync (evidence: `README.md`)
- Edge router → Auth routes: routes auth (evidence: `edge/src/index.ts`)
- Edge router → Session room: forwards requests (evidence: `edge/src/index.ts`)
- Edge router → Chat room: forwards chat (evidence: `edge/src/index.ts`)
- Edge router → Device relay: forwards device (evidence: `edge/src/index.ts`)
- Edge router → Preview room: routes preview (evidence: `edge/src/index.ts`)
- Edge router → Attachment storage: serves attachments (evidence: `edge/src/index.ts`)
- Chat sync client → Chat room: syncs chat
- Other devices → Chat sync client: follows sessions (evidence: `README.md`)
- Other devices → Workspace access: accesses workspace (evidence: `README.md`)