# micheledelaney/nuthatch architecture

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

- Interactive diagram: https://gitdiagram.com/micheledelaney/nuthatch
- Repository: https://github.com/micheledelaney/nuthatch

## Overview

Nuthatch is a local FileMaker XML static-analysis app, with browser, desktop-webview, and CLI entry points. The main workflow loads one or more XML exports, parses them into a solution model, resolves references and computes analysis, then presents structure, dependencies, call chains, and risks. Other documented capabilities include analysis comparison, saved analyses, and AI-oriented export. Some UI and state wiring is supported by the SOURCE INDEX rather than inspected implementation excerpts; the parser-to-worker dispatch is therefore shown as unverified.

Main entry points: [`src/App.tsx`](https://github.com/micheledelaney/nuthatch/blob/main/src/App.tsx) (App coordinator), [`src/state/store.ts`](https://github.com/micheledelaney/nuthatch/blob/main/src/state/store.ts) (Application state), [`src/core/model/buildModel.ts`](https://github.com/micheledelaney/nuthatch/blob/main/src/core/model/buildModel.ts) (Solution model), [`src/cli/main.ts`](https://github.com/micheledelaney/nuthatch/blob/main/src/cli/main.ts) (CLI exporter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Input and parsing"]
  node_parser["DDR parser<br/>[parseDdr.ts]"]
  node_xmlutils["XML utilities<br/>[xmlUtils.ts]"]
  node_context["Parse context<br/>[context.ts]"]
  node_worker["Parse worker<br/>[parse.worker.ts]"]
  node_loader["File loading<br/>[loadFiles.ts]"]
end

subgraph group_analysis["Model and analysis"]
  node_model["Solution model<br/>[buildModel.ts]"]
  node_types["Domain model<br/>[ddr.ts]"]
  node_refs["Reference analysis<br/>[dependencies.ts]"]
  node_chains["Unused chains<br/>[unusedChains.ts]"]
  node_marks["Usage marks<br/>[usageMarks.ts]"]
  node_diff["Analysis comparison<br/>[diff.ts]"]
  node_search["Object search<br/>[search.ts]"]
end

subgraph group_app["Exploration interface"]
  node_app["App coordinator<br/>[App.tsx]"]
  node_navigator["Object navigator<br/>[Navigator.tsx]"]
  node_objectview["Object details<br/>[ObjectColumn.tsx]"]
  node_workbench["Workbench<br/>[Workbench.tsx]"]
  node_graphview["Relationship graph"]
  node_report["Risk report<br/>[ReportCardView.tsx]"]
  node_comparison["Comparison view<br/>[ComparisonView.tsx]"]
end

subgraph group_state["State and export"]
  node_store["Application state<br/>[store.ts]"]
  node_saved[("Saved analyses<br/>[savedAnalyses.ts]")]
  node_ai["AI export<br/>[aiExport.ts]"]
  node_exportstate["Export actions<br/>[exportAnalysis.ts]"]
end

subgraph group_entry["Other entry point"]
  node_cli["CLI exporter<br/>[main.ts]"]
end

node_user(("Analyst"))
node_xml["XML exports"]
node_browser["Browser app"]
node_desktop["Desktop webview"]

node_user -->|"opens"| node_browser
node_user -->|"opens"| node_desktop
node_user -->|"loads"| node_xml
node_browser -->|"runs"| node_app
node_desktop -.->|"runs"| node_app
node_app -->|"reads state"| node_store
node_store -.->|"dispatches parse"| node_worker
node_worker -->|"loads files"| node_loader
node_worker -->|"parses XML"| node_parser
node_parser -->|"builds context"| node_context
node_parser -->|"uses"| node_xmlutils
node_store -->|"builds model"| node_model
node_model -->|"computes references"| node_refs
node_model -->|"finds unused chains"| node_chains
node_model -->|"resolves marks"| node_marks
node_model -->|"produces"| node_types
node_store -->|"compares analyses"| node_diff
node_app -->|"renders"| node_navigator
node_app -->|"renders"| node_workbench
node_app -->|"renders"| node_graphview
node_app -->|"renders"| node_report
node_app -->|"renders"| node_comparison
node_navigator -->|"reads model"| node_store
node_navigator -->|"uses search"| node_search
node_navigator -->|"opens details"| node_objectview
node_store -->|"persists analyses"| node_saved
node_store -->|"requests export"| node_exportstate
node_exportstate -->|"generates files"| node_ai
node_user -->|"runs command"| node_cli
node_cli -->|"loads files"| node_loader
node_cli -->|"parses exports"| node_parser
node_cli -->|"builds model"| node_model
node_cli -->|"writes export"| node_ai

click node_parser "https://github.com/micheledelaney/nuthatch/blob/main/src/core/parser/parseDdr.ts"
click node_xmlutils "https://github.com/micheledelaney/nuthatch/blob/main/src/core/parser/xmlUtils.ts"
click node_context "https://github.com/micheledelaney/nuthatch/blob/main/src/core/parser/context.ts"
click node_worker "https://github.com/micheledelaney/nuthatch/blob/main/src/worker/parse.worker.ts"
click node_loader "https://github.com/micheledelaney/nuthatch/blob/main/src/state/loadFiles.ts"
click node_model "https://github.com/micheledelaney/nuthatch/blob/main/src/core/model/buildModel.ts"
click node_types "https://github.com/micheledelaney/nuthatch/blob/main/src/types/ddr.ts"
click node_refs "https://github.com/micheledelaney/nuthatch/blob/main/src/core/analysis/dependencies.ts"
click node_chains "https://github.com/micheledelaney/nuthatch/blob/main/src/core/analysis/unusedChains.ts"
click node_marks "https://github.com/micheledelaney/nuthatch/blob/main/src/core/analysis/usageMarks.ts"
click node_diff "https://github.com/micheledelaney/nuthatch/blob/main/src/core/analysis/diff.ts"
click node_search "https://github.com/micheledelaney/nuthatch/blob/main/src/core/search/search.ts"
click node_app "https://github.com/micheledelaney/nuthatch/blob/main/src/App.tsx"
click node_navigator "https://github.com/micheledelaney/nuthatch/blob/main/src/components/Navigator.tsx"
click node_objectview "https://github.com/micheledelaney/nuthatch/blob/main/src/components/ObjectColumn.tsx"
click node_workbench "https://github.com/micheledelaney/nuthatch/blob/main/src/components/workbench/Workbench.tsx"
click node_graphview "https://github.com/micheledelaney/nuthatch/blob/main/src/components/RelationshipGraphView.tsx"
click node_report "https://github.com/micheledelaney/nuthatch/blob/main/src/components/ReportCardView.tsx"
click node_comparison "https://github.com/micheledelaney/nuthatch/blob/main/src/components/ComparisonView.tsx"
click node_store "https://github.com/micheledelaney/nuthatch/blob/main/src/state/store.ts"
click node_saved "https://github.com/micheledelaney/nuthatch/blob/main/src/state/savedAnalyses.ts"
click node_ai "https://github.com/micheledelaney/nuthatch/blob/main/src/core/export/aiExport.ts"
click node_exportstate "https://github.com/micheledelaney/nuthatch/blob/main/src/state/exportAnalysis.ts"
click node_cli "https://github.com/micheledelaney/nuthatch/blob/main/src/cli/main.ts"

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_parser,node_xmlutils,node_context,node_worker,node_loader,node_browser,node_desktop toneBlue
class node_model,node_types,node_refs,node_chains,node_marks,node_diff,node_search toneAmber
class node_app,node_navigator,node_objectview,node_workbench,node_graphview,node_report,node_comparison toneMint
class node_store,node_saved,node_ai,node_exportstate toneRose
class node_cli,node_user,node_xml toneIndigo
```

## Components

### Input and parsing

- [DDR parser](https://github.com/micheledelaney/nuthatch/blob/main/src/core/parser/parseDdr.ts): `src/core/parser/parseDdr.ts`
- [XML utilities](https://github.com/micheledelaney/nuthatch/blob/main/src/core/parser/xmlUtils.ts): `src/core/parser/xmlUtils.ts`
- [Parse context](https://github.com/micheledelaney/nuthatch/blob/main/src/core/parser/context.ts): `src/core/parser/context.ts`
- [Parse worker](https://github.com/micheledelaney/nuthatch/blob/main/src/worker/parse.worker.ts): `src/worker/parse.worker.ts`
- [File loading](https://github.com/micheledelaney/nuthatch/blob/main/src/state/loadFiles.ts): `src/state/loadFiles.ts`

### Model and analysis

- [Solution model](https://github.com/micheledelaney/nuthatch/blob/main/src/core/model/buildModel.ts): `src/core/model/buildModel.ts`
- [Domain model](https://github.com/micheledelaney/nuthatch/blob/main/src/types/ddr.ts): `src/types/ddr.ts`
- [Reference analysis](https://github.com/micheledelaney/nuthatch/blob/main/src/core/analysis/dependencies.ts): `src/core/analysis/dependencies.ts`
- [Unused chains](https://github.com/micheledelaney/nuthatch/blob/main/src/core/analysis/unusedChains.ts): `src/core/analysis/unusedChains.ts`
- [Usage marks](https://github.com/micheledelaney/nuthatch/blob/main/src/core/analysis/usageMarks.ts): `src/core/analysis/usageMarks.ts`
- [Analysis comparison](https://github.com/micheledelaney/nuthatch/blob/main/src/core/analysis/diff.ts): `src/core/analysis/diff.ts`
- [Object search](https://github.com/micheledelaney/nuthatch/blob/main/src/core/search/search.ts): `src/core/search/search.ts`

### Exploration interface

- [App coordinator](https://github.com/micheledelaney/nuthatch/blob/main/src/App.tsx): `src/App.tsx`
- [Object navigator](https://github.com/micheledelaney/nuthatch/blob/main/src/components/Navigator.tsx): `src/components/Navigator.tsx`
- [Object details](https://github.com/micheledelaney/nuthatch/blob/main/src/components/ObjectColumn.tsx): `src/components/ObjectColumn.tsx`
- [Workbench](https://github.com/micheledelaney/nuthatch/blob/main/src/components/workbench/Workbench.tsx): `src/components/workbench/Workbench.tsx`
- [Relationship graph](https://github.com/micheledelaney/nuthatch/blob/main/src/components/RelationshipGraphView.tsx): `src/components/RelationshipGraphView.tsx`
- [Risk report](https://github.com/micheledelaney/nuthatch/blob/main/src/components/ReportCardView.tsx): `src/components/ReportCardView.tsx`
- [Comparison view](https://github.com/micheledelaney/nuthatch/blob/main/src/components/ComparisonView.tsx): `src/components/ComparisonView.tsx`

### State and export

- [Application state](https://github.com/micheledelaney/nuthatch/blob/main/src/state/store.ts): `src/state/store.ts`
- [Saved analyses](https://github.com/micheledelaney/nuthatch/blob/main/src/state/savedAnalyses.ts): `src/state/savedAnalyses.ts`
- [AI export](https://github.com/micheledelaney/nuthatch/blob/main/src/core/export/aiExport.ts): `src/core/export/aiExport.ts`
- [Export actions](https://github.com/micheledelaney/nuthatch/blob/main/src/state/exportAnalysis.ts): `src/state/exportAnalysis.ts`

### Other entry point

- [CLI exporter](https://github.com/micheledelaney/nuthatch/blob/main/src/cli/main.ts): `src/cli/main.ts`

### Other components

- **Analyst**
- **XML exports**
- **Browser app**
- **Desktop webview**

## Connections

- Analyst → Browser app: opens
- Analyst → Desktop webview: opens
- Analyst → XML exports: loads
- Browser app → App coordinator: runs
- Desktop webview → App coordinator: runs
- App coordinator → Application state: reads state (evidence: `src/App.tsx`)
- Application state → Parse worker: dispatches parse (evidence: `src/state/store.ts`)
- Parse worker → File loading: loads files (evidence: `src/worker/parse.worker.ts`)
- Parse worker → DDR parser: parses XML (evidence: `src/worker/parse.worker.ts`)
- DDR parser → Parse context: builds context (evidence: `src/core/parser/parseDdr.ts`)
- DDR parser → XML utilities: uses (evidence: `src/core/parser/parseDdr.ts`)
- Application state → Solution model: builds model (evidence: `src/state/store.ts`)
- Solution model → Reference analysis: computes references (evidence: `src/core/model/buildModel.ts`)
- Solution model → Unused chains: finds unused chains (evidence: `src/core/model/buildModel.ts`)
- Solution model → Usage marks: resolves marks (evidence: `src/core/model/buildModel.ts`)
- Solution model → Domain model: produces (evidence: `src/core/model/buildModel.ts`)
- Application state → Analysis comparison: compares analyses (evidence: `src/state/store.ts`)
- App coordinator → Object navigator: renders (evidence: `src/App.tsx`)
- App coordinator → Workbench: renders (evidence: `src/App.tsx`)
- App coordinator → Relationship graph: renders (evidence: `src/App.tsx`)
- App coordinator → Risk report: renders (evidence: `src/App.tsx`)
- App coordinator → Comparison view: renders (evidence: `src/App.tsx`)
- Object navigator → Application state: reads model (evidence: `src/components/Navigator.tsx`)
- Object navigator → Object search: uses search (evidence: `src/components/Navigator.tsx`)
- Object navigator → Object details: opens details (evidence: `src/components/ObjectColumn.tsx`)
- Application state → Saved analyses: persists analyses (evidence: `src/state/store.ts`)
- Application state → Export actions: requests export (evidence: `src/state/store.ts`)
- Export actions → AI export: generates files (evidence: `src/state/exportAnalysis.ts`)
- Analyst → CLI exporter: runs command
- CLI exporter → File loading: loads files (evidence: `src/cli/main.ts`)
- CLI exporter → DDR parser: parses exports (evidence: `src/cli/main.ts`)
- CLI exporter → Solution model: builds model (evidence: `src/cli/main.ts`)
- CLI exporter → AI export: writes export (evidence: `src/cli/main.ts`)
