⚙️ OMP Mesh Architecture

To support this massive feature set without blocking the Node.js event loop or compromising security, the overpowered OMP-first Web UI utilizes a Split-Process, Multi-Node Mesh Architecture.

1. System Architecture Layers

Layer 1: High-Performance Native Core (The Engine)

• Tech: Rust N-API (@oh-my-pi/pi-natives), Bun monorepo runtime, ast-grep-core.
• Role: Handles all blocking, heavy-compute tasks off the main thread via the libuv thread pool. Executes embedded bash (brush-shell), parses ASTs, tokenizes strings (tiktoken-rs), and resolves virtual URIs.

Layer 2: Headless Session Daemon & FSM Enforcer (The Brain)

• Tech: Python/Node.js dual-layer, SQLite (pi-mnemopi), Model Context Protocol (MCP).
• Role: Operates independently of the UI. Survives browser disconnects. Enforces the Deterministic FSM, isolates Git worktrees/APFS clones for subagents, handles OTel tracing telemetry, and manages Hindsight memory.

Layer 3: WebSocket/HTTP Bridge Server (The Gateway)

• Tech: Fastify, Server-Sent Events (SSE), WebSockets.
• Role: Embedded natively within the Pi process (or run detached via jiti). Proxies RPC/ACP protocols to the client. Broadcasts real-time events (compaction, tool executions, token counts, streaming text).

Layer 4: Client-Side Application (The Interface)

• Tech: React, Vite, Tailwind CSS, shadcn/ui, Streamdown (Markdown/Math/Mermaid), xterm.js.
• Role: Renders the UI natively in the browser or as a PWA/Electron desktop app. Relies on the PromptBus system to render interactive dialogs.

2. UI Layout Blueprint

The interface is structured for progressive disclosure, ensuring the vast toolset does not overwhelm the developer.

A. Global Command Palette (Cmd/Ctrl + K)

• Function: The central nervous system of the UI.
• Capabilities: Model switching, session navigation, settings toggles, skill/tool discovery, and executing slash commands (e.g., /compact, /review, /packages).

B. Left Sidebar: Federation & Session Hierarchy

• Machine/Mesh View: Toggle between Localhost, Remote Servers, and federated proxy machines.
• Session Tree: Grouped by Project → Workspace → Session. Includes visual indicators for active Subagents running underneath parent sessions.
• Package Manager: A dedicated tab for the pi-packages GUI to manage installed extensions.

C. Main Stage: The Multi-Tab Workbench

• Chat Stream: Utilizes Streamdown for live markdown, math, and Mermaid rendering.
  • Inline Tool Cards: Expandable/collapsible cards showing exact tool arguments, hash-anchored diff previews (red/green lines), and reasoning blocks.
  • Dimmed Queues: Visualizes upcoming, queued prompts at the bottom of the feed during active generation.
• Interactive Composer: Includes drag-and-drop zones for image attachments, a pulsing mic indicator for Web Speech API transcription, and an intelligent context visualizer (token percentage bar).
• File Previewer & Terminal: A split pane allowing users to preview files in real-time or drop into an integrated xterm.js terminal to run out-of-band human approvals.

D. Right Sidebar: Context & Kanban

• Workspace Telemetry: Live counters for token usage, elapsed time, cost, and active model.
• Kanban Board: Visualizes AI spec generation (Plan → Execute → Review → Done) and task dependency progression.
• Files Touched Manifest: Badges showing (R)ead, (W)rite, (E)dit, (M)odified, and (D)eleted states for the current session boundary.

E. Overlays & External Dashboards

• PromptBus Modals: Intercepts Pi requests for human confirmation (e.g., force-installing a package, approving a complex AST rewrite) and displays them as rich React modals.
• Observability Dashboard: A pop-out window streaming SSE traces, displaying waterfall bottleneck charts of LLM vs. Tool execution times.

3. Security & Networking Model

• Localhost Trust: Operates unguarded on 127.0.0.1.
• Remote Access: Handled via HTTP Basic Auth, PIN-authenticated LAN gates, or OAuth-guarded zrok tunnels.
• Data Redaction: The pi-otel layer performs recursive process-level data redaction to strip secrets before tracing payloads hit the local SQLite or Aspire dashboards.