# flxzt/rnote architecture

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

- Interactive diagram: https://gitdiagram.com/flxzt/rnote
- Repository: https://github.com/flxzt/rnote
- Video tour (about a minute): https://gitdiagram.com/flxzt/rnote/video

## Overview

1. **Top-level shape of the repo**
   Rnote is a Rust desktop application split into three primary crates: `rnote-ui` for the GTK4 interface, `rnote-engine` for document/state/rendering logic, and `rnote-compose` for geometry and stroke construction. A separate `rnote-cli` crate exposes non-interactive file handling for automation.

2. **Main runtime boundary**
   The GTK4 UI is the outer shell. It owns windows, widgets, dialogs, actions, and user interaction, but it delegates document editing, rendering, import/export, and pen behavior to the engine layer. This separation is important: the UI is not the source of truth for document content.

3. **Core document and canvas flow**
   Input enters through the canvas and pen/tool handlers in `rnote-ui`, is translated into pen events and commands, and then processed by `rnote-engine` and `rnote-compose`. The engine maintains the document model, stroke store, selection state, camera, snapshots, and rendering state. Rendering comes back out through the engine to the canvas widget.

4. **Composition subsystem**
   `rnote-compose` is the geometry and shape-building layer. It contains builders for lines, arrows, rectangles, ellipses, polygons, bezier curves, coordinate systems, and pen paths. It also includes styling systems such as smooth, rough, and textured rendering options. This crate is where raw input points become editable shapes and stroke content.

5. **Engine responsibilities**
   `rnote-engine` is the central application core. It manages document structure, layout, background/configuration, stroke content, selection/collision logic, snapping, camera control, animations, visual debug, and task execution. It also owns the state needed for pen modes such as brush, eraser, selector, shaper, typewriter, and tool behaviors like zoom or laser.

6. **Persistence and file formats**
   The native `.rnote` format is handled by the engine’s file-format modules and is described in the README as gzipped JSON. The engine also supports older `.rnote` revisions through versioned format modules, plus import/export paths for other formats such as Xournal++ (`xopp`), SVG, PDF, and image formats. This makes serialization a distinct boundary from editing/rendering.

7. **Export and import pipeline**
   Export and import are split across the engine and UI. The UI presents dialogs and actions, while the engine performs the actual transformation between document state and external formats. The CLI reuses these capabilities for batch processing, so file conversion is not tied to the GUI.

8. **UI structure**
   `rnote-ui` is organized around the application window, canvas, sidebar, pen picker, dialogs, settings panel, workspace browser, and assorted custom GTK widgets. The many `.ui` files and resource definitions indicate a declarative GTK resource setup, while the Rust modules implement behavior and binding to engine functionality.

9. **Workspace/file-management features**
   The workspace browser is a distinct UI subsystem for navigating local files and related documents. It supports operations like open, duplicate, rename, trash, create folder, and open in default app. This is a filesystem-facing layer separate from the document editor itself.

10. **CLI and automation**
   `rnote-cli` provides headless operations such as create, import, export, thumbnails, validation, and tests around file handling. It is architecturally important because it exposes the same document/file stack outside the GUI, which implies the core logic is reusable and not UI-coupled.

11. **Input and interaction model**
   The application is built for stylus-first interaction, with pressure-sensitive brushes, configurable shortcuts, drag-and-drop, clipboard support, and tablet-specific behaviors. Those concerns are distributed between the UI input layer and engine pen handlers, with pen configuration living in the engine and UI controls exposed in the sidebar/settings panels.

12. **Build and packaging boundary**
   The repo uses Rust/Cargo for the crates and Meson for desktop integration, resources, translations, and packaging. The `build-aux` and GitHub workflow files show distribution support for desktop targets, Flatpak-like deployment, Windows packaging, and translation updates. These affect how the app is assembled and shipped, but not the core runtime flow.

