# ethanvibe/excelcut architecture

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

- Interactive diagram: https://gitdiagram.com/ethanvibe/excelcut
- Repository: https://github.com/ethanvibe/excelcut

## Overview

ExPierceViz is a desktop Excel-data composition and visualization tool. Users upload spreadsheets, select and combine fields, configure calculations and aggregations, inspect composed data, switch to charting, then export the table or chart. The architecture separates file parsing, composition, shared application state, and visualization/export UI. The README documents broader product capabilities; sampled excerpts confirm the primary composition and chart paths, but not every implementation detail. Electron is represented as the documented desktop host; its source was not excerpted.

Main entry points: [`src/App.tsx`](https://github.com/ethanvibe/excelcut/blob/main/src/App.tsx) (App shell), [`src/store/AppContext.tsx`](https://github.com/ethanvibe/excelcut/blob/main/src/store/AppContext.tsx) (Application state), [`src/components/FilePanel.tsx`](https://github.com/ethanvibe/excelcut/blob/main/src/components/FilePanel.tsx) (File panel), [`src/components/VizPage.tsx`](https://github.com/ethanvibe/excelcut/blob/main/src/components/VizPage.tsx) (Charting and export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Application shell"]
  node_desktop["Electron host<br/>[main.cjs]"]
  node_entry["React entry<br/>[main.tsx]"]
  node_app["App shell<br/>[App.tsx]"]
end

subgraph group_data["Data preparation"]
  node_files["File panel<br/>[FilePanel.tsx]"]
  node_parser["Excel parser<br/>[excel.ts]"]
  node_workspace["Data workspace<br/>[DataWorkspace.tsx]"]
  node_composition["Data composition<br/>[excel.ts]"]
  node_config["Field configuration<br/>[ConfigPanel.tsx]"]
end

subgraph group_visuals["Visualization and export"]
  node_navigation["Navigation and export<br/>[TopNav.tsx]"]
  node_charts["Charting and export<br/>[VizPage.tsx]"]
end

subgraph group_shared["Shared UI and state"]
  node_state["Application state<br/>[AppContext.tsx]"]
  node_toasts["Notifications<br/>[Toast.tsx]"]
  node_footer["Footer<br/>[Footer.tsx]"]
  node_button["Button control<br/>[button.tsx]"]
end

node_user(("User"))

node_user -.->|"launches"| node_desktop
node_desktop -.->|"hosts"| node_entry
node_entry -->|"renders"| node_app
node_app -->|"renders"| node_files
node_app -->|"renders"| node_workspace
node_app -->|"renders"| node_config
node_app -->|"renders"| node_charts
node_app -->|"renders"| node_navigation
node_app -->|"renders"| node_footer
node_app -->|"provides state"| node_state
node_app -->|"provides notifications"| node_toasts
node_files -->|"parses files"| node_parser
node_files -->|"updates files"| node_state
node_workspace -->|"composes data"| node_composition
node_workspace -->|"reads and updates"| node_state
node_config -->|"updates settings"| node_state
node_navigation -->|"reads state"| node_state
node_charts -->|"reads chart data"| node_state
node_files -->|"reports status"| node_toasts
node_config -->|"reports status"| node_toasts
node_charts -->|"reports export status"| node_toasts
node_navigation -->|"uses controls"| node_button
node_charts -->|"uses controls"| node_button
node_user -->|"uploads spreadsheets"| node_files
node_user -->|"selects fields"| node_workspace
node_user -->|"configures charts"| node_charts
node_user -->|"exports table"| node_navigation

click node_desktop "https://github.com/ethanvibe/excelcut/blob/main/electron/main.cjs"
click node_entry "https://github.com/ethanvibe/excelcut/blob/main/src/main.tsx"
click node_app "https://github.com/ethanvibe/excelcut/blob/main/src/App.tsx"
click node_files "https://github.com/ethanvibe/excelcut/blob/main/src/components/FilePanel.tsx"
click node_parser "https://github.com/ethanvibe/excelcut/blob/main/src/lib/excel.ts"
click node_workspace "https://github.com/ethanvibe/excelcut/blob/main/src/components/DataWorkspace.tsx"
click node_composition "https://github.com/ethanvibe/excelcut/blob/main/src/lib/excel.ts"
click node_config "https://github.com/ethanvibe/excelcut/blob/main/src/components/ConfigPanel.tsx"
click node_navigation "https://github.com/ethanvibe/excelcut/blob/main/src/components/TopNav.tsx"
click node_charts "https://github.com/ethanvibe/excelcut/blob/main/src/components/VizPage.tsx"
click node_state "https://github.com/ethanvibe/excelcut/blob/main/src/store/AppContext.tsx"
click node_toasts "https://github.com/ethanvibe/excelcut/blob/main/src/components/Toast.tsx"
click node_footer "https://github.com/ethanvibe/excelcut/blob/main/src/components/Footer.tsx"
click node_button "https://github.com/ethanvibe/excelcut/blob/main/src/components/ui/button.tsx"

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_entry,node_app,node_user toneBlue
class node_files,node_parser,node_workspace,node_composition,node_config toneAmber
class node_navigation,node_charts toneMint
class node_state,node_toasts,node_footer,node_button toneRose
```

## Components

### Application shell

- [Electron host](https://github.com/ethanvibe/excelcut/blob/main/electron/main.cjs): `electron/main.cjs`
- [React entry](https://github.com/ethanvibe/excelcut/blob/main/src/main.tsx): `src/main.tsx`
- [App shell](https://github.com/ethanvibe/excelcut/blob/main/src/App.tsx): `src/App.tsx`

### Data preparation

- [File panel](https://github.com/ethanvibe/excelcut/blob/main/src/components/FilePanel.tsx): `src/components/FilePanel.tsx`
- [Excel parser](https://github.com/ethanvibe/excelcut/blob/main/src/lib/excel.ts): `src/lib/excel.ts`
- [Data workspace](https://github.com/ethanvibe/excelcut/blob/main/src/components/DataWorkspace.tsx): `src/components/DataWorkspace.tsx`
- [Data composition](https://github.com/ethanvibe/excelcut/blob/main/src/lib/excel.ts): `src/lib/excel.ts`
- [Field configuration](https://github.com/ethanvibe/excelcut/blob/main/src/components/ConfigPanel.tsx): `src/components/ConfigPanel.tsx`

### Visualization and export

- [Navigation and export](https://github.com/ethanvibe/excelcut/blob/main/src/components/TopNav.tsx): `src/components/TopNav.tsx`
- [Charting and export](https://github.com/ethanvibe/excelcut/blob/main/src/components/VizPage.tsx): `src/components/VizPage.tsx`

### Shared UI and state

- [Application state](https://github.com/ethanvibe/excelcut/blob/main/src/store/AppContext.tsx): `src/store/AppContext.tsx`
- [Notifications](https://github.com/ethanvibe/excelcut/blob/main/src/components/Toast.tsx): `src/components/Toast.tsx`
- [Footer](https://github.com/ethanvibe/excelcut/blob/main/src/components/Footer.tsx): `src/components/Footer.tsx`
- [Button control](https://github.com/ethanvibe/excelcut/blob/main/src/components/ui/button.tsx): `src/components/ui/button.tsx`

### Other components

- **User**

## Connections

- User → Electron host: launches
- Electron host → React entry: hosts
- React entry → App shell: renders (evidence: `src/main.tsx`)
- App shell → File panel: renders (evidence: `src/App.tsx`)
- App shell → Data workspace: renders (evidence: `src/App.tsx`)
- App shell → Field configuration: renders (evidence: `src/App.tsx`)
- App shell → Charting and export: renders (evidence: `src/App.tsx`)
- App shell → Navigation and export: renders (evidence: `src/App.tsx`)
- App shell → Footer: renders (evidence: `src/App.tsx`)
- App shell → Application state: provides state (evidence: `src/App.tsx`)
- App shell → Notifications: provides notifications (evidence: `src/App.tsx`)
- File panel → Excel parser: parses files (evidence: `src/components/FilePanel.tsx`)
- File panel → Application state: updates files (evidence: `src/components/FilePanel.tsx`)
- Data workspace → Data composition: composes data (evidence: `src/components/DataWorkspace.tsx`)
- Data workspace → Application state: reads and updates (evidence: `src/components/DataWorkspace.tsx`)
- Field configuration → Application state: updates settings (evidence: `src/components/ConfigPanel.tsx`)
- Navigation and export → Application state: reads state (evidence: `src/components/TopNav.tsx`)
- Charting and export → Application state: reads chart data (evidence: `src/components/VizPage.tsx`)
- File panel → Notifications: reports status (evidence: `src/components/FilePanel.tsx`)
- Field configuration → Notifications: reports status (evidence: `src/components/ConfigPanel.tsx`)
- Charting and export → Notifications: reports export status (evidence: `src/components/VizPage.tsx`)
- Navigation and export → Button control: uses controls (evidence: `src/components/TopNav.tsx`)
- Charting and export → Button control: uses controls (evidence: `src/components/VizPage.tsx`)
- User → File panel: uploads spreadsheets (evidence: `src/components/FilePanel.tsx`)
- User → Data workspace: selects fields (evidence: `src/components/DataWorkspace.tsx`)
- User → Charting and export: configures charts (evidence: `src/components/VizPage.tsx`)
- User → Navigation and export: exports table (evidence: `src/components/TopNav.tsx`)
