Add a layered architecture diagram of byre to docs
This commit is contained in:
Ian Gulliver
@@ -34,6 +34,7 @@ The app updates itself, and the server along with it on the Mac byre runs on. To
|
||||
|
||||
## Docs
|
||||
|
||||
- [docs/architecture.md](docs/architecture.md): a layered diagram of byre, from the Macs and tailnet down to the server's and app's components.
|
||||
- [docs/operations.md](docs/operations.md): external setup, vendor and platform quirks, and the intent behind byre's rules.
|
||||
- [docs/macos.md](docs/macos.md): the macOS app.
|
||||
- [docs/clean-install-vm.md](docs/clean-install-vm.md): testing a first-time install on a fresh Mac in a VM.
|
||||
|
||||
@@ -0,0 +1,122 @@
|
||||
# Architecture
|
||||
|
||||
byre from the system down to its software layers. Open a box with the magnifier mark (Server Mac, byre serve, the Manager, Byre.app on Mac) to see the layer inside it. The diagram syntax is the `diagrams` knowledge-base article.
|
||||
|
||||
```diagram
|
||||
row
|
||||
user "You" "on your Macs and iPhone"
|
||||
row
|
||||
mac "Byre.app on Mac" "SwiftUI · two panes" blue
|
||||
phone "Byre on iPhone" "same app, tab bar" blue
|
||||
icloud "iCloud" "CloudKit sync of app prefs" green
|
||||
dl "dl.byre.run" "Sparkle appcast + dmg" green
|
||||
row
|
||||
tailnet "Tailscale tailnet" "each app and server is its own node · identity = auth"
|
||||
row
|
||||
servermac "Server Mac" "launchd service run.fc.byre" amber
|
||||
vendors "Agent vendors" "Anthropic · OpenAI · Google" green
|
||||
origin "git remote" "origin: fetch · push" green
|
||||
user -> mac
|
||||
user -> phone
|
||||
mac -> tailnet "REST · SSE · WebSockets"
|
||||
phone -> tailnet
|
||||
mac ..> icloud
|
||||
mac ..> dl "updates"
|
||||
tailnet -> servermac "HTTPS on byre's ts.net name"
|
||||
servermac -> vendors "agent CLIs"
|
||||
servermac -> origin "merge · push"
|
||||
|
||||
inside servermac
|
||||
row
|
||||
service "byre serve" "Contents/Helpers/byre" amber
|
||||
row
|
||||
clis "Agent CLIs" "one process group per session"
|
||||
claude_cli "claude"
|
||||
codex_cli "codex"
|
||||
agy_cli "agy"
|
||||
hands_srv "byre-hands" "screen · AX · Orion · Chrome, one copy per session"
|
||||
row
|
||||
repos "Project checkouts" "default branch + task worktrees" green
|
||||
data "Data dir" "byre.db · loopback-token · codex home" green
|
||||
service -> clis "spawn · stream-json / app-server"
|
||||
clis -> service "MCP tools · hooks over loopback"
|
||||
clis -> hands_srv "MCP stdio"
|
||||
clis -> repos "edit · commit"
|
||||
service -> repos "snapshots · merge"
|
||||
service -> data
|
||||
|
||||
inside service
|
||||
row
|
||||
listen "Listeners" "cmd/byre serve"
|
||||
tsnet "tsnet node" "Tailscale whois → user"
|
||||
loop "loopback 127.0.0.1" "bearer token, scripts"
|
||||
row
|
||||
http "internal/server" "REST (api/openapi.yaml) · SSE hub · client & terminal WebSockets · preview ports" blue
|
||||
aside store "internal/store" "SQLite WAL, migrations" green
|
||||
row
|
||||
mgr "internal/agents · Manager" "tasks · lead · reviews · workflows · merges" amber
|
||||
row
|
||||
vendor "Vendor adapters" "one session per agent"
|
||||
claude "internal/claude" "stream-json"
|
||||
codex "internal/codex" "app-server JSON-RPC"
|
||||
agy "internal/antigravity" "stream-json · MCP proxy"
|
||||
tools "Agent-facing"
|
||||
mcp "internal/mcp" "byre tools over HTTP"
|
||||
hook "internal/hookcmd" "hooks via curl"
|
||||
row
|
||||
infra "Infrastructure"
|
||||
git "internal/git" "worktrees · snapshots · notes"
|
||||
term "internal/terminal" "PTYs · OSC 133"
|
||||
clients "internal/clients" "client Mac requests"
|
||||
wf "internal/workflow · schedule · todo"
|
||||
tsnet -> http
|
||||
loop -> http
|
||||
http -> mgr "start · message · merge"
|
||||
mgr -> vendor
|
||||
mgr -> tools
|
||||
mgr -> infra
|
||||
mgr -> store "writes"
|
||||
store ..> http "events → SSE"
|
||||
store ..> mgr "poke coordinator"
|
||||
|
||||
inside mgr
|
||||
row
|
||||
coord "coordinator" "level-triggered, one goroutine" amber
|
||||
live "live sessions" "turns · inbox · turn-end commit"
|
||||
row
|
||||
lead "lead agent" "per user · notes"
|
||||
tasks "tasks" "fork · subtasks · teams"
|
||||
review "reviews · audits" "workflow runs"
|
||||
row
|
||||
workers "workers" "merge · push · snapshot · discard"
|
||||
coord -> workers "start (in-progress column)"
|
||||
live -> workers "turn end"
|
||||
coord -> review
|
||||
coord -> lead "deliveries"
|
||||
|
||||
inside mac
|
||||
row
|
||||
ui "Views" "Panes · Chat · Composer · Sheet · Switcher" blue
|
||||
row
|
||||
appstore "Store" "in-memory state of every task" amber
|
||||
pages "Pages" "WKWebView tabs · drive_page"
|
||||
row
|
||||
stream "EventStream · EventCache" "SSE + per-server disk cache"
|
||||
remote "Remote" "client WebSocket: shell · files · hands · signing"
|
||||
fwd "Forwards" "*.localhost previews"
|
||||
row
|
||||
net "API · TailnetProxy" "ByreAPI client over libtailscale SOCKS5"
|
||||
aside persist "Persistence · Updater" "SwiftData + CloudKit · Sparkle" green
|
||||
ui -> appstore
|
||||
ui -> pages
|
||||
stream -> appstore "events"
|
||||
appstore -> net "requests"
|
||||
stream -> net
|
||||
remote -> net
|
||||
fwd -> net
|
||||
pages ..> fwd
|
||||
|
||||
highlight "Event stream" store http tailnet stream appstore ui
|
||||
highlight "Agent turn" mgr vendor clis tools hands_srv repos
|
||||
highlight "Client Mac control" mgr clients http remote
|
||||
```
|
||||
Reference in New Issue
Block a user