​

System Components

​

Excel VSTO Add-in

• Task Pane Hosting – TaskPaneManager and WebView2TaskPaneHost load the compiled React app and bridge messages using chrome.webview.postMessage.
• Excel API Layer – ExcelApiService exposes /api/actions/execute which fans out to handlers such as HandleWriteValues, HandleReadFormat, HandleCreateChart, and VBA operations. It uses ExcelSelection to gather workbook metadata and supports staging/undo via the FormatManager.
• Port & Backend Discovery – ExcelApiConfigService and BackendConfigService keep track of which localhost ports the API and Deno services are using by reading and writing files like excel-api-port-*.txt and deno-websocket-port-*.txt.
• Telemetry Clients – The add-in integrates with NLog for local diagnostics and PostHogService for behaviour analytics tied to the user email.

​

Deno Orchestrator

• Router & WebSocket Manager – Router upgrades connections, routes events (stream:start, tool:permission:response, etc.), and stores sockets per workbook via WebSocketManager.
• Tool Execution – src/tools defines concrete tool classes (WriteValuesTool, AddSheetsTool, VBAUpdateTool, …). Execution flows through toolExecutionFlow, which calls Excel, captures revert data, and updates conversation history.
• State Management – stateManager maintains per-workbook conversation history, tool changes, request metadata, and abort controllers. It also records attachments and ensures pending tools are tracked.
• LLM Client – llm-client/anthropic.ts builds parameter sets for Claude Sonnet 4.5, handles token counting, and performs summarisation during compacting.
• Observability – tracing.ts wraps Langfuse, logging each prompt, tool call, auto-approval, rejection, or cancellation as structured traces and spans.

​

Task Pane UI

• Authentication Context – AuthContext wraps Supabase’s PKCE flow, persists sessions, and exposes the current user to the rest of the app.
• Chat Surface – The main chat component streams Claude deltas, renders Markdown, and displays structured tool cards with actions for approve/reject/view/revert.
• Tool Permissions – webSocketChatService auto-approves whitelisted tools, batches approvals into tool:permission:response, and surfaces errors with actionable messages.
• Attachments & Metadata – The UI collects workbook metadata via webViewBridge, uploads file attachments (PDFs, PNGs, JPEGs) as base64 payloads, and exposes toggles for auto-approve.
• Analytics – posthog.ts initialises the PostHog client with the same API key used by the VSTO layer so front-end events align with backend traces.

​

Shared Contracts

• Types – deno-server/src/types/index.ts defines shared TypeScript interfaces for tool requests, WebSocket messages, and Excel API payloads.
• Port Files – %LOCALAPPDATA%\X21 holds deno-server-port-*.txt, deno-websocket-port-*.txt, and excel-api-port-*.txt so each component can discover the others even after a restart.
• Versioning – Publish.ps1 increments the ClickOnce manifest version and renames setup.exe to include x21-setup-v<version>.exe, ensuring clear audit trails.