# agustinvalencia/cuaderno architecture

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

- Interactive diagram: https://gitdiagram.com/agustinvalencia/cuaderno
- Repository: https://github.com/agustinvalencia/cuaderno

## Overview

Cuaderno is a local-first vault manager for the Research Logbook Method: Markdown and Typst notes are the source of truth, while SQLite is a rebuildable index. The main user workflow starts in the CLI or through an MCP client, invokes domain operations for capture, projects, actions, commitments, and orientation, then reads or updates vault files. The domain crate sits between both interfaces and the reusable core. Major supporting capabilities include templates, validation, search, and file watching. Relationships between crates follow the README; unsampled implementation details are represented only where documented.

Main entry points: [`crates/cdno-domain/src/vault/mod.rs`](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/mod.rs) (Vault API), [`crates/cdno-core/src/index.rs`](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/index.rs) (SQLite index), [`crates/cdno-core/src/store.rs`](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/store.rs) (Vault file access), [`crates/cdno-core/src/transaction.rs`](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/transaction.rs) (Atomic updates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI commands"]
  node_cli_entry["CLI entry<br/>[main.rs]"]
  node_mcp_server["MCP server<br/>[server.rs]"]
  node_mcp_ops["MCP operations<br/>[operations.rs]"]
end

subgraph group_domain["Logbook Domain"]
  node_vault_api["Vault API<br/>[mod.rs]"]
  node_projects["Projects and actions<br/>[actions.rs]"]
  node_context["Context queries<br/>[context.rs]"]
  node_commitments["Commitments<br/>[commitments.rs]"]
  node_log_capture["Log and capture<br/>[log.rs]"]
  node_templates["Templates<br/>[templating.rs]"]
  node_validation["Note rules<br/>[lint.rs]"]
  node_search["Vault search<br/>[search.rs]"]
end

subgraph group_vault["Vault Infrastructure"]
  node_core_store["Vault file access<br/>[store.rs]"]
  node_transactions["Atomic updates<br/>[transaction.rs]"]
  node_index[("SQLite index<br/>[index.rs]")]
  node_extractors["Note extraction<br/>[extractors.rs]"]
  node_watcher["File watching<br/>[watcher.rs]"]
end

subgraph group_formats["Note Formats"]
  node_note_types["Note types<br/>[note_type.rs]"]
  node_frontmatter["Structured metadata<br/>[mod.rs]"]
  node_typst["Typst support<br/>[mod.rs]"]
end

node_person(("Vault user"))
node_agent(("MCP client"))

node_person -->|"runs"| node_cli_entry
node_cli_entry -.->|"dispatches"| node_cli
node_cli -->|"invokes domain"| node_vault_api
node_agent -->|"sends MCP tools"| node_mcp_server
node_mcp_server -->|"dispatches tools"| node_mcp_ops
node_mcp_ops -->|"invokes domain"| node_vault_api
node_vault_api -->|"uses store"| node_core_store
node_vault_api -->|"uses index"| node_index
node_vault_api -.->|"exposes operations"| node_projects
node_vault_api -.->|"exposes queries"| node_context
node_vault_api -.->|"exposes queries"| node_commitments
node_vault_api -.->|"exposes operations"| node_log_capture
node_vault_api -.->|"exposes operations"| node_templates
node_vault_api -.->|"exposes rules"| node_validation
node_vault_api -.->|"exposes queries"| node_search
node_projects -.->|"stages updates"| node_transactions
node_core_store -->|"used by"| node_transactions
node_transactions -->|"updates index"| node_index
node_index -->|"uses extraction"| node_extractors
node_watcher -.->|"keeps current"| node_index
node_templates -->|"uses type rules"| node_note_types
node_validation -.->|"validates metadata"| node_frontmatter
node_core_store -.->|"handles notes"| node_typst

click node_cli "https://github.com/agustinvalencia/cuaderno/tree/main/crates/cdno-cli/src/commands"
click node_cli_entry "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-cli/src/main.rs"
click node_mcp_server "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-mcp/src/server.rs"
click node_mcp_ops "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-mcp/src/operations.rs"
click node_vault_api "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/mod.rs"
click node_projects "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/projects/actions.rs"
click node_context "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/context.rs"
click node_commitments "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/commitments.rs"
click node_log_capture "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/log.rs"
click node_templates "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/templating.rs"
click node_validation "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/lint.rs"
click node_core_store "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/store.rs"
click node_transactions "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/transaction.rs"
click node_index "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/index.rs"
click node_extractors "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/extractors.rs"
click node_watcher "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/watcher.rs"
click node_note_types "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/note_type.rs"
click node_frontmatter "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/frontmatter/mod.rs"
click node_typst "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/typst/mod.rs"
click node_search "https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/search.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_cli,node_cli_entry,node_mcp_server,node_mcp_ops,node_person,node_agent toneBlue
class node_vault_api,node_projects,node_context,node_commitments,node_log_capture,node_templates,node_validation,node_search toneAmber
class node_core_store,node_transactions,node_index,node_extractors,node_watcher toneMint
class node_note_types,node_frontmatter,node_typst toneRose
```

## Components

### User Interfaces

- [CLI commands](https://github.com/agustinvalencia/cuaderno/tree/main/crates/cdno-cli/src/commands): `crates/cdno-cli/src/commands`
- [CLI entry](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-cli/src/main.rs): `crates/cdno-cli/src/main.rs`
- [MCP server](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-mcp/src/server.rs): `crates/cdno-mcp/src/server.rs`
- [MCP operations](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-mcp/src/operations.rs): `crates/cdno-mcp/src/operations.rs`

### Logbook Domain

- [Vault API](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/mod.rs): `crates/cdno-domain/src/vault/mod.rs`
- [Projects and actions](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/projects/actions.rs): `crates/cdno-domain/src/vault/projects/actions.rs`
- [Context queries](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/context.rs): `crates/cdno-domain/src/vault/context.rs`
- [Commitments](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/commitments.rs): `crates/cdno-domain/src/vault/commitments.rs`
- [Log and capture](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/log.rs): `crates/cdno-domain/src/vault/log.rs`
- [Templates](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/templating.rs): `crates/cdno-domain/src/vault/templating.rs`
- [Note rules](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/lint.rs): `crates/cdno-domain/src/lint.rs`
- [Vault search](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/vault/search.rs): `crates/cdno-domain/src/vault/search.rs`

### Vault Infrastructure

- [Vault file access](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/store.rs): `crates/cdno-core/src/store.rs`
- [Atomic updates](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/transaction.rs): `crates/cdno-core/src/transaction.rs`
- [SQLite index](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/index.rs): `crates/cdno-core/src/index.rs`
- [Note extraction](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/extractors.rs): `crates/cdno-core/src/extractors.rs`
- [File watching](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/watcher.rs): `crates/cdno-core/src/watcher.rs`

### Note Formats

- [Note types](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/note_type.rs): `crates/cdno-domain/src/note_type.rs`
- [Structured metadata](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-domain/src/frontmatter/mod.rs): `crates/cdno-domain/src/frontmatter/mod.rs`
- [Typst support](https://github.com/agustinvalencia/cuaderno/blob/main/crates/cdno-core/src/typst/mod.rs): `crates/cdno-core/src/typst/mod.rs`

### Other components

- **Vault user**
- **MCP client**

## Connections

- Vault user → CLI entry: runs
- CLI entry → CLI commands: dispatches
- CLI commands → Vault API: invokes domain
- MCP client → MCP server: sends MCP tools
- MCP server → MCP operations: dispatches tools (evidence: `crates/cdno-mcp/src/server.rs`)
- MCP operations → Vault API: invokes domain
- Vault API → Vault file access: uses store (evidence: `crates/cdno-domain/src/vault/mod.rs`)
- Vault API → SQLite index: uses index (evidence: `crates/cdno-domain/src/vault/mod.rs`)
- Vault API → Projects and actions: exposes operations (evidence: `crates/cdno-domain/src/vault/projects/actions.rs`)
- Vault API → Context queries: exposes queries (evidence: `crates/cdno-domain/src/vault/mod.rs`)
- Vault API → Commitments: exposes queries (evidence: `crates/cdno-domain/src/vault/mod.rs`)
- Vault API → Log and capture: exposes operations (evidence: `crates/cdno-domain/src/vault/mod.rs`)
- Vault API → Templates: exposes operations (evidence: `crates/cdno-domain/src/vault/templating.rs`)
- Vault API → Note rules: exposes rules
- Vault API → Vault search: exposes queries (evidence: `crates/cdno-domain/src/vault/mod.rs`)
- Projects and actions → Atomic updates: stages updates
- Vault file access → Atomic updates: used by (evidence: `crates/cdno-core/src/transaction.rs`)
- Atomic updates → SQLite index: updates index (evidence: `crates/cdno-core/src/transaction.rs`)
- SQLite index → Note extraction: uses extraction (evidence: `crates/cdno-core/src/index.rs`)
- File watching → SQLite index: keeps current
- Templates → Note types: uses type rules (evidence: `crates/cdno-domain/src/vault/templating.rs`)
- Note rules → Structured metadata: validates metadata
- Vault file access → Typst support: handles notes