|
| 1 | +<!-- SPDX-License-Identifier: PMPL-1.0-or-later --> |
| 2 | +<!-- TOPOLOGY.md — Root-level architecture and module structure map --> |
| 3 | +<!-- Last updated: 2026-04-03 --> |
| 4 | + |
| 5 | +# PanLL — Topology |
| 6 | + |
| 7 | +## Overview |
| 8 | + |
| 9 | +PanLL (pronounced "parallel") is a panel-based development environment built on |
| 10 | +The Elm Architecture (TEA) in ReScript. It serves as a cognitive-relief layer |
| 11 | +(eNSAID) — a Human-Things Interface (HTI) that reduces friction, context-switching, |
| 12 | +and cognitive overhead during development work. |
| 13 | + |
| 14 | +The frontend is 686 ReScript source files organised into a strict TEA decomposition: |
| 15 | +Model, Msg, Update, View, Commands, and Subscriptions. The backend is a Gossamer |
| 16 | +shell (Zig + WebKitGTK) with 107 Rust modules handling IPC, filesystem, and |
| 17 | +external service integration. 108 panels are defined across 118 clade definitions. |
| 18 | + |
| 19 | +## Module Structure |
| 20 | + |
| 21 | +``` |
| 22 | +src/ |
| 23 | +├── App.res Entry point — mounts TEA application |
| 24 | +├── Model.res State composition root (includes domain modules) |
| 25 | +├── Msg.res TEA message variants (top-level sum type) |
| 26 | +├── Update.res State transition kernel |
| 27 | +├── View.res Main view renderer — dispatches to panel components |
| 28 | +├── Storage.res localStorage persistence layer |
| 29 | +├── SubscriptionsFixed.res Keyboard + polling subscriptions |
| 30 | +│ |
| 31 | +├── tea/ [18] Custom TEA runtime (permanent, zero npm deps) |
| 32 | +│ ├── Tea_App.res Application lifecycle (mount/update/render) |
| 33 | +│ ├── Tea_Html.res Element constructors (no JSX) |
| 34 | +│ ├── Tea_Render.res Virtual DOM diff/patch engine |
| 35 | +│ ├── Tea_Cmd.res Command (side-effect) abstraction |
| 36 | +│ ├── Tea_Sub.res Subscription management |
| 37 | +│ ├── Tea_Vdom.res VDOM node types, ARIA attributes |
| 38 | +│ ├── Tea_Debug.res Debug utilities |
| 39 | +│ ├── Tea_Json.res JSON encoding/decoding |
| 40 | +│ ├── Tea_Http.res HTTP request commands |
| 41 | +│ ├── Tea_Keyboard.res Keyboard event handling |
| 42 | +│ ├── Tea_Mouse.res Mouse event handling |
| 43 | +│ ├── Tea_Animationframe.res RequestAnimationFrame subscriptions |
| 44 | +│ └── ... (18 modules total) |
| 45 | +│ |
| 46 | +├── model/ [117] Domain model types (one or more per panel) |
| 47 | +│ ├── AccessibilityModel.res |
| 48 | +│ ├── AerieModel.res |
| 49 | +│ ├── AiModel.res |
| 50 | +│ ├── CloudGuardModel.res (CloudGuard panel state) |
| 51 | +│ └── ... |
| 52 | +│ |
| 53 | +├── msg/ [117] Message types per panel domain |
| 54 | +│ ├── A2mlMsg.res |
| 55 | +│ ├── AerieMsg.res |
| 56 | +│ ├── CloudGuardMsg.res |
| 57 | +│ └── ... |
| 58 | +│ |
| 59 | +├── update/ [74] Update functions (state transitions per domain) |
| 60 | +│ ├── UpdateAccessibility.res |
| 61 | +│ ├── UpdateAerie.res |
| 62 | +│ ├── UpdateBoj.res |
| 63 | +│ └── ... |
| 64 | +│ |
| 65 | +├── core/ [139] Engine logic — computation, validation, integration |
| 66 | +│ ├── A2mlEngine.res A2ML manifest parsing engine |
| 67 | +│ ├── AntiCrash.res Neural token circuit breaker |
| 68 | +│ ├── ConnectionManager.res Service connection lifecycle |
| 69 | +│ ├── Contractiles.res Contract enforcement |
| 70 | +│ ├── DebugLogger.res Structured logging |
| 71 | +│ ├── Decoders.res JSON decoders |
| 72 | +│ ├── DOMPurify.res DOM sanitisation |
| 73 | +│ ├── EventChain.res Event propagation engine |
| 74 | +│ ├── RuntimeBridge.res Gossamer IPC bridge |
| 75 | +│ ├── SmartRouter.res Panel routing logic |
| 76 | +│ ├── TilingEngine.res Panel layout management |
| 77 | +│ ├── TrustedTypes.res Trusted Types policy |
| 78 | +│ ├── UndoEngine.res Undo/redo state management |
| 79 | +│ ├── WindowBridge.res Window API bridge |
| 80 | +│ └── ... (139 modules total) |
| 81 | +│ |
| 82 | +├── components/ [123] Panel view components (Tea_Html renderers) |
| 83 | +│ ├── AccessibilityToolbar.res |
| 84 | +│ ├── Aerie.res |
| 85 | +│ ├── Boj.res |
| 86 | +│ ├── CloudGuard.res |
| 87 | +│ ├── CladeBrowser.res |
| 88 | +│ └── ... |
| 89 | +│ |
| 90 | +├── commands/ [69] Gossamer bridge command bindings (invoke wrappers) |
| 91 | +│ ├── A2mlCmd.res |
| 92 | +│ ├── AerieCmd.res |
| 93 | +│ └── ... |
| 94 | +│ |
| 95 | +├── modules/ [19] Module registry, clade loader, TypeLL service |
| 96 | +│ ├── PanelRegistry.res Panel registration and lookup |
| 97 | +│ ├── CladeLoader.res Clade definition loading |
| 98 | +│ ├── DatabaseModule.res VeriSimDB integration module |
| 99 | +│ ├── DatabaseRegistry.res Database connection registry |
| 100 | +│ ├── CloudGuardModule.res CloudGuard domain module |
| 101 | +│ ├── FarmModule.res Farm domain module |
| 102 | +│ └── ... |
| 103 | +│ |
| 104 | +├── subscriptions/ [2] TEA subscriptions |
| 105 | +│ ├── KeyboardFixed.res Keyboard shortcut handling |
| 106 | +│ └── GossamerEvents.res Gossamer backend event stream |
| 107 | +│ |
| 108 | +├── panels/ Panel-specific subdirectories |
| 109 | +│ └── system-update/ System update panel assets |
| 110 | +│ |
| 111 | +├── abi/ ABI definitions |
| 112 | +│ ├── cartridge-schema.json BoJ cartridge ABI schema |
| 113 | +│ └── README.md |
| 114 | +│ |
| 115 | +├── generated/ Auto-generated code |
| 116 | +│ └── CartridgeAbi.res Generated cartridge bindings |
| 117 | +│ |
| 118 | +└── styles/ |
| 119 | + └── input.css Tailwind CSS input |
| 120 | +``` |
| 121 | + |
| 122 | +### Backend (Gossamer — Rust) |
| 123 | + |
| 124 | +``` |
| 125 | +src-gossamer/ |
| 126 | +├── src/ [107] Rust backend modules |
| 127 | +│ ├── main.rs Gossamer application entry point |
| 128 | +│ ├── farm/ Repository inventory commands |
| 129 | +│ ├── boj/ BoJ cartridge routing (17 cartridges) |
| 130 | +│ ├── cloudguard/ Cloudflare API integration (14 commands) |
| 131 | +│ ├── overlay/ Aerie network commands (21 commands) |
| 132 | +│ ├── plaza/ License compliance commands |
| 133 | +│ ├── minter/ Panel codegen backend |
| 134 | +│ ├── coprocessor/ Coprocessor control plane |
| 135 | +│ ├── valence_shell/ Terminal session management (12 commands) |
| 136 | +│ ├── game_preview/ IDApTIK live preview (8 commands) |
| 137 | +│ ├── vm_inspector/ Reversible VM debugger (7 commands) |
| 138 | +│ ├── level_architect/ Level design backend (5 commands) |
| 139 | +│ ├── dlc_workshop/ DLC/puzzle pack tools (8 commands) |
| 140 | +│ ├── multiplayer_monitor/ Phoenix sync backend (6 commands) |
| 141 | +│ ├── network_topology/ Network graph backend (4 commands) |
| 142 | +│ ├── release_manager/ Release pipeline (5 commands) |
| 143 | +│ └── ... |
| 144 | +└── lib/ Shared Rust library code |
| 145 | +``` |
| 146 | + |
| 147 | +### Clade Definitions |
| 148 | + |
| 149 | +``` |
| 150 | +panel-clades/ |
| 151 | +└── clades/ [118] A2ML clade definitions |
| 152 | + ├── core-*.a2ml Core panel clades |
| 153 | + ├── overlay-*.a2ml Overlay panel clades |
| 154 | + ├── gamedev-*.a2ml Game development panel clades (28) |
| 155 | + └── meta-*.a2ml Cross-cutting service clades |
| 156 | +``` |
| 157 | + |
| 158 | +### Tests |
| 159 | + |
| 160 | +``` |
| 161 | +tests/ [137] Deno test files |
| 162 | +├── tea_*.test.ts TEA runtime tests |
| 163 | +├── engine_*.test.ts Engine unit tests (47 engines) |
| 164 | +├── e2e_*.test.ts End-to-end panel lifecycle tests (40) |
| 165 | +├── integration_*.test.ts Cross-panel integration tests |
| 166 | +└── bench_*.test.ts Performance benchmarks |
| 167 | +``` |
| 168 | + |
| 169 | +## Architectural Decisions |
| 170 | + |
| 171 | +### TEA Framework (permanent) |
| 172 | + |
| 173 | +PanLL uses a custom TEA (The Elm Architecture) runtime in `src/tea/` — 18 modules |
| 174 | +with zero npm dependencies. All UI follows the cycle: |
| 175 | + |
| 176 | +``` |
| 177 | +Model -> Msg -> Update -> View -> (Cmd | Sub) -> ... |
| 178 | +``` |
| 179 | + |
| 180 | +All state lives in `Model.model`. No global mutable state. No hooks, no Redux, |
| 181 | +no MVC. The custom runtime includes VDOM diffing (`Tea_Render`), ARIA support |
| 182 | +(`Tea_Vdom`), and animation frame subscriptions. |
| 183 | + |
| 184 | +### Gossamer Integration |
| 185 | + |
| 186 | +PanLL migrated from Tauri 2.0 to Gossamer (Zig + WebKitGTK). The Rust backend |
| 187 | +in `src-gossamer/` provides IPC commands invoked from ReScript via |
| 188 | +`src/core/RuntimeBridge.res`. The `GossamerEvents` subscription streams backend |
| 189 | +events to the TEA message loop. |
| 190 | + |
| 191 | +### VeriSimDB Backing |
| 192 | + |
| 193 | +Panel state, feedback history, and diagnostic data persist to VeriSimDB (port 8080) |
| 194 | +via the `DatabaseModule` and `DatabaseBridgeEngine`. Queries use VQL-UT through |
| 195 | +the BoJ database-mcp cartridge when `bojRouting` is enabled. |
| 196 | + |
| 197 | +### Panel Organisation |
| 198 | + |
| 199 | +108 panels are organised into categories: |
| 200 | + |
| 201 | +| Category | Count | Description | |
| 202 | +|----------|-------|-------------| |
| 203 | +| Core panels | 3 | Panel-L (Symbolic), Panel-N (Neural), Panel-W (World) — always visible | |
| 204 | +| General overlays | 14 | CloudGuard, VAB, Farm, Fleet, Hypatia, Reposystem, Aerie, Interfaces, Playgrounds, Plaza, Minter, Protocol-Squisher, My-Lang, BoJ | |
| 205 | +| IDApTIK panels | 11 | Valence Shell, Game Preview, VM Inspector, Network Topology, Level Architect, Coprocessors, Multiplayer Monitor, DLC Workshop, Editor Bridge, Build Dashboard, Release Manager | |
| 206 | +| Meta panels | 3 | Automation Router, Clade Browser, 7-Tentacles | |
| 207 | +| Game dev panels | 28 | Clade definitions only (A2ML); ReScript implementation pending | |
| 208 | +| Cross-cutting | 49 | TypeLL verification, A2ML/K9 integration, cognitive governance, provisioner | |
| 209 | + |
| 210 | +The three core panels form a permanent tiled layout. Overlay panels appear one |
| 211 | +at a time on top of them, activated via the panel switcher bar. |
| 212 | + |
| 213 | +### TypeLL Verification Kernel |
| 214 | + |
| 215 | +TypeLL provides cross-panel type intelligence. All 48 implemented panels are wired |
| 216 | +to the verification kernel via `TypeCheckResult` messages. The `panelTypeChecks` |
| 217 | +dictionary in the model tracks per-panel verification status. |
| 218 | + |
| 219 | +### Cognitive Governance |
| 220 | + |
| 221 | +Six always-present systems monitor operator state: |
| 222 | + |
| 223 | +- **Vexometer** — friction index monitoring |
| 224 | +- **Anti-Crash Gate** — neural token circuit breaker (all inference gated) |
| 225 | +- **Orbital Drift Aura** — ambient stability indicator |
| 226 | +- **Feedback-O-Tron** — BoJ-backed context persistence |
| 227 | +- **Information Humidity** — UI density adaptation (High/Medium/Low) |
| 228 | +- **Dark Start** — architecture manifold entry |
| 229 | + |
| 230 | +### Coprocessor Engine |
| 231 | + |
| 232 | +Three-phase coprocessor routing: local CPU (when load < 80%), remote neural, |
| 233 | +and BoJ fallback. The control plane (`src/core/CoprocessorsEngine.res`) manages |
| 234 | +dispatch; the Zig FFI data plane handles computation. |
| 235 | + |
| 236 | +## Build and Test |
| 237 | + |
| 238 | +```bash |
| 239 | +# Compile ReScript modules |
| 240 | +deno task res:build |
| 241 | + |
| 242 | +# Full production build (Gossamer + bundle + CSS) |
| 243 | +deno task build |
| 244 | + |
| 245 | +# Development server (Gossamer + bundle + static on :8000) |
| 246 | +deno task dev |
| 247 | + |
| 248 | +# Run all tests |
| 249 | +deno task test |
| 250 | + |
| 251 | +# Test with coverage |
| 252 | +deno task test:coverage |
| 253 | + |
| 254 | +# ReScript watch mode |
| 255 | +deno task res:watch |
| 256 | +``` |
| 257 | + |
| 258 | +## Integration Points |
| 259 | + |
| 260 | +| Service | Port | Protocol | Purpose | |
| 261 | +|---------|------|----------|---------| |
| 262 | +| Gossamer shell | — | IPC | Desktop webview host (Zig + WebKitGTK) | |
| 263 | +| ECHIDNA | 9000 | HTTP | Theorem prover dispatch | |
| 264 | +| VeriSimDB | 8080 | HTTP/VQL-UT | 8-modality versioned database | |
| 265 | +| BoJ-Server | 7700 | HTTP | Cartridge server (17 cartridges) and protocol gateway | |
| 266 | +| TypeLL | 7800 | HTTP | Cross-panel type verification kernel | |
| 267 | +| Hypatia | — | HTTP (Elixir) | Neurosymbolic CI/CD intelligence | |
| 268 | +| gitbot-fleet | — | HTTP (Axum) | Bot orchestration (rhodibot, echidnabot, etc.) | |
| 269 | +| Aerie | — | HTTP (V-lang) | Network analysis API | |
| 270 | +| NQC proxy | 4000 | HTTP | Code execution sandbox | |
| 271 | +| Groove | — | IPC/HTTP | Universal service discovery and capability negotiation | |
| 272 | + |
| 273 | +## File Counts (as of 2026-04-03) |
| 274 | + |
| 275 | +| Directory | .res files | .rs files | Description | |
| 276 | +|-----------|-----------|-----------|-------------| |
| 277 | +| `src/tea/` | 18 | — | Custom TEA runtime | |
| 278 | +| `src/model/` | 117 | — | Domain model types | |
| 279 | +| `src/msg/` | 117 | — | Message types | |
| 280 | +| `src/update/` | 74 | — | Update functions | |
| 281 | +| `src/core/` | 139 | — | Engine logic | |
| 282 | +| `src/components/` | 123 | — | View components | |
| 283 | +| `src/commands/` | 69 | — | Gossamer IPC commands | |
| 284 | +| `src/modules/` | 19 | — | Registries and services | |
| 285 | +| `src/subscriptions/` | 2 | — | TEA subscriptions | |
| 286 | +| `src/*.res` | 7 | — | Top-level TEA wiring | |
| 287 | +| `src-gossamer/` | — | 107 | Rust backend | |
| 288 | +| **Total source** | **685** | **107** | **792 files** | |
| 289 | +| `tests/` | — | — | 137 test files | |
| 290 | +| `panel-clades/clades/` | — | — | 118 A2ML clade definitions | |
| 291 | + |
| 292 | +## See Also |
| 293 | + |
| 294 | +- `docs/architecture/TOPOLOGY.md` — detailed completion dashboard and cross-panel communication map |
| 295 | +- `docs/architecture/PANEL-INVENTORY.md` — full catalog of all 108 panels |
| 296 | +- `docs/architecture/ARCHITECTURE.md` — architectural narrative |
| 297 | +- `docs/decisions/DESIGN-DECISIONS.md` — ADR log |
| 298 | +- `docs/ENSAID.adoc` — eNSAID philosophy and design rationale |
0 commit comments