# xrayxl/xrayxl-addin architecture

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

- Interactive diagram: https://gitdiagram.com/xrayxl/xrayxl-addin
- Repository: https://github.com/xrayxl/xrayxl-addin

## Overview

XRayXL is an in-process Excel add-in that records XLL and VBA execution to a shared trace file. The user arms tracing, runs calculations or macros, then inspects the resulting trace; the ribbon and Excel commands provide controls, while diagnostics and event capture complement the main trace. The graph reflects documented tracer behavior and relationships visible in excerpts or the source index; several implementation details and UI paths are unsampled, so uncertain connections are omitted.

Main entry points: [`src/app/session.cpp`](https://github.com/xrayxl/xrayxl-addin/blob/main/src/app/session.cpp) (Session lifecycle), [`src/emit/csv.cpp`](https://github.com/xrayxl/xrayxl-addin/blob/main/src/emit/csv.cpp) (Trace writer), [`src/xll/xllarm.cpp`](https://github.com/xrayxl/xrayxl-addin/blob/main/src/xll/xllarm.cpp) (Arm XLL hooks), [`src/vba/vbapatch.cpp`](https://github.com/xrayxl/xrayxl-addin/blob/main/src/vba/vbapatch.cpp) (VBA interpreter hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Session Control"]
  node_session["Session lifecycle<br/>[session.cpp]"]
  node_commands["Excel commands<br/>[commands.cpp]"]
  node_events["Excel events<br/>[appevents.cpp]"]
end

subgraph group_xll["XLL Tracing"]
  node_xllarm["Arm XLL hooks<br/>[xllarm.cpp]"]
  node_xllregistry["Registration lookup<br/>[xllregistry.cpp]"]
  node_xllwatch["Late registrations"]
  node_xllhook["XLL detours<br/>[xllhook.cpp]"]
  node_xlltrace["XLL recorder<br/>[xlltrace.cpp]"]
end

subgraph group_vba["VBA Tracing"]
  node_vbapatch["VBA interpreter hooks<br/>[vbapatch.cpp]"]
  node_vbapcode["Opcode analysis<br/>[vbapcode.cpp]"]
  node_vbatrace["VBA recorder<br/>[vbatrace.cpp]"]
  node_identity["Procedure identity<br/>[vbaidentity.cpp]"]
end

subgraph group_output["Trace Output"]
  node_csv["Trace writer<br/>[csv.cpp]"]
  node_ring["Buffered drain<br/>[ring.cpp]"]
  node_tracefile["CSV or JSONL trace"]
end

subgraph group_support["User Support"]
  node_ribbon["Ribbon controls<br/>[ribbon.cpp]"]
  node_diagnostics["Crash diagnostics<br/>[crashlog.cpp]"]
end

node_user(("Excel user"))
node_excel(("Excel process"))

node_user -->|"controls"| node_ribbon
node_ribbon -->|"arms or disarms"| node_session
node_excel -.->|"invokes"| node_commands
node_commands -.->|"controls session"| node_session
node_session -->|"arms XLL"| node_xllarm
node_session -->|"arms VBA"| node_vbapatch
node_session -->|"starts event capture"| node_events
node_xllarm -->|"resolves exports"| node_xllregistry
node_xllarm -->|"installs watcher"| node_xllwatch
node_xllarm -->|"installs detours"| node_xllhook
node_xllhook -->|"records calls"| node_xlltrace
node_vbapatch -->|"analyzes opcodes"| node_vbapcode
node_vbapatch -->|"resolves procedures"| node_identity
node_vbapatch -->|"hooks interpreter"| node_vbatrace
node_vbatrace -->|"uses identity"| node_identity
node_xlltrace -.->|"writes rows"| node_csv
node_vbatrace -->|"writes rows"| node_csv
node_events -->|"writes event rows"| node_csv
node_session -->|"opens and closes"| node_csv
node_csv -->|"buffers and drains"| node_ring
node_csv -->|"writes trace"| node_tracefile
node_excel -.->|"reports faults"| node_diagnostics

click node_session "https://github.com/xrayxl/xrayxl-addin/blob/main/src/app/session.cpp"
click node_commands "https://github.com/xrayxl/xrayxl-addin/blob/main/src/app/commands.cpp"
click node_events "https://github.com/xrayxl/xrayxl-addin/blob/main/src/app/appevents.cpp"
click node_ribbon "https://github.com/xrayxl/xrayxl-addin/blob/main/src/ui/ribbon.cpp"
click node_xllarm "https://github.com/xrayxl/xrayxl-addin/blob/main/src/xll/xllarm.cpp"
click node_xllregistry "https://github.com/xrayxl/xrayxl-addin/blob/main/src/xll/xllregistry.cpp"
click node_xllwatch "https://github.com/xrayxl/xrayxl-addin/blob/main/src/xll/xllregister_watch.cpp"
click node_xllhook "https://github.com/xrayxl/xrayxl-addin/blob/main/src/xll/xllhook.cpp"
click node_xlltrace "https://github.com/xrayxl/xrayxl-addin/blob/main/src/xll/xlltrace.cpp"
click node_vbapatch "https://github.com/xrayxl/xrayxl-addin/blob/main/src/vba/vbapatch.cpp"
click node_vbapcode "https://github.com/xrayxl/xrayxl-addin/blob/main/src/vba/vbapcode.cpp"
click node_vbatrace "https://github.com/xrayxl/xrayxl-addin/blob/main/src/vba/vbatrace.cpp"
click node_identity "https://github.com/xrayxl/xrayxl-addin/blob/main/src/vba/vbaidentity.cpp"
click node_csv "https://github.com/xrayxl/xrayxl-addin/blob/main/src/emit/csv.cpp"
click node_ring "https://github.com/xrayxl/xrayxl-addin/blob/main/src/emit/ring.cpp"
click node_diagnostics "https://github.com/xrayxl/xrayxl-addin/blob/main/src/core/crashlog.cpp"

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_session,node_commands,node_events,node_user toneBlue
class node_xllarm,node_xllregistry,node_xllwatch,node_xllhook,node_xlltrace toneAmber
class node_vbapatch,node_vbapcode,node_vbatrace,node_identity toneMint
class node_csv,node_ring,node_tracefile toneRose
class node_ribbon,node_diagnostics,node_excel toneIndigo
```

## Components

### Session Control

- [Session lifecycle](https://github.com/xrayxl/xrayxl-addin/blob/main/src/app/session.cpp): `src/app/session.cpp`
- [Excel commands](https://github.com/xrayxl/xrayxl-addin/blob/main/src/app/commands.cpp): `src/app/commands.cpp`
- [Excel events](https://github.com/xrayxl/xrayxl-addin/blob/main/src/app/appevents.cpp): `src/app/appevents.cpp`

### XLL Tracing

- [Arm XLL hooks](https://github.com/xrayxl/xrayxl-addin/blob/main/src/xll/xllarm.cpp): `src/xll/xllarm.cpp`
- [Registration lookup](https://github.com/xrayxl/xrayxl-addin/blob/main/src/xll/xllregistry.cpp): `src/xll/xllregistry.cpp`
- [Late registrations](https://github.com/xrayxl/xrayxl-addin/blob/main/src/xll/xllregister_watch.cpp): `src/xll/xllregister_watch.cpp`
- [XLL detours](https://github.com/xrayxl/xrayxl-addin/blob/main/src/xll/xllhook.cpp): `src/xll/xllhook.cpp`
- [XLL recorder](https://github.com/xrayxl/xrayxl-addin/blob/main/src/xll/xlltrace.cpp): `src/xll/xlltrace.cpp`

### VBA Tracing

- [VBA interpreter hooks](https://github.com/xrayxl/xrayxl-addin/blob/main/src/vba/vbapatch.cpp): `src/vba/vbapatch.cpp`
- [Opcode analysis](https://github.com/xrayxl/xrayxl-addin/blob/main/src/vba/vbapcode.cpp): `src/vba/vbapcode.cpp`
- [VBA recorder](https://github.com/xrayxl/xrayxl-addin/blob/main/src/vba/vbatrace.cpp): `src/vba/vbatrace.cpp`
- [Procedure identity](https://github.com/xrayxl/xrayxl-addin/blob/main/src/vba/vbaidentity.cpp): `src/vba/vbaidentity.cpp`

### Trace Output

- [Trace writer](https://github.com/xrayxl/xrayxl-addin/blob/main/src/emit/csv.cpp): `src/emit/csv.cpp`
- [Buffered drain](https://github.com/xrayxl/xrayxl-addin/blob/main/src/emit/ring.cpp): `src/emit/ring.cpp`
- **CSV or JSONL trace**

### User Support

- [Ribbon controls](https://github.com/xrayxl/xrayxl-addin/blob/main/src/ui/ribbon.cpp): `src/ui/ribbon.cpp`
- [Crash diagnostics](https://github.com/xrayxl/xrayxl-addin/blob/main/src/core/crashlog.cpp): `src/core/crashlog.cpp`

### Other components

- **Excel user**
- **Excel process**

## Connections

- Excel user → Ribbon controls: controls (evidence: `src/ui/ribbon.cpp`)
- Ribbon controls → Session lifecycle: arms or disarms (evidence: `src/ui/ribbon.cpp`)
- Excel process → Excel commands: invokes
- Excel commands → Session lifecycle: controls session
- Session lifecycle → Arm XLL hooks: arms XLL (evidence: `src/app/session.cpp`)
- Session lifecycle → VBA interpreter hooks: arms VBA (evidence: `src/app/session.cpp`)
- Session lifecycle → Excel events: starts event capture (evidence: `src/app/session.cpp`)
- Arm XLL hooks → Registration lookup: resolves exports (evidence: `src/xll/xllarm.cpp`)
- Arm XLL hooks → Late registrations: installs watcher (evidence: `src/xll/xllarm.cpp`)
- Arm XLL hooks → XLL detours: installs detours (evidence: `src/xll/xllarm.cpp`)
- XLL detours → XLL recorder: records calls (evidence: `src/xll/xllhook.cpp`)
- VBA interpreter hooks → Opcode analysis: analyzes opcodes (evidence: `src/vba/vbapatch.cpp`)
- VBA interpreter hooks → Procedure identity: resolves procedures (evidence: `src/vba/vbapatch.cpp`)
- VBA interpreter hooks → VBA recorder: hooks interpreter (evidence: `src/vba/vbapatch.cpp`)
- VBA recorder → Procedure identity: uses identity (evidence: `src/vba/vbatrace.cpp`)
- XLL recorder → Trace writer: writes rows
- VBA recorder → Trace writer: writes rows (evidence: `src/vba/vbatrace.cpp`)
- Excel events → Trace writer: writes event rows
- Session lifecycle → Trace writer: opens and closes (evidence: `src/app/session.cpp`)
- Trace writer → Buffered drain: buffers and drains (evidence: `src/emit/csv.cpp`)
- Trace writer → CSV or JSONL trace: writes trace (evidence: `src/emit/csv.cpp`)
- Excel process → Crash diagnostics: reports faults