# lucas-spink/research-notebook architecture

> Architecture diagram of the GitHub repository lucas-spink/research-notebook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucas-spink/research-notebook
- Repository: https://github.com/lucas-spink/research-notebook

## Overview

The repository is a desktop computational research notebook: users create or open a project folder, manage experiment records and evidence in its table-based editor, and inspect results and file previews. The README identifies plain Markdown, YAML and CSL-JSON in `_notebook/` as the durable record; the format package parses and serializes it. The graph also includes external-change reconciliation, citations, and the VS Code capture extension as documented product capabilities. Sampled source supports project and notebook orchestration, preview loading, and file watching; links for unsampled subsystems are limited to documented scope and tree paths.

Main entry points: [`apps/desktop/src-tauri/src/commands/mod.rs`](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src-tauri/src/commands/mod.rs) (Tauri commands), [`apps/desktop/src/features/notebook/useNotebook.ts`](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/features/notebook/useNotebook.ts) (Notebook editor), [`apps/desktop/src/features/projects/model/flows.ts`](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/features/projects/model/flows.ts) (Project flows), [`apps/desktop/src/features/conflicts/useExternalChanges.ts`](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/features/conflicts/useExternalChanges.ts) (Change conflicts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Desktop experience"]
  node_desktop["Desktop UI<br/>[App.tsx]"]
  node_projects["Project flows<br/>[flows.ts]"]
  node_notebook_ui["Notebook editor<br/>[useNotebook.ts]"]
  node_results["Results tree<br/>[useResultsTree.ts]"]
  node_preview["File preview<br/>[usePreview.ts]"]
  node_conflicts["Change conflicts"]
end

subgraph group_records["Notebook records"]
  node_format["Format and domain<br/>[index.ts]"]
  node_files["Project files<br/>[lib.rs]"]
  node_history["Version history<br/>[mod.rs]"]
  node_index["Notebook search<br/>[lib.rs]"]
  node_citations["Citation handling<br/>[index.ts]"]
end

subgraph group_services["Native services"]
  node_commands["Tauri commands<br/>[mod.rs]"]
  node_preview_engine["Preview rendering<br/>[lib.rs]"]
  node_git["Git provenance<br/>[lib.rs]"]
end

subgraph group_integrations["Capture and citations"]
  node_vscode["VS Code capture<br/>[extension.ts]"]
  node_citation_engine["Citeproc engine<br/>[citeproc-engine.ts]"]
end

node_researcher(("Researcher"))
node_external_editor["External applications"]
node_project_store[("Notebook folder")]
node_filesystem[("Local filesystem")]

node_researcher -->|"uses"| node_desktop
node_desktop -->|"presents"| node_projects
node_projects -->|"invokes"| node_commands
node_projects -->|"starts watch"| node_conflicts
node_projects -->|"opens project"| node_notebook_ui
node_notebook_ui -->|"edits records"| node_format
node_notebook_ui -->|"reads and writes"| node_commands
node_results -->|"requests actions"| node_notebook_ui
node_preview -->|"requests preview"| node_commands
node_commands -->|"renders"| node_preview_engine
node_commands -->|"accesses"| node_files
node_commands -->|"manages versions"| node_history
node_commands -->|"searches"| node_index
node_commands -->|"reads and writes"| node_project_store
node_files -->|"reads and writes"| node_filesystem
node_history -->|"stores snapshots"| node_filesystem
node_index -->|"indexes records"| node_project_store
node_conflicts -->|"polls changes"| node_commands
node_conflicts -->|"reports changes"| node_notebook_ui
node_vscode -.->|"submits capture"| node_commands
node_vscode -.->|"writes requests"| node_project_store
node_notebook_ui -.->|"uses citation data"| node_citations
node_citations -.->|"formats citations"| node_citation_engine
node_preview -->|"opens files"| node_external_editor
node_commands -.->|"gets provenance"| node_git

click node_desktop "https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/App.tsx"
click node_projects "https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/features/projects/model/flows.ts"
click node_notebook_ui "https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/features/notebook/useNotebook.ts"
click node_results "https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/features/results/useResultsTree.ts"
click node_preview "https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/features/preview/usePreview.ts"
click node_conflicts "https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/features/conflicts/useExternalChanges.ts"
click node_format "https://github.com/lucas-spink/research-notebook/blob/main/packages/format/src/index.ts"
click node_files "https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src-tauri/crates/nb-fs/src/lib.rs"
click node_history "https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src-tauri/crates/nb-fs/src/history/mod.rs"
click node_index "https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src-tauri/crates/nb-index/src/lib.rs"
click node_citations "https://github.com/lucas-spink/research-notebook/blob/main/packages/citations/src/index.ts"
click node_commands "https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src-tauri/src/commands/mod.rs"
click node_preview_engine "https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src-tauri/crates/nb-preview/src/lib.rs"
click node_git "https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src-tauri/crates/nb-git/src/lib.rs"
click node_vscode "https://github.com/lucas-spink/research-notebook/blob/main/extensions/vscode/src/extension.ts"
click node_citation_engine "https://github.com/lucas-spink/research-notebook/blob/main/packages/citations/src/spikes/citeproc-engine.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_desktop,node_projects,node_notebook_ui,node_results,node_preview,node_conflicts toneBlue
class node_format,node_files,node_history,node_index,node_citations,node_project_store,node_filesystem toneAmber
class node_commands,node_preview_engine,node_git toneMint
class node_vscode,node_citation_engine toneRose
class node_researcher,node_external_editor toneIndigo
```

## Components

### Desktop experience

- [Desktop UI](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/App.tsx): `apps/desktop/src/App.tsx`
- [Project flows](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/features/projects/model/flows.ts): `apps/desktop/src/features/projects/model/flows.ts`
- [Notebook editor](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/features/notebook/useNotebook.ts): `apps/desktop/src/features/notebook/useNotebook.ts`
- [Results tree](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/features/results/useResultsTree.ts): `apps/desktop/src/features/results/useResultsTree.ts`
- [File preview](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/features/preview/usePreview.ts): `apps/desktop/src/features/preview/usePreview.ts`
- [Change conflicts](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src/features/conflicts/useExternalChanges.ts): `apps/desktop/src/features/conflicts/useExternalChanges.ts`

### Notebook records

- [Format and domain](https://github.com/lucas-spink/research-notebook/blob/main/packages/format/src/index.ts): `packages/format/src/index.ts`
- [Project files](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src-tauri/crates/nb-fs/src/lib.rs): `apps/desktop/src-tauri/crates/nb-fs/src/lib.rs`
- [Version history](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src-tauri/crates/nb-fs/src/history/mod.rs): `apps/desktop/src-tauri/crates/nb-fs/src/history/mod.rs`
- [Notebook search](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src-tauri/crates/nb-index/src/lib.rs): `apps/desktop/src-tauri/crates/nb-index/src/lib.rs`
- [Citation handling](https://github.com/lucas-spink/research-notebook/blob/main/packages/citations/src/index.ts): `packages/citations/src/index.ts`

### Native services

- [Tauri commands](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src-tauri/src/commands/mod.rs): `apps/desktop/src-tauri/src/commands/mod.rs`
- [Preview rendering](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src-tauri/crates/nb-preview/src/lib.rs): `apps/desktop/src-tauri/crates/nb-preview/src/lib.rs`
- [Git provenance](https://github.com/lucas-spink/research-notebook/blob/main/apps/desktop/src-tauri/crates/nb-git/src/lib.rs): `apps/desktop/src-tauri/crates/nb-git/src/lib.rs`

### Capture and citations

- [VS Code capture](https://github.com/lucas-spink/research-notebook/blob/main/extensions/vscode/src/extension.ts): `extensions/vscode/src/extension.ts`
- [Citeproc engine](https://github.com/lucas-spink/research-notebook/blob/main/packages/citations/src/spikes/citeproc-engine.ts): `packages/citations/src/spikes/citeproc-engine.ts`

### Other components

- **Researcher**
- **External applications**
- **Notebook folder**
- **Local filesystem**

## Connections

- Researcher → Desktop UI: uses
- Desktop UI → Project flows: presents
- Project flows → Tauri commands: invokes
- Project flows → Change conflicts: starts watch
- Project flows → Notebook editor: opens project
- Notebook editor → Format and domain: edits records
- Notebook editor → Tauri commands: reads and writes
- Results tree → Notebook editor: requests actions
- File preview → Tauri commands: requests preview
- Tauri commands → Preview rendering: renders
- Tauri commands → Project files: accesses
- Tauri commands → Version history: manages versions
- Tauri commands → Notebook search: searches
- Tauri commands → Notebook folder: reads and writes
- Project files → Local filesystem: reads and writes
- Version history → Local filesystem: stores snapshots
- Notebook search → Notebook folder: indexes records
- Change conflicts → Tauri commands: polls changes
- Change conflicts → Notebook editor: reports changes
- VS Code capture → Tauri commands: submits capture
- VS Code capture → Notebook folder: writes requests
- Notebook editor → Citation handling: uses citation data
- Citation handling → Citeproc engine: formats citations
- File preview → External applications: opens files
- Tauri commands → Git provenance: gets provenance