sam/pi-dashboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add architecture diagrams (Mermaid + Archify map) for pi-dashboard

Browse Source 
- docs/pi-dashboard.mmd — Mermaid source of truth
- docs/diagrams/pi-dashboard.png|svg — rendered via mmdc (mermaid-cli 11.16.0)
- docs/archify/pi-dashboard.architecture.json — Archify JSON IR
- docs/pi-dashboard-map.html — interactive map (9/9 showcase checks)
- docs/README.md — embedded mermaid + artifact index + regenerate commands
- visual-check screenshots/evidence at 1440x900 + 2048x1320 (light/dark)

Generated by project-diagramming-mermaid + project-diagramming-archify skills.
This commit is contained in:
Sam Rolfe
2026-09-06 11:35:09 +10:00
parent 7aa09842d2
commit 3b3e63afb9
12 changed files with 14168 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/README.md Normal file
View File

@@ -0,0 +1,44 @@
# Pi Dashboard — Diagrams
Architecture artifacts for pi-dashboard, generated by the `project-diagramming-mermaid` + `project-diagramming-archify` skills (per-project `docs/` convention).
## Overview
- **Source of truth**: [`pi-dashboard.mmd`](./pi-dashboard.mmd)
- **Rendered** (via `mmdc`, mermaid-cli 11.16.0):
- [`diagrams/pi-dashboard.png`](./diagrams/pi-dashboard.png) (@2x, white bg)
- [`diagrams/pi-dashboard.svg`](./diagrams/pi-dashboard.svg) (vector)
- **Interactive map** (Archify, 9/9 showcase checks): [`pi-dashboard-map.html`](./pi-dashboard-map.html) — open in a browser for pan/zoom, search, theme toggle, route tracing
- **Archify spec** (JSON IR): [`archify/pi-dashboard.architecture.json`](./archify/pi-dashboard.architecture.json)
## Diagram (Mermaid)
Renders natively in Obsidian; shows as ASCII in pi via the `pi-mermaid` extension.
```mermaid
flowchart LR
EXT["dashboard.ts pi extension"] -->|"writes JSON"| SF[("state files ~/.pi/agent/dashboard")]
REM["remote machines .13 .51"] -->|"ssh cat *.json, 5s timeout + cooldown"| ST["state.go"]
SF -->|"readLocalStates"| ST
ST -->|"AgentState"| MAIN["main.go bubbletea TUI"]
CFG["pi-dashboard.yaml"] -->|"loadConfig"| MAIN
MAIN -->|"2s poll tick"| ST
MAIN -->|"table + detail"| UI["Table + Detail panes"]
UI -->|"Enter"| AT["tmux / zellij attach"]
UI -->|"d"| HK["hunk diff"]
UI -->|"Tab"| TX["tuxedo todo.txt"]
UI -->|"Del"| SF
```
## Regenerate
```bash
# update the source
vim pi-dashboard.mmd
# re-render images
mmdc -i pi-dashboard.mmd -o diagrams/pi-dashboard.png --scale 2 -b white
mmdc -i pi-dashboard.mmd -o diagrams/pi-dashboard.svg
# update the Archify map (JSON IR in archify/, then):
node ~/.agents/skills/archify/bin/archify.mjs validate architecture archify/pi-dashboard.architecture.json --quality showcase --json
node ~/.agents/skills/archify/bin/archify.mjs deliver architecture archify/pi-dashboard.architecture.json pi-dashboard-map.html --quality showcase --json
```

236
docs/archify/pi-dashboard.architecture.json Normal file
View File