Main entry points: [`crates/rnote-engine/src/pens`](https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/pens) (Pen system), [`crates/rnote-engine/src/document`](https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/document) (Document core), [`crates/rnote-engine/src/fileformats`](https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/fileformats) (File formats), [`crates/rnote-ui/src/app`](https://github.com/flxzt/rnote/tree/main/crates/rnote-ui/src/app) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_ui["UI crate"]
  node_node_ui_app["App shell<br/>GTK4 app"]
  node_node_ui_canvas["Canvas<br/>interaction layer"]
  node_node_ui_panels["Panels<br/>tool UI"]
  node_node_ui_workspace["Workspace<br/>file browser"]
  node_node_ui_resources["UI resources<br/>GTK resources"]
end

subgraph group_grp_engine["Engine crate"]
  node_node_engine_doc["Document core<br/>doc model"]
  node_node_engine_store[("Stroke store<br/>state store")]
  node_node_engine_pens["Pen system<br/>input modes"]
  node_node_engine_render["Render loop<br/>engine loop"]
  node_node_engine_formats["File formats<br/>serialization"]
  node_node_engine_strokes["Stroke types<br/>stroke model"]
  node_node_engine_camera(("Camera & snap<br/>view control<br/>[camera.rs]"))
end

subgraph group_grp_compose["Compose crate"]
  node_node_compose_builders["Builders"]
  node_node_compose_shapes["Shapes<br/>geometry"]
  node_node_compose_path["Pen paths<br/>path geometry"]
  node_node_compose_style["Style"]
  node_node_compose_transform["Transforms<br/>geometry ops"]
end

subgraph group_grp_cli["CLI crate"]
  node_node_cli_main["CLI<br/>headless app<br/>[main.rs]"]
  node_node_cli_ops["CLI ops<br/>batch actions"]
end

subgraph group_grp_build["Build & distro"]
  node_node_build["Build system<br/>packaging<br/>[meson.build]"]
end

node_node_ui_app -->|"hosts"| node_node_ui_canvas
node_node_ui_app -->|"wires"| node_node_ui_panels
node_node_ui_app -->|"delegates"| node_node_engine_doc
node_node_ui_canvas -->|"renders via"| node_node_engine_render
node_node_ui_canvas -->|"sends input to"| node_node_engine_pens
node_node_ui_panels -->|"configures"| node_node_engine_pens
node_node_ui_workspace -->|"opens files"| node_node_engine_formats
node_node_ui_resources -.->|"feeds"| node_node_ui_app
node_node_engine_pens -->|"creates"| node_node_compose_builders
node_node_engine_pens -->|"produces"| node_node_compose_path
node_node_engine_pens -->|"commits"| node_node_engine_strokes
node_node_engine_doc -->|"owns"| node_node_engine_store
node_node_engine_doc -->|"tracks"| node_node_engine_camera
node_node_engine_render -->|"reads"| node_node_engine_store
node_node_engine_render -->|"draws"| node_node_engine_strokes
node_node_engine_formats -->|"serializes"| node_node_engine_doc
node_node_engine_formats -->|"encodes"| node_node_engine_strokes
node_node_compose_builders -->|"builds"| node_node_compose_shapes
node_node_compose_builders -->|"applies"| node_node_compose_style
node_node_compose_path -->|"uses"| node_node_compose_transform
node_node_cli_main -->|"dispatches"| node_node_cli_ops
node_node_cli_ops -->|"reuses"| node_node_engine_formats
node_node_cli_ops -->|"loads"| node_node_engine_doc
node_node_build -.->|"packages"| node_node_ui_resources
node_node_build -.->|"builds"| node_node_cli_main
node_node_build -.->|"ships"| node_node_engine_formats

click node_node_ui_app "https://github.com/flxzt/rnote/tree/main/crates/rnote-ui/src/app"
click node_node_ui_canvas "https://github.com/flxzt/rnote/tree/main/crates/rnote-ui/src/canvas"
click node_node_ui_panels "https://github.com/flxzt/rnote/tree/main/crates/rnote-ui/src/penssidebar"
click node_node_ui_workspace "https://github.com/flxzt/rnote/tree/main/crates/rnote-ui/src/workspacebrowser"
click node_node_ui_resources "https://github.com/flxzt/rnote/tree/main/crates/rnote-ui/data"
click node_node_engine_doc "https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/document"
click node_node_engine_store "https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/store"
click node_node_engine_pens "https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/pens"
click node_node_engine_render "https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/engine"
click node_node_engine_formats "https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/fileformats"
click node_node_engine_strokes "https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/strokes"
click node_node_engine_camera "https://github.com/flxzt/rnote/blob/main/crates/rnote-engine/src/camera.rs"
click node_node_compose_builders "https://github.com/flxzt/rnote/tree/main/crates/rnote-compose/src/builders"
click node_node_compose_shapes "https://github.com/flxzt/rnote/tree/main/crates/rnote-compose/src/shapes"
click node_node_compose_path "https://github.com/flxzt/rnote/tree/main/crates/rnote-compose/src/penpath"
click node_node_compose_style "https://github.com/flxzt/rnote/tree/main/crates/rnote-compose/src/style"
click node_node_compose_transform "https://github.com/flxzt/rnote/tree/main/crates/rnote-compose/src/transform"
click node_node_cli_main "https://github.com/flxzt/rnote/blob/main/crates/rnote-cli/src/main.rs"
click node_node_cli_ops "https://github.com/flxzt/rnote/tree/main/crates/rnote-cli/src"
click node_node_build "https://github.com/flxzt/rnote/blob/main/meson.build"

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_node_ui_app,node_node_ui_canvas,node_node_ui_panels,node_node_ui_workspace,node_node_ui_resources toneBlue
class node_node_engine_doc,node_node_engine_store,node_node_engine_pens,node_node_engine_render,node_node_engine_formats,node_node_engine_strokes,node_node_engine_camera toneAmber
class node_node_compose_builders,node_node_compose_shapes,node_node_compose_path,node_node_compose_style,node_node_compose_transform toneMint
class node_node_cli_main,node_node_cli_ops toneRose
class node_node_build toneIndigo
```

## Components

### UI crate

GTK4 application shell and interactive document workspace

- [App shell](https://github.com/flxzt/rnote/tree/main/crates/rnote-ui/src/app): GTK4 app · Top-level application, window, actions, and global UI wiring · `crates/rnote-ui/src/app`
- [Canvas](https://github.com/flxzt/rnote/tree/main/crates/rnote-ui/src/canvas): interaction layer · Canvas widget, input handling, and document-facing rendering hooks · `crates/rnote-ui/src/canvas`
- [Panels](https://github.com/flxzt/rnote/tree/main/crates/rnote-ui/src/penssidebar): tool UI · Sidebar, pen picker, settings, dialogs, and canvas controls · `crates/rnote-ui/src/penssidebar`
- [Workspace](https://github.com/flxzt/rnote/tree/main/crates/rnote-ui/src/workspacebrowser): file browser · Workspace browser and file operations around local note documents · `crates/rnote-ui/src/workspacebrowser`
- [UI resources](https://github.com/flxzt/rnote/tree/main/crates/rnote-ui/data): GTK resources · Declarative .ui files, icons, schema, thumbnailer, and translations · `crates/rnote-ui/data`

### Engine crate

Document model, rendering, pens, storage, and file formats

- [Document core](https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/document): doc model · Document structure, layout, background, and configuration state · `crates/rnote-engine/src/document`
- [Stroke store](https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/store): state store · Stroke content, selection, trash, and render/selection components · `crates/rnote-engine/src/store`
- [Pen system](https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/pens): input modes · Brush, eraser, selector, shaper, typewriter, tools, shortcuts, and configs · `crates/rnote-engine/src/pens`
- [Render loop](https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/engine): engine loop · Rendering, animation, snapshots, visual debug, and task execution · `crates/rnote-engine/src/engine`
- [File formats](https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/fileformats): serialization · Native rnote format plus xopp and other import/export adapters · `crates/rnote-engine/src/fileformats`
- [Stroke types](https://github.com/flxzt/rnote/tree/main/crates/rnote-engine/src/strokes): stroke model · Brush, shape, text, bitmap, and vector image stroke representations · `crates/rnote-engine/src/strokes`
- [Camera & snap](https://github.com/flxzt/rnote/blob/main/crates/rnote-engine/src/camera.rs): view control · Camera state, snapping, and selection/collision helpers · `crates/rnote-engine/src/camera.rs`

### Compose crate

Geometry, stroke construction, and styling primitives

- [Builders](https://github.com/flxzt/rnote/tree/main/crates/rnote-compose/src/builders): shape builders · Builders for lines, arrows, polygons, rectangles, ellipses, bezier curves, and pen paths · `crates/rnote-compose/src/builders`
- [Shapes](https://github.com/flxzt/rnote/tree/main/crates/rnote-compose/src/shapes): geometry · Editable geometric shape primitives and shape interfaces · `crates/rnote-compose/src/shapes`
- [Pen paths](https://github.com/flxzt/rnote/tree/main/crates/rnote-compose/src/penpath): path geometry · Pen path elements, segments, and path composition · `crates/rnote-compose/src/penpath`
- [Style](https://github.com/flxzt/rnote/tree/main/crates/rnote-compose/src/style): render style · Smooth, rough, textured, and indicator styling options · `crates/rnote-compose/src/style`
- [Transforms](https://github.com/flxzt/rnote/tree/main/crates/rnote-compose/src/transform): geometry ops · Transformable abstractions and transform utilities · `crates/rnote-compose/src/transform`

### CLI crate

Headless import/export and validation entrypoints

- [CLI](https://github.com/flxzt/rnote/blob/main/crates/rnote-cli/src/main.rs): headless app · Command-line entrypoint and orchestration for batch operations · `crates/rnote-cli/src/main.rs`
- [CLI ops](https://github.com/flxzt/rnote/tree/main/crates/rnote-cli/src): batch actions · Create, import, export, thumbnail, validation, and test helpers · `crates/rnote-cli/src`

### Build & distro

Cargo/Meson packaging, resources, and release automation

- [Build system](https://github.com/flxzt/rnote/blob/main/meson.build): packaging · Cargo, Meson, build scripts, and distro/CI automation · `meson.build`

## Connections

- App shell → Canvas: hosts · Application window drives the canvas workspace
- App shell → Panels: wires · Application shell connects dialogs, sidebar, and tool controls
- App shell → Document core: delegates · UI forwards document operations to the engine
- Canvas → Render loop: renders via · Canvas displays engine output and rendering state
- Canvas → Pen system: sends input to · Pointer and stylus input become pen events and commands
- Panels → Pen system: configures · UI panels edit pen modes, tools, and shortcuts
- Workspace → File formats: opens files · Workspace file actions rely on document serialization and import/export
- UI resources → App shell: feeds · Declarative UI resources and translations back the application shell
- Pen system → Builders: creates · Pen modes and shapers assemble geometry from input points
- Pen system → Pen paths: produces · Freehand input is turned into pen paths
- Pen system → Stroke types: commits · Pen behaviors create and modify stroke content
- Document core → Stroke store: owns · Document state includes stored strokes, selection, and trash
- Document core → Camera & snap: tracks · Document view state includes camera and snapping context
- Render loop → Stroke store: reads · Rendering consumes stored document content and selection state
- Render loop → Stroke types: draws · Stroke representations are rendered for the canvas
- File formats → Document core: serializes · File formats convert document state to and from disk
- File formats → Stroke types: encodes · Persistence preserves stroke content and related assets
- Builders → Shapes: builds · Builders output editable geometric shapes
- Builders → Style: applies · Shape construction includes style and indicator selection
- Pen paths → Transforms: uses · Path geometry relies on transformable operations
- CLI → CLI ops: dispatches · CLI entrypoint routes subcommands to batch operations
- CLI ops → File formats: reuses · Headless commands reuse the same import/export stack as the GUI
- CLI ops → Document core: loads · Batch commands work on document state without the UI
- Build system → UI resources: packages · Build and packaging system installs resources, icons, schemas, and translations
- Build system → CLI: builds · Packaging and CI cover the CLI binary as well as the desktop app
- Build system → File formats: ships · Release tooling includes file-format compatibility and test assets
