Architecture
Understanding Dojo’s architecture helps you reason about how things work and why certain design choices were made.
Remote-first
Section titled “Remote-first”Dojo is a remote-first version control system. The server is always the source of truth:
- Push to persist — your local commits exist locally until you push
- Pull to sync — get the latest changes from the server
- No central clone needed for agents — agents work through remote workspaces via the API
This means you never have “I forgot to push” problems — the server always has the latest state.
Per-repository isolation
Section titled “Per-repository isolation”Each repository is fully isolated with its own storage:
- Commits, trees, and blobs are stored per-repo
- Workspaces exist within a single repo
- Search indexes are scoped to a single repo
- Operations (undo/redo) are per-repo
This means one repository can never affect another’s performance or data.
The data model
Section titled “The data model”Objects
Section titled “Objects”Like Git, Dojo stores data as content-addressed objects:
| Object | Description |
|---|---|
| Commit | A snapshot pointing to a tree, with parent(s), author, message |
| Tree | A directory listing: entries with names, kinds (blob/tree), and hashes |
| Blob | Raw file content, identified by SHA-256 hash |
Named pointers to commits:
- Bookmarks — like Git branches.
main,feature/auth, etc. - Refs are updated atomically with optimistic concurrency control
Workspaces
Section titled “Workspaces”Remote sandboxes for agents:
- Based on a specific commit
- Maintain an overlay of changed files (adds, modifies, deletes)
- Support multiple commits within a session
- Can be submitted as stacks for review
Manifests and indexes
Section titled “Manifests and indexes”For performance, Dojo maintains derived data:
- File manifest — a flat index of all files at each ref tip, enabling instant directory listing
- FTS5 search index — full-text search across file contents, built and maintained incrementally
These are rebuilt automatically if lost — they’re derived from the underlying objects.
Sync protocol
Section titled “Sync protocol”The CLI communicates with the server using a three-phase sync:
- Negotiate — client and server exchange heads to determine what’s missing
- Push — client sends new objects (commits, trees, blobs) and ref updates
- Pull — client requests objects it doesn’t have
Ref updates use optimistic concurrency: if a ref has moved since your last sync, the push is rejected and you need to pull first.
Event system
Section titled “Event system”When things happen in a repository, Dojo emits events:
- Activity feed — visible in the web UI
- Webhooks — HTTP callbacks to your endpoints, signed with HMAC-SHA256
Events include pushes, stack submissions, reviews, workspace activity, and more.
Performance characteristics
Section titled “Performance characteristics”| Operation | Speed | Notes |
|---|---|---|
| Directory listing | Instant | Materialized file manifest |
| Full-text search | Fast | FTS5 index, ranked results |
| Push | Proportional to changes | Only new objects are sent |
| Workspace write | Instant | Overlay-based, no full tree rebuild |
| Workspace commit | Fast | Merges overlay into tree |