Tools Software WebUI — tool-system docs, diagrams, Archify map

docs/system.architecture.json

@@ -0,0 +1,193 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Tools Software WebUI",
+    "quality_profile": "showcase",
+    "viewBox": [1120, 620]
+  },
+  "components": [
+    {
+      "id": "agents",
+      "type": "backend",
+      "label": "pi agents",
+      "sublabel": "per machine (.27/.13/.51)",
+      "pos": [120, 160]
+    },
+    {
+      "id": "ext",
+      "type": "backend",
+      "label": "dashboard.ts",
+      "sublabel": "extension",
+      "pos": [330, 160]
+    },
+    {
+      "id": "smc",
+      "type": "database",
+      "label": "state JSON",
+      "sublabel": "~/.pi/agent/dashboard",
+      "pos": [520, 160]
+    },
+    {
+      "id": "tui",
+      "type": "frontend",
+      "label": "pi-dashboard",
+      "sublabel": "Go TUI",
+      "pos": [710, 100]
+    },
+    {
+      "id": "portal",
+      "type": "frontend",
+      "label": "console portal",
+      "sublabel": "Python :8500",
+      "pos": [710, 260]
+    },
+    {
+      "id": "omni",
+      "type": "backend",
+      "label": "OmniRoute",
+      "sublabel": "LLM :20129",
+      "pos": [330, 370]
+    },
+    {
+      "id": "n8n",
+      "type": "backend",
+      "label": "n8n",
+      "sublabel": ":5678",
+      "pos": [140, 470]
+    },
+    {
+      "id": "prefect",
+      "type": "backend",
+      "label": "Prefect 3",
+      "sublabel": ":4200",
+      "pos": [350, 470]
+    },
+    {
+      "id": "headroom",
+      "type": "backend",
+      "label": "headroom",
+      "sublabel": "compress :8787",
+      "pos": [140, 370]
+    },
+    {
+      "id": "caddy",
+      "type": "external",
+      "label": "Caddy",
+      "sublabel": "reverse proxy .35",
+      "pos": [920, 300]
+    },
+    {
+      "id": "gitea",
+      "type": "external",
+      "label": "Gitea",
+      "sublabel": ":3001/:2222",
+      "pos": [920, 120]
+    },
+    {
+      "id": "phone",
+      "type": "external",
+      "label": "Mobile",
+      "sublabel": "Termux / KDE Connect",
+      "pos": [920, 480]
+    }
+  ],
+  "boundaries": [
+    {
+      "kind": "region",
+      "label": "console & telemetry",
+      "wraps": ["ext", "smc", "tui", "portal"]
+    },
+    {
+      "kind": "region",
+      "label": "web-facing host (.13)",
+      "wraps": ["omni", "n8n", "prefect", "headroom"]
+    },
+    {
+      "kind": "region",
+      "label": "home lab (.35)",
+      "wraps": ["caddy", "gitea"]
+    }
+  ],
+  "connections": [
+    {
+      "id": "agents-to-ext",
+      "from": "agents",
+      "to": "ext",
+      "label": "runs every session",
+      "labelAt": [285, 150]
+    },
+    {
+      "id": "ext-to-smc",
+      "from": "ext",
+      "to": "smc",
+      "label": "writes JSON"
+    },
+    {
+      "id": "smc-to-tui",
+      "from": "smc",
+      "to": "tui",
+      "label": "ssh pull / read",
+      "labelAt": [665, 90]
+    },
+    {
+      "id": "smc-to-portal",
+      "from": "smc",
+      "to": "portal",
+      "label": "collected on .13",
+      "fromSide": "bottom",
+      "toSide": "top"
+    },
+    {
+      "id": "agents-to-omni",
+      "from": "agents",
+      "to": "omni",
+      "label": "LLM (omni provider)",
+      "fromSide": "bottom",
+      "toSide": "top"
+    },
+    {
+      "id": "omni-to-caddy",
+      "from": "omni",
+      "to": "caddy",
+      "label": "combo routing"
+    },
+    {
+      "id": "caddy-to-gitea",
+      "from": "caddy",
+      "to": "gitea",
+      "label": "gitea.lab"
+    }
+  ],
+  "cards": [
+    {
+      "dot": "cyan",
+      "title": "Core loop",
+      "items": [
+        "Every pi session runs dashboard.ts → heartbeat JSON per machine",
+        "Collected on .13; rendered by Go TUI and Python portal",
+        "LLM traffic proxied through OmniRoute with priority fallback combos",
+        "Headroom compresses heavy contexts; NTFY alerts mobile on completion",
+        "n8n webhooks / Prefect pipelines can trigger around the agents"
+      ]
+    },
+    {
+      "dot": "emerald",
+      "title": "Access routes",
+      "items": [
+        "Console: pi-dashboard TUI on .27/.13 · portal Admin via console.lab",
+        "n8n :5678 · Prefect :4200 · Open WebUI :3000 on .13",
+        "Phone: Tailscale + Termux SSH + KDE Connect + NTFY"
+      ]
+    },
+    {
+      "dot": "amber",
+      "title": "Decisions",
+      "items": [
+        "Windmill not needed — n8n (canvas) + Prefect (pipelines) cover it",
+        "Paseo / Pi Web UI deferred to roadmap — current console suffices",
+        "Gitea Actions recommended: auto-sync ~/.agents clones on push"
+      ]
+    }
+  ]
+}