# harumiweb/xlflow architecture

> Architecture diagram of the GitHub repository harumiweb/xlflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harumiweb/xlflow
- Repository: https://github.com/harumiweb/xlflow

## Overview

xlflow is a CLI-first Excel VBA development harness: users move VBA and formula data between workbooks and source-controlled files, edit and validate that source, then test or run macros and inspect results. The CLI is the principal workflow entry point; a VS Code extension adds LSP and visual UserForm editing, while a Windows .NET bridge performs Excel automation. The README documents the capabilities and workflow; source-index references support selected internal links, but unsampled implementations and their detailed call paths are not inferred.

Main entry points: [`internal/cli/root.go`](https://github.com/harumiweb/xlflow/blob/main/internal/cli/root.go) (Command orchestration), [`bridge/dotnet/src/Xlflow.ExcelBridge/BridgeHost.cs`](https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/BridgeHost.cs) (Bridge host and protocol), [`editors/vscode/src/client.ts`](https://github.com/harumiweb/xlflow/blob/main/editors/vscode/src/client.ts) (VS Code extension), [`bridge/dotnet/src/Xlflow.ExcelBridge/Services/ExcelRunService.cs`](https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/Services/ExcelRunService.cs) (Macro execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli["xlflow CLI<br/>[main.go]"]
  node_commands["Command orchestration<br/>[root.go]"]
  node_results["Structured output<br/>[output.go]"]
end

subgraph group_source["VBA source and analysis"]
  node_sourcefiles["VBA source files"]
  node_sync["VBA import/export<br/>[filepull.go]"]
  node_format["VBA formatting<br/>[fmt.go]"]
  node_lint["VBA linting<br/>[linter.go]"]
  node_analysis["Semantic analysis<br/>[analyzer.go]"]
  node_forms["UserForm generation<br/>[compiler.go]"]
end

subgraph group_workbook["Workbook operations"]
  node_formulas["Formula snapshots<br/>[extract.go]"]
  node_diff["Workbook and source diff<br/>[diff.go]"]
  node_workbook[("Excel workbook")]
end

subgraph group_bridge["Excel automation"]
  node_tests["VBA testing"]
  node_execution["Macro execution<br/>[ExcelRunService.cs]"]
  node_bridgehost["Bridge host and protocol<br/>[BridgeHost.cs]"]
  node_bridgecontract["Bridge request and response<br/>[BridgeResponse.cs]"]
  node_session["Excel session management"]
  node_runtime["Macro worker<br/>[MacroRunWorker.cs]"]
end

subgraph group_editor["Editor integrations"]
  node_lsp["Language server<br/>[server.go]"]
  node_vscode["VS Code extension<br/>[client.ts]"]
  node_sidebar["Operations sidebar<br/>[sidebar.ts]"]
  node_formdesigner["UserForm designer<br/>[App.tsx]"]
  node_formprotocol["Designer protocol<br/>[protocol.ts]"]
end

node_developer(("Developer or agent"))

node_developer -->|"invokes commands"| node_cli
node_cli -->|"dispatches commands"| node_commands
node_commands -->|"runs pull or push"| node_sync
node_sync -->|"imports and exports"| node_workbook
node_sync -->|"reads and writes"| node_sourcefiles
node_developer -->|"edits source"| node_sourcefiles
node_commands -->|"runs formatting"| node_format
node_commands -->|"runs linting"| node_lint
node_commands -->|"runs tests"| node_tests
node_commands -->|"runs macros"| node_execution
node_commands -->|"pulls formulas"| node_formulas
node_commands -->|"compares workbooks"| node_diff
node_commands -->|"builds forms"| node_forms
node_commands -->|"formats output"| node_results
node_developer -->|"uses extension"| node_vscode
node_vscode -->|"starts language server"| node_lsp
node_vscode -->|"provides operations UI"| node_sidebar
node_vscode -.->|"opens form designer"| node_formdesigner
node_formdesigner -->|"uses protocol"| node_formprotocol
node_commands -->|"performs analysis"| node_analysis
node_commands -->|"provides LSP features"| node_lsp
node_commands -.->|"uses Excel bridge"| node_bridgehost
node_bridgehost -->|"exchanges messages"| node_bridgecontract
node_bridgehost -.->|"dispatches session work"| node_session
node_bridgehost -.->|"dispatches macro work"| node_execution
node_execution -->|"invokes worker"| node_runtime
node_tests -->|"tests macros in"| node_workbook
node_execution -->|"runs macros in"| node_workbook
node_formulas -->|"extracts formulas from"| node_workbook
node_diff -->|"compares workbook data"| node_workbook
node_lint -->|"uses semantic analysis"| node_analysis

click node_cli "https://github.com/harumiweb/xlflow/blob/main/cmd/xlflow/main.go"
click node_commands "https://github.com/harumiweb/xlflow/blob/main/internal/cli/root.go"
click node_sync "https://github.com/harumiweb/xlflow/blob/main/internal/filepull/filepull.go"
click node_format "https://github.com/harumiweb/xlflow/blob/main/internal/vbafmt/fmt.go"
click node_lint "https://github.com/harumiweb/xlflow/blob/main/internal/lint/linter.go"
click node_analysis "https://github.com/harumiweb/xlflow/blob/main/internal/analyze/analyzer.go"
click node_lsp "https://github.com/harumiweb/xlflow/blob/main/internal/lspserver/server.go"
click node_tests "https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/Services/ExcelTestService.cs"
click node_execution "https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/Services/ExcelRunService.cs"
click node_formulas "https://github.com/harumiweb/xlflow/blob/main/internal/formulas/extract.go"
click node_diff "https://github.com/harumiweb/xlflow/blob/main/internal/diff/diff.go"
click node_forms "https://github.com/harumiweb/xlflow/blob/main/internal/vba/userforms/compiler/compiler.go"
click node_bridgehost "https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/BridgeHost.cs"
click node_bridgecontract "https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/Contract/BridgeResponse.cs"
click node_session "https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/Services/ExcelSessionService.cs"
click node_runtime "https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/Workers/MacroRunWorker.cs"
click node_vscode "https://github.com/harumiweb/xlflow/blob/main/editors/vscode/src/client.ts"
click node_sidebar "https://github.com/harumiweb/xlflow/blob/main/editors/vscode/src/sidebar.ts"
click node_formdesigner "https://github.com/harumiweb/xlflow/blob/main/editors/vscode/webview/userFormDesigner/App.tsx"
click node_formprotocol "https://github.com/harumiweb/xlflow/blob/main/editors/vscode/src/userFormEditor/protocol.ts"
click node_results "https://github.com/harumiweb/xlflow/blob/main/internal/output/output.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_commands,node_results toneBlue
class node_sourcefiles,node_sync,node_format,node_lint,node_analysis,node_forms toneAmber
class node_formulas,node_diff,node_workbook toneMint
class node_tests,node_execution,node_bridgehost,node_bridgecontract,node_session,node_runtime toneRose
class node_lsp,node_vscode,node_sidebar,node_formdesigner,node_formprotocol,node_developer toneIndigo
```

## Components

### CLI workflow

- [xlflow CLI](https://github.com/harumiweb/xlflow/blob/main/cmd/xlflow/main.go): `cmd/xlflow/main.go`
- [Command orchestration](https://github.com/harumiweb/xlflow/blob/main/internal/cli/root.go): `internal/cli/root.go`
- [Structured output](https://github.com/harumiweb/xlflow/blob/main/internal/output/output.go): `internal/output/output.go`

### VBA source and analysis

- **VBA source files**
- [VBA import/export](https://github.com/harumiweb/xlflow/blob/main/internal/filepull/filepull.go): `internal/filepull/filepull.go`
- [VBA formatting](https://github.com/harumiweb/xlflow/blob/main/internal/vbafmt/fmt.go): `internal/vbafmt/fmt.go`
- [VBA linting](https://github.com/harumiweb/xlflow/blob/main/internal/lint/linter.go): `internal/lint/linter.go`
- [Semantic analysis](https://github.com/harumiweb/xlflow/blob/main/internal/analyze/analyzer.go): `internal/analyze/analyzer.go`
- [UserForm generation](https://github.com/harumiweb/xlflow/blob/main/internal/vba/userforms/compiler/compiler.go): `internal/vba/userforms/compiler/compiler.go`

### Workbook operations

- [Formula snapshots](https://github.com/harumiweb/xlflow/blob/main/internal/formulas/extract.go): `internal/formulas/extract.go`
- [Workbook and source diff](https://github.com/harumiweb/xlflow/blob/main/internal/diff/diff.go): `internal/diff/diff.go`
- **Excel workbook**

### Excel automation

- [VBA testing](https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/Services/ExcelTestService.cs): `bridge/dotnet/src/Xlflow.ExcelBridge/Services/ExcelTestService.cs`
- [Macro execution](https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/Services/ExcelRunService.cs): `bridge/dotnet/src/Xlflow.ExcelBridge/Services/ExcelRunService.cs`
- [Bridge host and protocol](https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/BridgeHost.cs): `bridge/dotnet/src/Xlflow.ExcelBridge/BridgeHost.cs`
- [Bridge request and response](https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/Contract/BridgeResponse.cs): `bridge/dotnet/src/Xlflow.ExcelBridge/Contract/BridgeResponse.cs`
- [Excel session management](https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/Services/ExcelSessionService.cs): `bridge/dotnet/src/Xlflow.ExcelBridge/Services/ExcelSessionService.cs`
- [Macro worker](https://github.com/harumiweb/xlflow/blob/main/bridge/dotnet/src/Xlflow.ExcelBridge/Workers/MacroRunWorker.cs): `bridge/dotnet/src/Xlflow.ExcelBridge/Workers/MacroRunWorker.cs`

### Editor integrations

- [Language server](https://github.com/harumiweb/xlflow/blob/main/internal/lspserver/server.go): `internal/lspserver/server.go`
- [VS Code extension](https://github.com/harumiweb/xlflow/blob/main/editors/vscode/src/client.ts): `editors/vscode/src/client.ts`
- [Operations sidebar](https://github.com/harumiweb/xlflow/blob/main/editors/vscode/src/sidebar.ts): `editors/vscode/src/sidebar.ts`
- [UserForm designer](https://github.com/harumiweb/xlflow/blob/main/editors/vscode/webview/userFormDesigner/App.tsx): `editors/vscode/webview/userFormDesigner/App.tsx`
- [Designer protocol](https://github.com/harumiweb/xlflow/blob/main/editors/vscode/src/userFormEditor/protocol.ts): `editors/vscode/src/userFormEditor/protocol.ts`

### Other components

- **Developer or agent**

## Connections

- Developer or agent → xlflow CLI: invokes commands (evidence: `README.md`)
- xlflow CLI → Command orchestration: dispatches commands (evidence: `cmd/xlflow/main.go`)
- Command orchestration → VBA import/export: runs pull or push (evidence: `internal/cli/root.go`)
- VBA import/export → Excel workbook: imports and exports (evidence: `README.md`)
- VBA import/export → VBA source files: reads and writes (evidence: `README.md`)
- Developer or agent → VBA source files: edits source (evidence: `README.md`)
- Command orchestration → VBA formatting: runs formatting (evidence: `README.md`)
- Command orchestration → VBA linting: runs linting (evidence: `README.md`)
- Command orchestration → VBA testing: runs tests (evidence: `README.md`)
- Command orchestration → Macro execution: runs macros (evidence: `README.md`)
- Command orchestration → Formula snapshots: pulls formulas (evidence: `README.md`)
- Command orchestration → Workbook and source diff: compares workbooks (evidence: `README.md`)
- Command orchestration → UserForm generation: builds forms (evidence: `README.md`)
- Command orchestration → Structured output: formats output (evidence: `internal/cli/root.go`)
- Developer or agent → VS Code extension: uses extension (evidence: `README.md`)
- VS Code extension → Language server: starts language server (evidence: `editors/vscode/src/client.ts`)
- VS Code extension → Operations sidebar: provides operations UI (evidence: `editors/vscode/src/client.ts`)
- VS Code extension → UserForm designer: opens form designer
- UserForm designer → Designer protocol: uses protocol (evidence: `editors/vscode/webview/userFormDesigner/App.tsx`)
- Command orchestration → Semantic analysis: performs analysis (evidence: `internal/cli/root.go`)
- Command orchestration → Language server: provides LSP features (evidence: `README.md`)
- Command orchestration → Bridge host and protocol: uses Excel bridge
- Bridge host and protocol → Bridge request and response: exchanges messages (evidence: `bridge/dotnet/src/Xlflow.ExcelBridge/BridgeHost.cs`)
- Bridge host and protocol → Excel session management: dispatches session work
- Bridge host and protocol → Macro execution: dispatches macro work
- Macro execution → Macro worker: invokes worker (evidence: `bridge/dotnet/src/Xlflow.ExcelBridge/Services/ExcelRunService.cs`)
- VBA testing → Excel workbook: tests macros in (evidence: `README.md`)
- Macro execution → Excel workbook: runs macros in (evidence: `README.md`)
- Formula snapshots → Excel workbook: extracts formulas from (evidence: `README.md`)
- Workbook and source diff → Excel workbook: compares workbook data (evidence: `README.md`)
- VBA linting → Semantic analysis: uses semantic analysis (evidence: `internal/lint/linter.go`)
