# gaurgle/notez architecture

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

- Interactive diagram: https://gitdiagram.com/gaurgle/notez
- Repository: https://github.com/gaurgle/notez

## Overview

notez is a local-first notes and todo manager exposed through a Rust CLI/TUI, with notez-core providing the shared scope and data model. The main workflow is CLI dispatch into note, tree, search, or todo operations; scope resolution and aggregation determine which vault files are visible, and interactive edits persist locally. The README documents project/global/personal/scratch scopes, project docs, tags, migration, and Git sync. Some command implementations were not excerpted, so their connections are shown only where documented; epoz is a separate repository.

Main entry points: [`crates/notez-cli/src/main.rs`](https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/main.rs) (Command Dispatch), [`crates/notez-core/src/core/aggregate.rs`](https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/core/aggregate.rs) (Note Aggregation), [`crates/notez-cli/src/commands/todo.rs`](https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/commands/todo.rs) (Todo Command), [`crates/notez-cli/src/commands/tree.rs`](https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/commands/tree.rs) (Tree Browser Command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and TUI"]
  node_dispatch["Command Dispatch<br/>[main.rs]"]
  node_cli_surface["CLI Surface<br/>[mod.rs]"]
  node_note_commands["Note Commands<br/>[add.rs]"]
  node_edit_command["Edit and Rename<br/>[edit.rs]"]
  node_tree_command["Tree Browser Command<br/>[tree.rs]"]
  node_tree_tui["Tree Browser TUI<br/>[tree.rs]"]
  node_search_command["Search Command<br/>[search.rs]"]
  node_todo_command["Todo Command<br/>[todo.rs]"]
  node_todo_tui["Todo Board TUI<br/>[todo.rs]"]
end

subgraph group_domain["Scope and Notes"]
  node_scope_model["Scope Model<br/>[scope.rs]"]
  node_scope_resolution["Scope Resolution<br/>[resolve.rs]"]
  node_note_aggregation["Note Aggregation<br/>[aggregate.rs]"]
  node_search_engine["Full-Text Search<br/>[search.rs]"]
end

subgraph group_boards["Todo and Tags"]
  node_todo_model["Todo Board Logic<br/>[mod.rs]"]
  node_todo_tags["Tags and Filters<br/>[tags.rs]"]
end

subgraph group_config["Configuration"]
  node_config["Config and Paths<br/>[mod.rs]"]
  node_registry["Project Registry<br/>[registry.rs]"]
end

subgraph group_operations["Vault Operations"]
  node_vault_sync["Vault Sync<br/>[sync.rs]"]
  node_legacy_migration["Legacy Migration<br/>[migrate.rs]"]
  node_vault_files[("Local Note Vault")]
end

node_user(("CLI User"))
node_git_remote["Git Remote"]

node_user -->|"invokes"| node_dispatch
node_dispatch -->|"parses"| node_cli_surface
node_dispatch -->|"dispatches"| node_note_commands
node_dispatch -->|"dispatches"| node_tree_command
node_dispatch -->|"dispatches"| node_todo_command
node_dispatch -->|"dispatches"| node_edit_command
node_note_commands -->|"writes notes"| node_vault_files
node_edit_command -->|"selects in-scope notes"| node_note_aggregation
node_tree_command -->|"assembles entries"| node_note_aggregation
node_tree_command -->|"opens browser"| node_tree_tui
node_tree_tui -->|"loads tag flags"| node_todo_tags
node_search_command -->|"searches notes"| node_search_engine
node_search_engine -->|"collects entries"| node_note_aggregation
node_search_engine -->|"reads content"| node_vault_files
node_todo_command -->|"assembles board"| node_todo_model
node_todo_command -->|"opens board"| node_todo_tui
node_todo_tui -->|"mutates tasks"| node_todo_model
node_todo_model -->|"uses tag model"| node_todo_tags
node_todo_command -->|"saves edited sources"| node_vault_files
node_note_aggregation -->|"labels entries"| node_scope_model
node_note_aggregation -->|"walks projects"| node_registry
node_note_aggregation -->|"uses configured roots"| node_config
node_scope_resolution -->|"resolves scope"| node_scope_model
node_config -->|"locates vault"| node_vault_files
node_registry -->|"uses config paths"| node_config
node_vault_sync -->|"syncs global vault"| node_vault_files
node_vault_sync -->|"pulls and pushes"| node_git_remote
node_legacy_migration -->|"converts layout"| node_vault_files

click node_dispatch "https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/main.rs"
click node_cli_surface "https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/cli/mod.rs"
click node_note_commands "https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/commands/add.rs"
click node_edit_command "https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/commands/edit.rs"
click node_tree_command "https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/commands/tree.rs"
click node_tree_tui "https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/tui/tree.rs"
click node_search_command "https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/commands/search.rs"
click node_todo_command "https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/commands/todo.rs"
click node_todo_tui "https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/tui/todo.rs"
click node_scope_model "https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/core/scope.rs"
click node_scope_resolution "https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/core/resolve.rs"
click node_note_aggregation "https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/core/aggregate.rs"
click node_search_engine "https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/search.rs"
click node_todo_model "https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/todo/mod.rs"
click node_todo_tags "https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/tags.rs"
click node_config "https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/config/mod.rs"
click node_registry "https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/config/registry.rs"
click node_vault_sync "https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/sync.rs"
click node_legacy_migration "https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/migrate.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_dispatch,node_cli_surface,node_note_commands,node_edit_command,node_tree_command,node_tree_tui,node_search_command,node_todo_command,node_todo_tui,node_user toneBlue
class node_scope_model,node_scope_resolution,node_note_aggregation,node_search_engine toneAmber
class node_todo_model,node_todo_tags toneMint
class node_config,node_registry toneRose
class node_vault_sync,node_legacy_migration,node_vault_files,node_git_remote toneIndigo
```

## Components

### CLI and TUI

- [Command Dispatch](https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/main.rs): `crates/notez-cli/src/main.rs`
- [CLI Surface](https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/cli/mod.rs): `crates/notez-cli/src/cli/mod.rs`
- [Note Commands](https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/commands/add.rs): `crates/notez-cli/src/commands/add.rs`
- [Edit and Rename](https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/commands/edit.rs): `crates/notez-cli/src/commands/edit.rs`
- [Tree Browser Command](https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/commands/tree.rs): `crates/notez-cli/src/commands/tree.rs`
- [Tree Browser TUI](https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/tui/tree.rs): `crates/notez-cli/src/tui/tree.rs`
- [Search Command](https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/commands/search.rs): `crates/notez-cli/src/commands/search.rs`
- [Todo Command](https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/commands/todo.rs): `crates/notez-cli/src/commands/todo.rs`
- [Todo Board TUI](https://github.com/gaurgle/notez/blob/main/crates/notez-cli/src/tui/todo.rs): `crates/notez-cli/src/tui/todo.rs`

### Scope and Notes

- [Scope Model](https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/core/scope.rs): `crates/notez-core/src/core/scope.rs`
- [Scope Resolution](https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/core/resolve.rs): `crates/notez-core/src/core/resolve.rs`
- [Note Aggregation](https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/core/aggregate.rs): `crates/notez-core/src/core/aggregate.rs`
- [Full-Text Search](https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/search.rs): `crates/notez-core/src/search.rs`

### Todo and Tags

- [Todo Board Logic](https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/todo/mod.rs): `crates/notez-core/src/todo/mod.rs`
- [Tags and Filters](https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/tags.rs): `crates/notez-core/src/tags.rs`

### Configuration

- [Config and Paths](https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/config/mod.rs): `crates/notez-core/src/config/mod.rs`
- [Project Registry](https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/config/registry.rs): `crates/notez-core/src/config/registry.rs`

### Vault Operations

- [Vault Sync](https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/sync.rs): `crates/notez-core/src/sync.rs`
- [Legacy Migration](https://github.com/gaurgle/notez/blob/main/crates/notez-core/src/migrate.rs): `crates/notez-core/src/migrate.rs`
- **Local Note Vault**

### Other components

- **CLI User**
- **Git Remote**

## Connections

- CLI User → Command Dispatch: invokes (evidence: `crates/notez-cli/src/main.rs`)
- Command Dispatch → CLI Surface: parses (evidence: `crates/notez-cli/src/main.rs`)
- Command Dispatch → Note Commands: dispatches (evidence: `crates/notez-cli/src/main.rs`)
- Command Dispatch → Tree Browser Command: dispatches (evidence: `crates/notez-cli/src/main.rs`)
- Command Dispatch → Todo Command: dispatches (evidence: `crates/notez-cli/src/main.rs`)
- Command Dispatch → Edit and Rename: dispatches (evidence: `crates/notez-cli/src/main.rs`)
- Note Commands → Local Note Vault: writes notes (evidence: `README.md`)
- Edit and Rename → Note Aggregation: selects in-scope notes (evidence: `README.md`)
- Tree Browser Command → Note Aggregation: assembles entries (evidence: `crates/notez-core/src/core/aggregate.rs`)
- Tree Browser Command → Tree Browser TUI: opens browser (evidence: `crates/notez-cli/src/tui/tree.rs`)
- Tree Browser TUI → Tags and Filters: loads tag flags (evidence: `crates/notez-cli/src/tui/tree.rs`)
- Search Command → Full-Text Search: searches notes (evidence: `README.md`)
- Full-Text Search → Note Aggregation: collects entries (evidence: `crates/notez-core/src/search.rs`)
- Full-Text Search → Local Note Vault: reads content (evidence: `crates/notez-core/src/search.rs`)
- Todo Command → Todo Board Logic: assembles board
- Todo Command → Todo Board TUI: opens board (evidence: `crates/notez-cli/src/tui/todo.rs`)
- Todo Board TUI → Todo Board Logic: mutates tasks (evidence: `crates/notez-cli/src/tui/todo.rs`)
- Todo Board Logic → Tags and Filters: uses tag model (evidence: `crates/notez-core/src/todo/mod.rs`)
- Todo Command → Local Note Vault: saves edited sources (evidence: `README.md`)
- Note Aggregation → Scope Model: labels entries (evidence: `crates/notez-core/src/core/aggregate.rs`)
- Note Aggregation → Project Registry: walks projects (evidence: `crates/notez-core/src/core/aggregate.rs`)
- Note Aggregation → Config and Paths: uses configured roots (evidence: `crates/notez-core/src/core/aggregate.rs`)
- Scope Resolution → Scope Model: resolves scope (evidence: `crates/notez-core/src/core/resolve.rs`)
- Config and Paths → Local Note Vault: locates vault (evidence: `crates/notez-core/src/config/mod.rs`)
- Project Registry → Config and Paths: uses config paths (evidence: `crates/notez-core/src/config/registry.rs`)
- Vault Sync → Local Note Vault: syncs global vault (evidence: `README.md`)
- Vault Sync → Git Remote: pulls and pushes (evidence: `README.md`)
- Legacy Migration → Local Note Vault: converts layout (evidence: `README.md`)
