# godanitt/cuadernos architecture

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

- Interactive diagram: https://gitdiagram.com/godanitt/cuadernos
- Repository: https://github.com/godanitt/cuadernos

## Overview

Cuadernos is both an open Typst library of subject notebooks and papers, and a Python manager for discovering, validating, compiling, and cataloging them. The main workflow is an editor or maintainer invoking the CLI: it discovers document metadata, validates selected sources, compiles them with Tinymist, and synchronizes catalog and paper outputs. The graph also preserves migration and source parsing as supporting capabilities. Some module relationships are evidenced by the source index rather than sampled call sites; unsampled implementation details are not inferred.

Main entry points: [`src/cuadernos_manager/cli.py`](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/cli.py) (CLI commands), [`src/cuadernos_manager/project.py`](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/project.py) (Project discovery), [`src/cuadernos_manager/build.py`](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/build.py) (Incremental build), [`src/cuadernos_manager/paper.py`](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/paper.py) (Paper model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command workflow"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_migration["Name migration<br/>[migrate.py]"]
end

subgraph group_documents["Document model"]
  node_discovery["Project discovery<br/>[project.py]"]
  node_notebook["Notebook model<br/>[models.py]"]
  node_paper["Paper model<br/>[paper.py]"]
  node_metadata["Metadata reader<br/>[metadata.py]"]
  node_settings["Project settings<br/>[settings.py]"]
  node_parser["Typst parser<br/>[parser.py]"]
  node_typst_sources["Notebook and paper sources"]
end

subgraph group_processing["Build and quality"]
  node_validator["Document validation<br/>[validate.py]"]
  node_builder["Incremental build<br/>[build.py]"]
  node_tinymist["Tinymist CLI"]
end

subgraph group_outputs["Catalog and outputs"]
  node_generator["Catalog generation<br/>[generate.py]"]
  node_paper_output["Paper output sync<br/>[paper.py]"]
  node_pdf_outputs["Compiled PDFs"]
  node_catalog["Generated catalog<br/>[README.md]"]
  node_paper_pdfs["Paper PDFs"]
end

node_maintainer(("Maintainer"))

node_maintainer -->|"invokes"| node_cli
node_cli -->|"discovers"| node_discovery
node_cli -->|"normalizes names"| node_migration
node_discovery -->|"scans sources"| node_typst_sources
node_discovery -->|"loads notebooks"| node_notebook
node_discovery -->|"loads papers"| node_paper
node_notebook -->|"reads metadata"| node_metadata
node_notebook -->|"loads settings"| node_settings
node_paper -->|"reads metadata"| node_metadata
node_paper -->|"loads settings"| node_settings
node_cli -->|"validates"| node_validator
node_validator -->|"parses sources"| node_parser
node_validator -->|"checks metadata"| node_metadata
node_cli -->|"builds documents"| node_builder
node_builder -->|"runs compiler"| node_tinymist
node_builder -.->|"writes notebooks"| node_pdf_outputs
node_builder -.->|"writes papers"| node_paper_pdfs
node_cli -->|"syncs catalog"| node_generator
node_generator -->|"parses content"| node_parser
node_cli -->|"syncs paper index"| node_paper_output
node_paper_output -->|"lists outputs"| node_paper_pdfs
node_generator -.->|"writes catalog"| node_catalog
node_cli -->|"selects papers"| node_paper
node_migration -->|"reads metadata"| node_metadata
node_migration -->|"loads settings"| node_settings

click node_cli "https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/cli.py"
click node_migration "https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/migrate.py"
click node_discovery "https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/project.py"
click node_notebook "https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/models.py"
click node_paper "https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/paper.py"
click node_metadata "https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/metadata.py"
click node_settings "https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/settings.py"
click node_parser "https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/parser.py"
click node_validator "https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/validate.py"
click node_builder "https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/build.py"
click node_generator "https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/generate.py"
click node_paper_output "https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/paper.py"
click node_typst_sources "https://github.com/godanitt/cuadernos/tree/main/cuadernos"
click node_pdf_outputs "https://github.com/godanitt/cuadernos/tree/main/pdf"
click node_catalog "https://github.com/godanitt/cuadernos/blob/main/README.md"
click node_paper_pdfs "https://github.com/godanitt/cuadernos/tree/main/paper"

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_migration toneBlue
class node_discovery,node_notebook,node_paper,node_metadata,node_settings,node_parser,node_typst_sources toneAmber
class node_validator,node_builder,node_tinymist toneMint
class node_generator,node_paper_output,node_pdf_outputs,node_catalog,node_paper_pdfs toneRose
class node_maintainer toneIndigo
```

## Components

### Command workflow

- [CLI commands](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/cli.py): `src/cuadernos_manager/cli.py`
- [Name migration](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/migrate.py): `src/cuadernos_manager/migrate.py`

### Document model

- [Project discovery](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/project.py): `src/cuadernos_manager/project.py`
- [Notebook model](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/models.py): `src/cuadernos_manager/models.py`
- [Paper model](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/paper.py): `src/cuadernos_manager/paper.py`
- [Metadata reader](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/metadata.py): `src/cuadernos_manager/metadata.py`
- [Project settings](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/settings.py): `src/cuadernos_manager/settings.py`
- [Typst parser](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/parser.py): `src/cuadernos_manager/parser.py`
- [Notebook and paper sources](https://github.com/godanitt/cuadernos/tree/main/cuadernos): `cuadernos`

### Build and quality

- [Document validation](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/validate.py): `src/cuadernos_manager/validate.py`
- [Incremental build](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/build.py): `src/cuadernos_manager/build.py`
- **Tinymist CLI**

### Catalog and outputs

- [Catalog generation](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/generate.py): `src/cuadernos_manager/generate.py`
- [Paper output sync](https://github.com/godanitt/cuadernos/blob/main/src/cuadernos_manager/paper.py): `src/cuadernos_manager/paper.py`
- [Compiled PDFs](https://github.com/godanitt/cuadernos/tree/main/pdf): `pdf`
- [Generated catalog](https://github.com/godanitt/cuadernos/blob/main/README.md): `README.md`
- [Paper PDFs](https://github.com/godanitt/cuadernos/tree/main/paper): `paper`

### Other components

- **Maintainer**

## Connections

- Maintainer → CLI commands: invokes (evidence: `README.md`)
- CLI commands → Project discovery: discovers (evidence: `src/cuadernos_manager/cli.py`)
- CLI commands → Name migration: normalizes names (evidence: `src/cuadernos_manager/cli.py`)
- Project discovery → Notebook and paper sources: scans sources (evidence: `src/cuadernos_manager/project.py`)
- Project discovery → Notebook model: loads notebooks (evidence: `src/cuadernos_manager/project.py`)
- Project discovery → Paper model: loads papers (evidence: `src/cuadernos_manager/project.py`)
- Notebook model → Metadata reader: reads metadata (evidence: `src/cuadernos_manager/models.py`)
- Notebook model → Project settings: loads settings (evidence: `src/cuadernos_manager/models.py`)
- Paper model → Metadata reader: reads metadata (evidence: `src/cuadernos_manager/paper.py`)
- Paper model → Project settings: loads settings (evidence: `src/cuadernos_manager/paper.py`)
- CLI commands → Document validation: validates (evidence: `src/cuadernos_manager/cli.py`)
- Document validation → Typst parser: parses sources (evidence: `src/cuadernos_manager/validate.py`)
- Document validation → Metadata reader: checks metadata (evidence: `src/cuadernos_manager/validate.py`)
- CLI commands → Incremental build: builds documents (evidence: `src/cuadernos_manager/cli.py`)
- Incremental build → Tinymist CLI: runs compiler (evidence: `src/cuadernos_manager/build.py`)
- Incremental build → Compiled PDFs: writes notebooks
- Incremental build → Paper PDFs: writes papers
- CLI commands → Catalog generation: syncs catalog (evidence: `src/cuadernos_manager/cli.py`)
- Catalog generation → Typst parser: parses content (evidence: `src/cuadernos_manager/generate.py`)
- CLI commands → Paper output sync: syncs paper index (evidence: `src/cuadernos_manager/cli.py`)
- Paper output sync → Paper PDFs: lists outputs (evidence: `src/cuadernos_manager/paper.py`)
- Catalog generation → Generated catalog: writes catalog
- CLI commands → Paper model: selects papers (evidence: `src/cuadernos_manager/cli.py`)
- Name migration → Metadata reader: reads metadata (evidence: `src/cuadernos_manager/migrate.py`)
- Name migration → Project settings: loads settings (evidence: `src/cuadernos_manager/migrate.py`)
