How flxzt/rnote works
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: pens Pen system · document Document core · fileformats File formats · app App shell
Components 20
UI crate
GTK4 application shell and interactive document workspace
- App shell · Top-level application, window, actions, and global UI wiring
crates/rnote-ui/src/app - Canvas · Canvas widget, input handling, and document-facing rendering hooks
crates/rnote-ui/src/canvas - Panels · Sidebar, pen picker, settings, dialogs, and canvas controls
crates/rnote-ui/src/penssidebar - Workspace · Workspace browser and file operations around local note documents
crates/rnote-ui/src/workspacebrowser - UI 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 · Document structure, layout, background, and configuration state
crates/rnote-engine/src/document - Stroke store · Stroke content, selection, trash, and render/selection components
crates/rnote-engine/src/store - Pen system · Brush, eraser, selector, shaper, typewriter, tools, shortcuts, and configs
crates/rnote-engine/src/pens - Render loop · Rendering, animation, snapshots, visual debug, and task execution
crates/rnote-engine/src/engine - File formats · Native rnote format plus xopp and other import/export adapters
crates/rnote-engine/src/fileformats - Stroke types · Brush, shape, text, bitmap, and vector image stroke representations
crates/rnote-engine/src/strokes - Camera & snap · Camera state, snapping, and selection/collision helpers
crates/rnote-engine/src/camera.rs
Compose crate
Geometry, stroke construction, and styling primitives
- Builders · Builders for lines, arrows, polygons, rectangles, ellipses, bezier curves, and pen paths
crates/rnote-compose/src/builders - Shapes · Editable geometric shape primitives and shape interfaces
crates/rnote-compose/src/shapes - Pen paths · Pen path elements, segments, and path composition
crates/rnote-compose/src/penpath - Style · Smooth, rough, textured, and indicator styling options
crates/rnote-compose/src/style - Transforms · Transformable abstractions and transform utilities
crates/rnote-compose/src/transform
CLI crate
Headless import/export and validation entrypoints
Build & distro
Cargo/Meson packaging, resources, and release automation
- Build system · Cargo, Meson, build scripts, and distro/CI automation
meson.build
Connections 26
- 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