Skip to main content

​
Architecture Overview

X21 is composed of three tightly-coupled runtimes that share state over localhost:
  1. Excel VSTO Add-in (X21\vsto-addin) – A .NET Framework 4.8 project that embeds the WebView2-based task pane, exposes an HTTP API for Excel operations, and brokers logging/telemetry.
  2. Deno Orchestrator (X21\deno-server) – A TypeScript service that manages conversations with Claude, executes Excel tools, and coordinates approvals via WebSockets.
  3. Task Pane UI (X21\web-ui) – A React + Vite application rendered inside WebView2. It handles authentication, chat streaming, tool review, and attachments.
These components collaborate to convert natural language prompts into deterministic Excel actions while giving users full control over what executes inside the workbook.

​
Request Lifecycle

  1. Prompt Submission – The task pane collects the user prompt, selected tools, and optional attachments. It resolves the active workbook name by asking the VSTO bridge through webViewBridge.getWorkbookName.
  2. WebSocket Dispatch – The UI sends a stream:start payload to the Deno server. The Router class registers the workbook socket, persists the conversation in stateManager, and begins tracing in Langfuse.
  3. Claude Streaming – streamClaudeResponseAndHandleToolUsage streams Claude Sonnet 4.5 deltas back to the UI (stream:delta). When the LLM proposes a tool call, the backend captures the request and emits tool:permission.
  4. Tool Approval – Users review each tool. Approvals trigger toolExecutionFlow, which calls the Excel HTTP API (/api/actions/execute) with the serialized request. Results are cached alongside revert instructions.
  5. Change Application – After the Excel service responds, the backend updates the conversation with tool_result blocks, logs the span in Langfuse, and continues the LLM stream. Applied changes can be reverted or replayed with tool:revert / tool:apply.
  6. Completion & Scoring – When Claude finishes, stream:end is broadcast. Users can rate the interaction; the backend forwards scores and feedback to Langfuse and records analytics in PostHog.

​
Data Boundaries

  • On-device by default – All communication occurs over http://localhost and ws://localhost. No workbook data leaves the machine unless attachments are uploaded or remote telemetry is enabled.
  • Port discovery – Both the Deno server and Excel API scan for available ports and write them to %LOCALAPPDATA%\X21 so other components can discover them.
  • State isolation – The stateManager keeps independent conversation history per workbook name, ensuring multiple Excel windows do not interfere with each other.

​
Reliability Features

  • Abort Controllers – Every request spawns an AbortController, allowing the UI to cancel in-flight Claude generations or tool pipelines.
  • Token Compacting – When conversation history approaches the model limit, compacting.ts summarizes previous turns to keep prompts within the configured tokenLimit.
  • Structured Error Handling – Exceptions during tool execution raise ToolExecutionError, which is surfaced to the UI (tool:error) and logged with full context.
  • Daily Log Rotation – The Deno logger writes to %LOCALAPPDATA%\X21\X21-deno\Logs, rotating logs per day while keeping a current file.
For a breakdown of each subsystem, continue to the Components and Technology Stack pages.