@@ -0,0 +1,236 @@
{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "Pi Dashboard",
"quality_profile": "showcase"
},
"components": [
{
"id": "ext",
"type": "backend",
"label": "dashboard.ts",
"sublabel": "pi extension",
"pos": [
40,
140
]
},
{
"id": "sf",
"type": "database",
"label": "state files",
"sublabel": "~/.pi/agent/dashboard",
"pos": [
260,
140
]
},
{
"id": "st",
"type": "backend",
"label": "state.go",
"sublabel": "read + liveness",
"pos": [
480,
140
]
},
{
"id": "main",
"type": "backend",
"label": "main.go",
"sublabel": "bubbletea TUI",
"pos": [
700,
140
]
},
{
"id": "ui",
"type": "frontend",
"label": "Table + Detail",
"sublabel": "views",
"pos": [
920,
140
]
},
{
"id": "cfg",
"type": "backend",
"label": "pi-dashboard.yaml",
"sublabel": "config",
"pos": [
700,
40
]
},
{
"id": "rem",
"type": "external",
"label": "remotes .13 .51",
"sublabel": "ssh cat *.json",
"pos": [
40,
340
]
},
{
"id": "at",
"type": "external",
"label": "tmux / zellij",
"sublabel": "attach",
"pos": [
1180,
540
]
},
{
"id": "hk",
"type": "external",
"label": "hunk",
"sublabel": "diff review",
"pos": [
1180,
390
]
},
{
"id": "tx",
"type": "external",
"label": "tuxedo",
"sublabel": "todo.txt",
"pos": [
1180,
240
]
}
],
"boundaries": [
{
"kind": "region",
"label": "pi-dashboard (Go)",
"wraps": [
"st",
"main",
"ui",
"cfg"
]
},
{
"kind": "region",
"label": "data sources",
"wraps": [
"ext",
"sf",
"rem"
]
}
],
"connections": [
{
"id": "ext-to-sf",
"from": "ext",
"to": "sf",
"label": "writes JSON"
},
{
"id": "rem-to-st",
"from": "rem",
"to": "st",
"label": "ssh"
},
{
"id": "sf-to-st",
"from": "sf",
"to": "st",
"label": "readLocalStates"
},
{
"id": "st-to-main",
"from": "st",
"to": "main",
"label": "AgentState",
"labelAt": [
620,
215
]
},
{
"id": "cfg-to-main",
"from": "cfg",
"to": "main",
"label": "loadConfig",
"labelAt": [
760,
114
]
},
{
"id": "main-to-st",
"from": "main",
"to": "st",
"label": "2s poll tick",
"fromSide": "bottom",
"toSide": "bottom"
},
{
"id": "main-to-ui",
"from": "main",
"to": "ui",
"label": "model"
},
{
"id": "ui-to-at",
"from": "ui",
"to": "at",
"label": "Enter",
"labelAt": [
1060,
480
]
},
{
"id": "ui-to-hk",
"from": "ui",
"to": "hk",
"label": "d",
"labelAt": [
1060,
360
]
},
{
"id": "ui-to-tx",
"from": "ui",
"to": "tx",
"label": "Tab",
"labelAt": [
1060,
240
]
}
],
"cards": [
{
"dot": "cyan",
"title": "Source of truth",
"items": [
"dashboard.ts extension writes session JSON per machine",
"state.go: heartbeat/staleness (45s window, legacy 30m)",
"remote reads: ssh cat *.json, 5s hard timeout + cooldown"
]
},
{
"dot": "emerald",
"title": "UI actions",
"items": [
"Enter: tmux / zellij attach (local or ssh -t)",
"d: hunk diff in the agent's folder",
"Tab: tuxedo task board (<cwd>/todo.txt)",
"Del: remove closed/lost state file (local or ssh)"
]
}
]
}

BIN
docs/diagrams/pi-dashboard.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

1
docs/diagrams/pi-dashboard.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

13700
docs/pi-dashboard-map.html Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
docs/pi-dashboard-map.visual-check.1440x900.dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 95 KiB

BIN
docs/pi-dashboard-map.visual-check.1440x900.light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 97 KiB

BIN
docs/pi-dashboard-map.visual-check.2048x1320.dark.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 131 KiB

BIN
docs/pi-dashboard-map.visual-check.2048x1320.light.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 130 KiB

32
docs/pi-dashboard-map.visual-check.html Normal file
View File

