# vld-b/bismuth architecture

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

- Interactive diagram: https://gitdiagram.com/vld-b/bismuth
- Repository: https://github.com/vld-b/bismuth

## Overview

1. **What this repo is**
   - Bismuth is a **Windows 11 note-taking and PDF annotation app** built as a packaged desktop app.
   - The UI is XAML-based and optimized for **keyboard, pen, and touch/finger input**.

2. **Top-level project split**
   - **WID/** is the main application: windows/pages, editing surface, notebook UI, persistence, and app logic.
   - **Shared/** contains reusable XAML controls and color-picking helpers used across the app.
   - **AppSettings/** holds strongly-typed app configuration and config migration logic.
   - The solution is built from a single Visual Studio solution, with a GitHub Actions workflow for .NET builds.

3. **Application shell and navigation**
   - `App.xaml` / `App.xaml.cs` are the app entry point.
   - `ExtendedSplashScreen` is the startup experience, backed by a Lottie animation asset.
   - `MainPage` is the central host that likely routes the user into notebooks, canvas editing, and settings.

4. **Notebook-centric domain model**
   - The app is organized around **notebooks and pages**, not around a generic document editor.
   - `NotebookList`, `NotebookPage`, `NotebookSearchResult`, `PageThumbnail`, and `CreateNewNotebookOptions` define the notebook lifecycle:
     - browsing notebooks
     - opening a notebook
     - creating a new notebook
     - showing search results
     - rendering page previews/thumbnails

5. **Canvas and annotation subsystem**
   - `CanvasPage` is the core editing surface for ink and page content.
   - `CustomInkToolbarTool`, `ManipulateInkRect`, and `OnPageImage` / `OnPageText` support mixed annotation workflows:
     - freehand ink
     - selecting/manipulating ink regions
     - placing images on a page
     - placing/editing text on a page
   - `IOnPageItem` indicates a common abstraction for objects that can exist on a page.

6. **Input and visual tools**
   - `Shared/ColorPickerButton.xaml(.cs)` and `Shared/SimpleColorPicker.cs` provide reusable color selection for ink or page elements.
   - This is important because the app supports stylus-driven editing, where color and tool selection are part of the main workflow.
   - `MenuElement` and related UI pieces likely represent editor commands/tools in the in-app UI.

7. **State management and editing history**
   - `UndoObject` and `UndoRedoSystem` form the editing history layer.
   - The data flow is likely: user interaction on the canvas → mutation of page content → push undo record → allow reversal/restoration.
   - This is a key architectural boundary between transient UI events and durable document state.

8. **Persistence and file operations**
   - `FileConfig`, `PendingFileOperationsSystem`, and `SavingFileDialog` show that file handling is explicit rather than hidden behind a framework.
   - The app appears to manage notebook/document files directly, with deferred or queued file actions when necessary.
   - `NotebookUpgrader` and `SettingsConfigUpgrader` indicate schema/version migration for stored notebooks and config files.

9. **Settings and configuration**
   - `SettingsPage` is the user-facing settings UI.
   - `AppSettings/Settings.cs` defines the app’s configuration model.
   - Configuration is separated from the main app code, which helps keep user preferences and persisted app state distinct from notebook content.

10. **Assets and packaging**
   - `Package.appxmanifest` shows this is packaged for the Microsoft Store / Windows app model.
   - The app includes startup animation assets (`anim_startup.json` and `.lottie`), which suggests polished launch UX.
   - `PRIVACYPOLICY.md` reinforces that this is a consumer app with a store-style distribution model.

11. **Architectural boundaries to draw**
   - **UI layer:** XAML pages and controls in `WID/` plus shared controls in `Shared/`.
   - **Editing layer:** canvas, ink tools, page item manipulation, undo/redo.
   - **Document layer:** notebook/page/search/thumbnail structures and migrations.
   - **Configuration layer:** settings objects and settings migration.
   - **File system layer:** config, pending operations, save dialogs, and upgrader logic.

12. **Primary runtime flow**
   - Launch app → splash screen → main page → notebook selection/opening → canvas editing.
   - While editing, user actions update page items and are captured by undo/redo.
   - Changes eventually pass through the file/persistence layer and may be upgraded when older notebook/settings formats are encountered.

13. **Tooling and delivery**
   - The presence of `.github/workflows/dotnet.yml` indicates automated build validation in CI.
   - Overall, this is a **Windows-native, XAML-based note and annotation application** with a strong separation between editor UI, document state, and persistence.

Main entry points: [`WID/CanvasPage.xaml`](https://github.com/vld-b/bismuth/blob/master/WID/CanvasPage.xaml) (Canvas), [`WID/NotebookList.xaml`](https://github.com/vld-b/bismuth/blob/master/WID/NotebookList.xaml) (Notebook List), [`WID/App.xaml`](https://github.com/vld-b/bismuth/blob/master/WID/App.xaml) (App), [`WID/ExtendedSplashScreen.xaml`](https://github.com/vld-b/bismuth/blob/master/WID/ExtendedSplashScreen.xaml) (Splash)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_app_entry["App<br/>[App.xaml]"]
  node_app_splash["Splash<br/>startup screen"]
  node_app_main["Main Page<br/>shell host<br/>[MainPage.xaml]"]
end

subgraph group_document["Notebook Domain"]
  node_doc_list["Notebook List<br/>notebook browser<br/>[NotebookList.xaml]"]
  node_doc_page["Notebook Page<br/>notebook view<br/>[NotebookPage.xaml]"]
  node_doc_search["Search Result<br/>result view"]
  node_doc_create["New Notebook<br/>creation dialog"]
  node_doc_thumb["Page Thumbnail<br/>preview view<br/>[PageThumbnail.xaml]"]
  node_doc_model{{"Page Model<br/>page abstractions<br/>[IOnPageItem.cs]"}}
end

subgraph group_editing["Editing Surface"]
  node_edit_canvas["Canvas<br/>editor surface<br/>[CanvasPage.xaml]"]
  node_edit_tool["Ink Tool<br/>tool control"]
  node_edit_manip["Ink Manipulator<br/>selection control"]
  node_edit_image["Page Image<br/>page item<br/>[OnPageImage.xaml]"]
  node_edit_text["Page Text<br/>page item<br/>[OnPageText.xaml]"]
  node_edit_undo[("Undo System<br/>history system<br/>[UndoRedoSystem.cs]")]
end

subgraph group_persistence["Persistence"]
  node_persist_ops[("File Ops<br/>file system layer<br/>[FileConfig.cs]")]
  node_persist_migrate["Upgraders<br/>migration layer"]
end

subgraph group_settings["Settings"]
  node_settings_model["Settings Model<br/>config model<br/>[Settings.cs]"]
  node_settings_page["Settings Page<br/>settings UI<br/>[SettingsPage.xaml]"]
end

subgraph group_shared["Shared Controls"]
  node_shared_color(("Color Picker<br/>shared control"))
end

subgraph group_delivery["Delivery"]
  node_delivery_pkg["Package<br/>appx manifest"]
  node_delivery_assets["Startup Assets<br/>animation assets<br/>[anim_startup.json]"]
  node_delivery_ci["CI Build<br/>workflow<br/>[dotnet.yml]"]
end

node_app_entry -->|"launches"| node_app_splash
node_app_splash -->|"navigates"| node_app_main
node_app_main -->|"opens"| node_doc_list
node_app_main -->|"opens"| node_settings_page
node_doc_list -->|"creates"| node_doc_create
node_doc_list -->|"searches"| node_doc_search
node_doc_list -->|"shows"| node_doc_thumb
node_doc_list -->|"opens"| node_doc_page
node_doc_page -->|"hosts"| node_edit_canvas
node_edit_canvas -->|"selects"| node_edit_tool
node_edit_canvas -->|"manipulates"| node_edit_manip
node_edit_canvas -->|"hosts"| node_edit_image
node_edit_canvas -->|"hosts"| node_edit_text
node_edit_canvas -->|"records"| node_edit_undo
node_edit_image -->|"implements"| node_doc_model
node_edit_text -->|"implements"| node_doc_model
node_edit_undo -->|"persists"| node_persist_ops
node_persist_ops -->|"upgrades"| node_persist_migrate
node_settings_page -->|"edits"| node_settings_model
node_settings_model -->|"migrates"| node_persist_migrate
node_shared_color -->|"supports"| node_edit_tool
node_shared_color -->|"supports"| node_settings_page
node_app_splash -->|"uses"| node_delivery_assets
node_app_entry -->|"packages"| node_delivery_pkg
node_app_entry -->|"validated by"| node_delivery_ci

click node_app_entry "https://github.com/vld-b/bismuth/blob/master/WID/App.xaml"
click node_app_splash "https://github.com/vld-b/bismuth/blob/master/WID/ExtendedSplashScreen.xaml"
click node_app_main "https://github.com/vld-b/bismuth/blob/master/WID/MainPage.xaml"
click node_doc_list "https://github.com/vld-b/bismuth/blob/master/WID/NotebookList.xaml"
click node_doc_page "https://github.com/vld-b/bismuth/blob/master/WID/NotebookPage.xaml"
click node_doc_search "https://github.com/vld-b/bismuth/blob/master/WID/NotebookSearchResult.xaml"
click node_doc_create "https://github.com/vld-b/bismuth/blob/master/WID/CreateNewNotebookOptions.xaml"
click node_doc_thumb "https://github.com/vld-b/bismuth/blob/master/WID/PageThumbnail.xaml"
click node_doc_model "https://github.com/vld-b/bismuth/blob/master/WID/IOnPageItem.cs"
click node_edit_canvas "https://github.com/vld-b/bismuth/blob/master/WID/CanvasPage.xaml"
click node_edit_tool "https://github.com/vld-b/bismuth/blob/master/WID/CustomInkToolbarTool.xaml"
click node_edit_manip "https://github.com/vld-b/bismuth/blob/master/WID/ManipulateInkRect.xaml"
click node_edit_image "https://github.com/vld-b/bismuth/blob/master/WID/OnPageImage.xaml"
click node_edit_text "https://github.com/vld-b/bismuth/blob/master/WID/OnPageText.xaml"
click node_edit_undo "https://github.com/vld-b/bismuth/blob/master/WID/UndoRedoSystem.cs"
click node_persist_ops "https://github.com/vld-b/bismuth/blob/master/WID/FileConfig.cs"
click node_persist_migrate "https://github.com/vld-b/bismuth/blob/master/WID/NotebookUpgrader.cs"
click node_settings_model "https://github.com/vld-b/bismuth/blob/master/AppSettings/Settings.cs"
click node_settings_page "https://github.com/vld-b/bismuth/blob/master/WID/SettingsPage.xaml"
click node_shared_color "https://github.com/vld-b/bismuth/blob/master/Shared/ColorPickerButton.xaml"
click node_delivery_pkg "https://github.com/vld-b/bismuth/blob/master/WID/Package.appxmanifest"
click node_delivery_assets "https://github.com/vld-b/bismuth/blob/master/WID/Assets/anim_startup.json"
click node_delivery_ci "https://github.com/vld-b/bismuth/blob/master/.github/workflows/dotnet.yml"

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_app_entry,node_app_splash,node_app_main,node_delivery_pkg,node_delivery_assets,node_delivery_ci toneBlue
class node_doc_list,node_doc_page,node_doc_search,node_doc_create,node_doc_thumb,node_doc_model toneAmber
class node_edit_canvas,node_edit_tool,node_edit_manip,node_edit_image,node_edit_text,node_edit_undo toneMint
class node_persist_ops,node_persist_migrate toneRose
class node_settings_model,node_settings_page toneIndigo
class node_shared_color toneTeal
```

## Components

### App Shell

Startup and top-level navigation.

- [App](https://github.com/vld-b/bismuth/blob/master/WID/App.xaml): xaml app · Application entry point and startup wiring. · `WID/App.xaml`
- [Splash](https://github.com/vld-b/bismuth/blob/master/WID/ExtendedSplashScreen.xaml): startup screen · Extended splash experience shown on launch. · `WID/ExtendedSplashScreen.xaml`
- [Main Page](https://github.com/vld-b/bismuth/blob/master/WID/MainPage.xaml): shell host · Primary host that routes into notebooks and settings. · `WID/MainPage.xaml`

### Notebook Domain

Notebook browsing, page previews, and page abstractions.

- [Notebook List](https://github.com/vld-b/bismuth/blob/master/WID/NotebookList.xaml): notebook browser · Notebook browsing and opening surface. · `WID/NotebookList.xaml`
- [Notebook Page](https://github.com/vld-b/bismuth/blob/master/WID/NotebookPage.xaml): notebook view · Notebook page container and page-level UI. · `WID/NotebookPage.xaml`
- [Search Result](https://github.com/vld-b/bismuth/blob/master/WID/NotebookSearchResult.xaml): result view · Notebook search result presentation. · `WID/NotebookSearchResult.xaml`
- [New Notebook](https://github.com/vld-b/bismuth/blob/master/WID/CreateNewNotebookOptions.xaml): creation dialog · Options for creating a notebook. · `WID/CreateNewNotebookOptions.xaml`
- [Page Thumbnail](https://github.com/vld-b/bismuth/blob/master/WID/PageThumbnail.xaml): preview view · Page thumbnail and preview rendering. · `WID/PageThumbnail.xaml`
- [Page Model](https://github.com/vld-b/bismuth/blob/master/WID/IOnPageItem.cs): page abstractions · Common page-item interface and page template pattern. · `WID/IOnPageItem.cs`

### Editing Surface

Canvas, ink tools, page objects, and undo history.

- [Canvas](https://github.com/vld-b/bismuth/blob/master/WID/CanvasPage.xaml): editor surface · Core ink and page-content editing surface. · `WID/CanvasPage.xaml`
- [Ink Tool](https://github.com/vld-b/bismuth/blob/master/WID/CustomInkToolbarTool.xaml): tool control · Custom ink toolbar tool selection and behavior. · `WID/CustomInkToolbarTool.xaml`
- [Ink Manipulator](https://github.com/vld-b/bismuth/blob/master/WID/ManipulateInkRect.xaml): selection control · Rectangle-based manipulation of ink regions. · `WID/ManipulateInkRect.xaml`
- [Page Image](https://github.com/vld-b/bismuth/blob/master/WID/OnPageImage.xaml): page item · Image object placed on a page. · `WID/OnPageImage.xaml`
- [Page Text](https://github.com/vld-b/bismuth/blob/master/WID/OnPageText.xaml): page item · Text object placed on a page. · `WID/OnPageText.xaml`
- [Undo System](https://github.com/vld-b/bismuth/blob/master/WID/UndoRedoSystem.cs): history system · Undo/redo state and edit history records. · `WID/UndoRedoSystem.cs`

### Persistence

File operations and upgrade/migration logic.

- [File Ops](https://github.com/vld-b/bismuth/blob/master/WID/FileConfig.cs): file system layer · Config, queued file operations, and save dialog flow. · `WID/FileConfig.cs`
- [Upgraders](https://github.com/vld-b/bismuth/blob/master/WID/NotebookUpgrader.cs): migration layer · Notebook and settings schema upgrade logic. · `WID/NotebookUpgrader.cs`

### Settings

User configuration model and settings UI.

- [Settings Model](https://github.com/vld-b/bismuth/blob/master/AppSettings/Settings.cs): config model · Strongly-typed application settings state. · `AppSettings/Settings.cs`
- [Settings Page](https://github.com/vld-b/bismuth/blob/master/WID/SettingsPage.xaml): settings UI · User-facing settings screen. · `WID/SettingsPage.xaml`

### Shared Controls

Reusable XAML controls and color helpers.

- [Color Picker](https://github.com/vld-b/bismuth/blob/master/Shared/ColorPickerButton.xaml): shared control · Reusable color selection controls and helpers. · `Shared/ColorPickerButton.xaml`

### Delivery

Packaged app manifest, startup assets, and CI.

- [Package](https://github.com/vld-b/bismuth/blob/master/WID/Package.appxmanifest): appx manifest · Packaged Windows app manifest. · `WID/Package.appxmanifest`
- [Startup Assets](https://github.com/vld-b/bismuth/blob/master/WID/Assets/anim_startup.json): animation assets · Launch animation assets for splash experience. · `WID/Assets/anim_startup.json`
- [CI Build](https://github.com/vld-b/bismuth/blob/master/.github/workflows/dotnet.yml): workflow · GitHub Actions build validation for .NET. · `.github/workflows/dotnet.yml`

## Connections

- App → Splash: launches · App startup opens the splash experience first.
- Splash → Main Page: navigates · Startup transitions into the main shell.
- Main Page → Notebook List: opens · Main shell routes into notebook browsing and opening.
- Main Page → Settings Page: opens · Main shell exposes application settings.
- Notebook List → New Notebook: creates · Notebook browsing includes notebook creation flow.
- Notebook List → Search Result: searches · Notebook UI surfaces search results.
- Notebook List → Page Thumbnail: shows · Notebook/page UI uses page previews.
- Notebook List → Notebook Page: opens · Opening a notebook leads into notebook page views.
- Notebook Page → Canvas: hosts · Notebook pages embed the editing surface.
- Canvas → Ink Tool: selects · Canvas uses ink toolbar tools for editing modes.
- Canvas → Ink Manipulator: manipulates · Canvas uses selection handles for ink regions.
- Canvas → Page Image: hosts · Canvas can place images on a page.
- Canvas → Page Text: hosts · Canvas can place and edit page text.
- Canvas → Undo System: records · Canvas mutations are captured in undo/redo history.
- Page Image → Page Model: implements · Page items share a common page-item abstraction.
- Page Text → Page Model: implements · Page items share a common page-item abstraction.
- Undo System → File Ops: persists · History and document changes eventually flow to file operations.
- File Ops → Upgraders: upgrades · File handling invokes migration for older content or config.
- Settings Page → Settings Model: edits · Settings UI is backed by the typed settings model.
- Settings Model → Upgraders: migrates · Configuration changes are versioned and upgraded.
- Color Picker → Ink Tool: supports · Shared color selection feeds ink/tool workflows.
- Color Picker → Settings Page: supports · Shared color controls can be reused in settings UI.
- Splash → Startup Assets: uses · Splash screen is backed by startup animation assets.
- App → Package: packages · Application is delivered as a packaged Windows app.
- App → CI Build: validated by · Repository includes automated .NET build validation.
