# storytold/gridcraft architecture

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

- Interactive diagram: https://gitdiagram.com/storytold/gridcraft
- Repository: https://github.com/storytold/gridcraft

## Overview

GridCraft is a cross-platform spreadsheet application, with native desktop and browser shells plus headless CLI and agent interfaces. Users open or create workbooks, edit and analyze sheets through a shared command/session engine, recalculate formulas, and save or export results. The map preserves documented capabilities such as charts, pivots, printing, and workbook compatibility, while showing only relationships evidenced by the README or supplied source index/excerpts; unsampled subsystem links are omitted where their callers are not established.

Main entry points: [`crates/engine/src/lib.rs`](https://github.com/storytold/gridcraft/blob/main/crates/engine/src/lib.rs) (Session Engine), [`apps/gridcraft-web/src/web.rs`](https://github.com/storytold/gridcraft/blob/main/apps/gridcraft-web/src/web.rs) (Browser Shell), [`crates/model/src/workbook.rs`](https://github.com/storytold/gridcraft/blob/main/crates/model/src/workbook.rs) (Workbook Model), [`crates/ui-egui/src/app.rs`](https://github.com/storytold/gridcraft/blob/main/crates/ui-egui/src/app.rs) (Spreadsheet UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Interfaces"]
  node_desktop["Desktop Shell<br/>[main.rs]"]
  node_web["Browser Shell<br/>[web.rs]"]
  node_ui["Spreadsheet UI<br/>[app.rs]"]
  node_localstore[("Browser Preferences<br/>[prefs.rs]")]
end

subgraph group_workbook["Workbook Operations"]
  node_commands["Workbook Commands<br/>[cmd.rs]"]
  node_engine["Session Engine<br/>[lib.rs]"]
  node_model["Workbook Model<br/>[workbook.rs]"]
  node_charts["Chart Rendering<br/>[render.rs]"]
  node_pivot["Pivot Tables<br/>[compute.rs]"]
end

subgraph group_compute["Spreadsheet Computation"]
  node_formula["Formula Parser<br/>[parser.rs]"]
  node_calc["Recalculation<br/>[recalc.rs]"]
  node_functions["Worksheet Functions<br/>[lib.rs]"]
  node_numfmt["Number Formatting<br/>[decimal.rs]"]
end

subgraph group_formats["Files and Output"]
  node_xlsx["Workbook Formats<br/>[sheet_read.rs]"]
  node_io["File Operations<br/>[io.rs]"]
  node_pdf["PDF Output<br/>[lib.rs]"]
end

subgraph group_agents["Automation Interfaces"]
  node_cli["Headless CLI<br/>[main.rs]"]
  node_control["JSON Control<br/>[control_server.rs]"]
  node_mcp["MCP Server<br/>[server.rs]"]
end

node_user(("Spreadsheet User"))
node_browser(("Browser Host"))
node_files["Workbook Files"]

node_user -->|"launches"| node_desktop
node_user -->|"opens"| node_web
node_desktop -->|"starts"| node_ui
node_web -->|"runs"| node_ui
node_ui -.->|"dispatches"| node_commands
node_commands -.->|"executes"| node_engine
node_engine -.->|"updates"| node_model
node_model -.->|"stores formulas"| node_formula
node_engine -.->|"recalculates"| node_calc
node_calc -.->|"evaluates"| node_functions
node_model -.->|"formats values"| node_numfmt
node_engine -.->|"renders charts"| node_charts
node_engine -.->|"computes pivots"| node_pivot
node_engine -.->|"handles files"| node_io
node_io -.->|"reads and writes"| node_xlsx
node_engine -.->|"exports PDF"| node_pdf
node_files -.->|"opened or saved"| node_io
node_cli -.->|"runs headless"| node_engine
node_control -.->|"controls"| node_engine
node_mcp -.->|"dispatches tools"| node_engine
node_web -->|"stores preferences"| node_localstore
node_browser -->|"hosts"| node_web

click node_desktop "https://github.com/storytold/gridcraft/blob/main/apps/gridcraft/src/main.rs"
click node_web "https://github.com/storytold/gridcraft/blob/main/apps/gridcraft-web/src/web.rs"
click node_ui "https://github.com/storytold/gridcraft/blob/main/crates/ui-egui/src/app.rs"
click node_commands "https://github.com/storytold/gridcraft/blob/main/crates/engine/src/cmd.rs"
click node_engine "https://github.com/storytold/gridcraft/blob/main/crates/engine/src/lib.rs"
click node_model "https://github.com/storytold/gridcraft/blob/main/crates/model/src/workbook.rs"
click node_formula "https://github.com/storytold/gridcraft/blob/main/crates/formula/src/parser.rs"
click node_calc "https://github.com/storytold/gridcraft/blob/main/crates/calc/src/recalc.rs"
click node_functions "https://github.com/storytold/gridcraft/blob/main/crates/functions/src/lib.rs"
click node_numfmt "https://github.com/storytold/gridcraft/blob/main/crates/numfmt/src/decimal.rs"
click node_charts "https://github.com/storytold/gridcraft/blob/main/crates/chart/src/render.rs"
click node_pivot "https://github.com/storytold/gridcraft/blob/main/crates/engine/src/pivot/compute.rs"
click node_xlsx "https://github.com/storytold/gridcraft/blob/main/crates/xlsx/src/sheet_read.rs"
click node_io "https://github.com/storytold/gridcraft/blob/main/crates/engine/src/io.rs"
click node_pdf "https://github.com/storytold/gridcraft/blob/main/crates/pdf/src/lib.rs"
click node_cli "https://github.com/storytold/gridcraft/blob/main/apps/gridcraft-cli/src/main.rs"
click node_control "https://github.com/storytold/gridcraft/blob/main/apps/gridcraft/src/control_server.rs"
click node_mcp "https://github.com/storytold/gridcraft/blob/main/crates/mcp/src/server.rs"
click node_localstore "https://github.com/storytold/gridcraft/blob/main/apps/gridcraft-web/src/prefs.rs"

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_desktop,node_web,node_ui,node_localstore,node_user,node_browser toneBlue
class node_commands,node_engine,node_model,node_charts,node_pivot toneAmber
class node_formula,node_calc,node_functions,node_numfmt toneMint
class node_xlsx,node_io,node_pdf toneRose
class node_cli,node_control,node_mcp,node_files toneIndigo
```

## Components

### User Interfaces

- [Desktop Shell](https://github.com/storytold/gridcraft/blob/main/apps/gridcraft/src/main.rs): `apps/gridcraft/src/main.rs`
- [Browser Shell](https://github.com/storytold/gridcraft/blob/main/apps/gridcraft-web/src/web.rs): `apps/gridcraft-web/src/web.rs`
- [Spreadsheet UI](https://github.com/storytold/gridcraft/blob/main/crates/ui-egui/src/app.rs): `crates/ui-egui/src/app.rs`
- [Browser Preferences](https://github.com/storytold/gridcraft/blob/main/apps/gridcraft-web/src/prefs.rs): `apps/gridcraft-web/src/prefs.rs`

### Workbook Operations

- [Workbook Commands](https://github.com/storytold/gridcraft/blob/main/crates/engine/src/cmd.rs): `crates/engine/src/cmd.rs`
- [Session Engine](https://github.com/storytold/gridcraft/blob/main/crates/engine/src/lib.rs): `crates/engine/src/lib.rs`
- [Workbook Model](https://github.com/storytold/gridcraft/blob/main/crates/model/src/workbook.rs): `crates/model/src/workbook.rs`
- [Chart Rendering](https://github.com/storytold/gridcraft/blob/main/crates/chart/src/render.rs): `crates/chart/src/render.rs`
- [Pivot Tables](https://github.com/storytold/gridcraft/blob/main/crates/engine/src/pivot/compute.rs): `crates/engine/src/pivot/compute.rs`

### Spreadsheet Computation

- [Formula Parser](https://github.com/storytold/gridcraft/blob/main/crates/formula/src/parser.rs): `crates/formula/src/parser.rs`
- [Recalculation](https://github.com/storytold/gridcraft/blob/main/crates/calc/src/recalc.rs): `crates/calc/src/recalc.rs`
- [Worksheet Functions](https://github.com/storytold/gridcraft/blob/main/crates/functions/src/lib.rs): `crates/functions/src/lib.rs`
- [Number Formatting](https://github.com/storytold/gridcraft/blob/main/crates/numfmt/src/decimal.rs): `crates/numfmt/src/decimal.rs`

### Files and Output

- [Workbook Formats](https://github.com/storytold/gridcraft/blob/main/crates/xlsx/src/sheet_read.rs): `crates/xlsx/src/sheet_read.rs`
- [File Operations](https://github.com/storytold/gridcraft/blob/main/crates/engine/src/io.rs): `crates/engine/src/io.rs`
- [PDF Output](https://github.com/storytold/gridcraft/blob/main/crates/pdf/src/lib.rs): `crates/pdf/src/lib.rs`

### Automation Interfaces

- [Headless CLI](https://github.com/storytold/gridcraft/blob/main/apps/gridcraft-cli/src/main.rs): `apps/gridcraft-cli/src/main.rs`
- [JSON Control](https://github.com/storytold/gridcraft/blob/main/apps/gridcraft/src/control_server.rs): `apps/gridcraft/src/control_server.rs`
- [MCP Server](https://github.com/storytold/gridcraft/blob/main/crates/mcp/src/server.rs): `crates/mcp/src/server.rs`

### Other components

- **Spreadsheet User**
- **Browser Host**
- **Workbook Files**

## Connections

- Spreadsheet User → Desktop Shell: launches
- Spreadsheet User → Browser Shell: opens
- Desktop Shell → Spreadsheet UI: starts (evidence: `apps/gridcraft/src/main.rs`)
- Browser Shell → Spreadsheet UI: runs
- Spreadsheet UI → Workbook Commands: dispatches
- Workbook Commands → Session Engine: executes
- Session Engine → Workbook Model: updates
- Workbook Model → Formula Parser: stores formulas
- Session Engine → Recalculation: recalculates
- Recalculation → Worksheet Functions: evaluates
- Workbook Model → Number Formatting: formats values
- Session Engine → Chart Rendering: renders charts
- Session Engine → Pivot Tables: computes pivots
- Session Engine → File Operations: handles files
- File Operations → Workbook Formats: reads and writes
- Session Engine → PDF Output: exports PDF
- Workbook Files → File Operations: opened or saved
- Headless CLI → Session Engine: runs headless
- JSON Control → Session Engine: controls
- MCP Server → Session Engine: dispatches tools
- Browser Shell → Browser Preferences: stores preferences (evidence: `apps/gridcraft-web/src/main.rs`)
- Browser Host → Browser Shell: hosts