@@ -0,0 +1,32 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Archify visual-check · pi-dashboard-map.html</title>
<style>
*{box-sizing:border-box}body{margin:0;padding:24px;background:#e9eef5;color:#172033;font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}header{max-width:1500px;margin:0 auto 18px}h1{margin:0 0 6px;font-size:20px}p{margin:0;color:#526176}.grid{max-width:1500px;margin:auto;display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:18px}figure{margin:0;padding:10px;background:white;border:1px solid #c9d4e3;border-radius:12px;box-shadow:0 10px 30px rgba(15,23,42,.08)}img{display:block;width:100%;height:auto;border:1px solid #e2e8f0}figcaption{padding:9px 4px 2px;color:#526176}@media(max-width:900px){.grid{grid-template-columns:1fr}}
</style>
</head>
<body>
<header><h1>Archify visual-check</h1><p>pi-dashboard-map.html · automated containment pass · visual review pending</p></header>
<main class="grid">
<figure>
<img src="pi-dashboard-map.visual-check.1440x900.light.png" alt="light 1440 by 900">
<figcaption><strong>LIGHT</strong> · 1440×900 · containment pass</figcaption>
</figure>
<figure>
<img src="pi-dashboard-map.visual-check.1440x900.dark.png" alt="dark 1440 by 900">
<figcaption><strong>DARK</strong> · 1440×900 · containment pass</figcaption>
</figure>
<figure>
<img src="pi-dashboard-map.visual-check.2048x1320.light.png" alt="light 2048 by 1320">
<figcaption><strong>LIGHT</strong> · 2048×1320 · containment pass</figcaption>
</figure>
<figure>
<img src="pi-dashboard-map.visual-check.2048x1320.dark.png" alt="dark 2048 by 1320">
<figcaption><strong>DARK</strong> · 2048×1320 · containment pass</figcaption>
</figure>
</main>
</body>
</html>

143
docs/pi-dashboard-map.visual-check.json Normal file
View File

@@ -0,0 +1,143 @@
{
"schemaVersion": 1,
"ok": true,
"command": "visual-check",
"status": "pass",
"visualReview": "pending",
"artifact": {
"path": "/home/sam/src/pi-dashboard/docs/pi-dashboard-map.html",
"sha256": "e36d87bd9e1567751a9d5837584aa7122a2a64c566263b8321fd69235d6977f2",
"bytes": 637800
},
"state": {
"detail": "read",
"motion": "still"
},
"chrome": {
"status": "available",
"executable": "/run/current-system/sw/bin/google-chrome"
},
"containment": {
"status": "pass",
"viewports": [
{
"width": 1440,
"height": 900,
"theme": "light",
"innerWidth": 1440,
"innerHeight": 900,
"scrollWidth": 1440,
"scrollHeight": 900,
"overflowX": false,
"overflowY": false,
"ok": true,
"resolvedTheme": "light"
},
{
"width": 1600,
"height": 1000,
"theme": "light",
"innerWidth": 1600,
"innerHeight": 1000,
"scrollWidth": 1600,
"scrollHeight": 1000,
"overflowX": false,
"overflowY": false,
"ok": true,
"resolvedTheme": "light"
},
{
"width": 1920,
"height": 1080,
"theme": "light",
"innerWidth": 1920,
"innerHeight": 1080,
"scrollWidth": 1920,
"scrollHeight": 1080,
"overflowX": false,
"overflowY": false,
"ok": true,
"resolvedTheme": "light"
},
{
"width": 2048,
"height": 1320,
"theme": "light",
"innerWidth": 2048,
"innerHeight": 1320,
"scrollWidth": 2048,
"scrollHeight": 1320,
"overflowX": false,
"overflowY": false,
"ok": true,
"resolvedTheme": "light"
}
]
},
"captures": {
"status": "pass",
"screenshots": [
{
"width": 1440,
"height": 900,
"theme": "light",
"innerWidth": 1440,
"innerHeight": 900,
"scrollWidth": 1440,
"scrollHeight": 900,
"overflowX": false,
"overflowY": false,
"ok": true,
"resolvedTheme": "light",
"file": "pi-dashboard-map.visual-check.1440x900.light.png"
},
{
"width": 1440,
"height": 900,
"theme": "dark",
"innerWidth": 1440,
"innerHeight": 900,
"scrollWidth": 1440,
"scrollHeight": 900,
"overflowX": false,
"overflowY": false,
"ok": true,
"resolvedTheme": "dark",
"file": "pi-dashboard-map.visual-check.1440x900.dark.png"
},
{
"width": 2048,
"height": 1320,
"theme": "light",
"innerWidth": 2048,
"innerHeight": 1320,
"scrollWidth": 2048,
"scrollHeight": 1320,
"overflowX": false,
"overflowY": false,
"ok": true,
"resolvedTheme": "light",
"file": "pi-dashboard-map.visual-check.2048x1320.light.png"
},
{
"width": 2048,
"height": 1320,
"theme": "dark",
"innerWidth": 2048,
"innerHeight": 1320,
"scrollWidth": 2048,
"scrollHeight": 1320,
"overflowX": false,
"overflowY": false,
"ok": true,
"resolvedTheme": "dark",
"file": "pi-dashboard-map.visual-check.2048x1320.dark.png"
}
],
"contactSheet": "pi-dashboard-map.visual-check.html"
},
"sidecars": {
"receipt": "pi-dashboard-map.visual-check.json",
"contactSheet": "pi-dashboard-map.visual-check.html"
}
}

12
docs/pi-dashboard.mmd Normal file
View File

@@ -0,0 +1,12 @@
flowchart LR
EXT[dashboard.ts pi extension] -->|writes JSON| SF[(state files<br/>~/.pi/agent/dashboard)]
REM[remote machines .13 .51] -->|ssh cat *.json<br/>5s timeout + cooldown| ST[state.go]
SF -->|readLocalStates| ST
ST -->|AgentState| MAIN[main.go bubbletea TUI]
CFG[pi-dashboard.yaml] -->|loadConfig| MAIN
MAIN -->|2s poll tick| ST
MAIN -->|table + detail| UI[Table + Detail panes]
UI -->|Enter| AT[tmux / zellij attach]
UI -->|d| HK[hunk diff]
UI -->|Tab| TX[tuxedo todo.txt]
UI -->|Del| SF