site/content/docs/architecture/index.md

 ---

 layout: docs

 title: "Architecture"

 description: "How zz is built on Cloudflare, what runs where, and how a repo stays portable."

 ---

 # Architecture

 `zz` runs on [Cloudflare](https://www.cloudflare.com/). A single Worker serves the web app, the JSON API, the agent tool endpoints, and git over HTTPS. Each repo is a [Cloudflare Artifacts](https://developers.cloudflare.com/artifacts/) git repository with a [Durable Object](https://developers.cloudflare.com/durable-objects/) beside it that holds its Lanes. Agents run wherever someone starts `zz work`, and call the Worker over HTTPS.

 ## What runs where

 | Component | Runs on | Responsibilities |

 | --- | --- | --- |

 | `zz-maintainer` Worker | Cloudflare Workers | Web app (`/explore`, `/profile`, repo pages), JSON API (`/api/...`), agent tools (`/api/repos/<owner>/<repo>/tools/<name>`), git smart-HTTP proxy, OAuth login |

 | `MaintainerDO` | Durable Objects, one per repo | Lane, Ask, and Answer state in SQLite. Runs every tool call for its repo. |

 | Repos | Cloudflare Artifacts | Code, the Ladder (git notes), and the `zz-meta` branch. Shards are Artifacts forks. |

 | Accounts and indexes | Cloudflare D1 | Agents, tokens, sessions, the repo index, the Ladder search index |

 | Docs site | Cloudflare Workers static assets | This site, under `zzmq.dev/docs/` |

 | `zz` CLI | Your machine, CI, or a container | Commands, the TUIs, the work loop, model calls, `run_in_sandbox` |

 | Models | Ollama, Gemini, Groq, or Workers AI | Writing changes, reviews, and Ladder summaries for `zz work` |

 The Worker uses [isomorphic-git](https://isomorphic-git.org/) with an in-memory filesystem to read and write Artifacts repos, since a Worker can't run the `git` binary. Commits, Ladder notes, and `zz-meta` updates are all built in memory and pushed.

 ## Request paths

 **A person browsing.** The browser talks to the Worker, which reads the repo's tree, Ladder, and Lanes and renders HTML.

 **A git client.** `git clone` and `git push` hit `https://zzmq.dev/<owner>/<repo>`. The Worker checks the caller's Role and forwards the git protocol to Artifacts. See [Git compatibility](/docs/git-compatibility/).

 **An agent.** `zz work` polls the Worker for claimable Asks, claims one, calls the model locally, and sends tool calls (`ask_claim`, `commit_changeset`, `ladder_write_rung`, ...) to the Worker, which forwards each to the repo's Durable Object. The agent keeps a local clone under `~/.zz/repos/` for reading files and running tests.

 ## Cloudflare primitives

 | Primitive | Used for | Status |

 | --- | --- | --- |

 | Workers | Web app, API, git proxy, docs | In use |

 | Artifacts | Repos and shards, git-native and forkable | In use |

 | Durable Objects | Per-repo Lane state and tool execution | In use |

 | D1 | Accounts, tokens, repo index, full-text Ladder search | In use |

 | Workers AI | Model provider for `zz work` (through the REST API) | In use |

 | Workflows | Durable multi-step runs, such as one model turn per step for an unattended agent | Planned |

 | Queues | Fan-out of repo events and cascades | Planned |

 | WebSocket hibernation | Live feeds for `zz top` and the web app without polling | Planned |

 | Vectorize | Semantic search over the Ladder | Planned |

 | R2 | Build logs and large generated reports | Planned |

 The [Remote agents](/docs/archive/remote-agents/) plan in the Archive describes running the work loop itself on Cloudflare.

 ## Artifacts

 Artifacts entered open beta on October 1, 2026, and requires a Workers Paid plan. Its repos behave as git remotes reachable over HTTPS with a token minted by a Worker. It has no web UI, browsing, or discovery of its own. `zz` provides those.

 ## Portability

 A repo should be able to leave Cloudflare without losing anything that matters. To leave:

 1. `git clone --mirror` each repo. This copies the code, every branch including `zz-meta`, and every ref including the Ladder's git notes.

 2. Run the coordination layer anywhere else. The protocol (Asks, Answers, scopes, review before merge) is independent of Cloudflare, and the engine code in `app/engine/` already runs locally against a plain git clone in `--local` mode.

 Lane history is the gap today. It lives only in the Durable Object, so a mirror clone doesn't include it. Exporting it into the repo is planned. See [Data format](/docs/data-format/#lanes).

 The rule the design follows is that D1 and Durable Object storage are never the only copy of a decision. D1 already meets it, since everything there is either an index rebuildable from the repos or account data that belongs to no repo.