diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..ceb7fbf --- /dev/null +++ b/docs/README.md @@ -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 +``` \ No newline at end of file diff --git a/docs/archify/pi-dashboard.architecture.json b/docs/archify/pi-dashboard.architecture.json new file mode 100644 index 0000000..cc2c899 --- /dev/null +++ b/docs/archify/pi-dashboard.architecture.json @@ -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 (/todo.txt)", + "Del: remove closed/lost state file (local or ssh)" + ] + } + ] +} \ No newline at end of file diff --git a/docs/diagrams/pi-dashboard.png b/docs/diagrams/pi-dashboard.png new file mode 100644 index 0000000..db14cac Binary files /dev/null and b/docs/diagrams/pi-dashboard.png differ diff --git a/docs/diagrams/pi-dashboard.svg b/docs/diagrams/pi-dashboard.svg new file mode 100644 index 0000000..1fff3d8 --- /dev/null +++ b/docs/diagrams/pi-dashboard.svg @@ -0,0 +1 @@ +

writes JSON

ssh cat *.json
5s timeout + cooldown

readLocalStates

AgentState

loadConfig

2s poll tick

table + detail

Enter

d

Tab

Del

dashboard.ts pi extension

state files
~/.pi/agent/dashboard

remote machines .13 .51

state.go

main.go bubbletea TUI

pi-dashboard.yaml

Table + Detail panes

tmux / zellij attach

hunk diff

tuxedo todo.txt

\ No newline at end of file diff --git a/docs/pi-dashboard-map.html b/docs/pi-dashboard-map.html new file mode 100644 index 0000000..ba2ac37 --- /dev/null +++ b/docs/pi-dashboard-map.html @@ -0,0 +1,13700 @@ + + + + + + + Pi Dashboard Diagram + + + + + + + + + + + +
+ +
+
+
+

Pi Dashboard

+
+
+ + + + + + +
+ + Pi Dashboard + A architecture diagram generated by Archify. + + + + + + + + + + + + + + + + + + + + + + + + + pi-dashboard (Go) + + + data sources + + + + + + + + + + + + + + + + dashboard.ts · pi extension · data sources + + + + dashboard.ts + pi extension + + + + state files · ~/.pi/agent/dashboard · data sources + + + + state files + ~/.pi/agent/dashboard + + + + state.go · read + liveness · pi-dashboard (Go) + + + + state.go + read + liveness + + + + main.go · bubbletea TUI · pi-dashboard (Go) + + + + main.go + bubbletea TUI + + + + Table + Detail · views · pi-dashboard (Go) + + + + Table + Detail + views + + + + pi-dashboard.yaml · config · pi-dashboard (Go) + + + + pi-dashboard.yaml + config + + + + remotes .13 .51 · ssh cat *.json · data sources + + + + remotes .13 .51 + ssh cat *.json + + + + tmux / zellij · attach · Architecture component + + + + tmux / zellij + attach + + + + hunk · diff review · Architecture component + + + + hunk + diff review + + + + tuxedo · todo.txt · Architecture component + + + + tuxedo + todo.txt + + + + + + writes JSON + + + + ssh + + + + readLocalStates + + + + AgentState + + + + loadConfig + + + + 2s poll tick + + + + model + + + + Enter + + + + d + + + + Tab + + + + + Legend + + + Frontend + + + + Backend + + + + Database + + + + External + + + +

+ + + + + + + + +
+ + +
+
+
+
+

Source of truth

+
+
    +
  • • 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
  • +
+
+ +
+
+
+

UI actions

+
+
    +
  • • 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)
  • +
+
+
+ +
+ + + + diff --git a/docs/pi-dashboard-map.visual-check.1440x900.dark.png b/docs/pi-dashboard-map.visual-check.1440x900.dark.png new file mode 100644 index 0000000..cb64948 Binary files /dev/null and b/docs/pi-dashboard-map.visual-check.1440x900.dark.png differ diff --git a/docs/pi-dashboard-map.visual-check.1440x900.light.png b/docs/pi-dashboard-map.visual-check.1440x900.light.png new file mode 100644 index 0000000..0cf95f9 Binary files /dev/null and b/docs/pi-dashboard-map.visual-check.1440x900.light.png differ diff --git a/docs/pi-dashboard-map.visual-check.2048x1320.dark.png b/docs/pi-dashboard-map.visual-check.2048x1320.dark.png new file mode 100644 index 0000000..cd608b8 Binary files /dev/null and b/docs/pi-dashboard-map.visual-check.2048x1320.dark.png differ diff --git a/docs/pi-dashboard-map.visual-check.2048x1320.light.png b/docs/pi-dashboard-map.visual-check.2048x1320.light.png new file mode 100644 index 0000000..0b9695a Binary files /dev/null and b/docs/pi-dashboard-map.visual-check.2048x1320.light.png differ diff --git a/docs/pi-dashboard-map.visual-check.html b/docs/pi-dashboard-map.visual-check.html new file mode 100644 index 0000000..4b561c4 --- /dev/null +++ b/docs/pi-dashboard-map.visual-check.html @@ -0,0 +1,32 @@ + + + + + +Archify visual-check · pi-dashboard-map.html + + + +

Archify visual-check

pi-dashboard-map.html · automated containment pass · visual review pending

+
+
+ light 1440 by 900 +
LIGHT · 1440×900 · containment pass
+
+
+ dark 1440 by 900 +
DARK · 1440×900 · containment pass
+
+
+ light 2048 by 1320 +
LIGHT · 2048×1320 · containment pass
+
+
+ dark 2048 by 1320 +
DARK · 2048×1320 · containment pass
+
+
+ + diff --git a/docs/pi-dashboard-map.visual-check.json b/docs/pi-dashboard-map.visual-check.json new file mode 100644 index 0000000..e7c39c5 --- /dev/null +++ b/docs/pi-dashboard-map.visual-check.json @@ -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" + } +} diff --git a/docs/pi-dashboard.mmd b/docs/pi-dashboard.mmd new file mode 100644 index 0000000..a41e074 --- /dev/null +++ b/docs/pi-dashboard.mmd @@ -0,0 +1,12 @@ +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