# iamshrisawant/digi-notes architecture

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

- Interactive diagram: https://gitdiagram.com/iamshrisawant/digi-notes
- Repository: https://github.com/iamshrisawant/digi-notes

## Overview

#### Purpose and Entry Points
DigiNotes is a native PySide6 desktop sticky-notes manager. It runs primarily from the system tray, maintains multiple frameless desktop note windows, and persists note text and layout locally. Launchers are `run.sh` and `run.bat`; application startup and process ownership begin in `src/main.py`.

#### Application Bootstrap and Lifetime Management
`src/main.py` creates the Qt application, enforces a single running instance with `QLockFile`, initializes tray actions, and owns note lifecycle through its `NoteManager`. This is the top-level control boundary: tray/dashboard actions create, show, hide, or remove note windows rather than a server or browser route handling them.

Paths: `src/main.py`, `run.sh`, `run.bat`

#### Sticky Note Window Layer
Each desktop note is a custom borderless Qt window implemented by `StickyNote`. It manages title-bar interactions, drag positioning, pin/stays-on-top behavior, collapse-to-indicator behavior, opacity/hover presentation, and coordination with formatting help. It is the boundary between persisted note state and OS window-management APIs.

Paths: `src/note_window.py`, `src/styles.py`

#### Markdown Editing and Interaction Engine
The embedded editor is a `QTextEdit` subclass with a custom syntax highlighter. It transforms Markdown input into in-place rich styling, hides or reveals syntax according to cursor context, continues lists on Enter, and handles click-driven checkbox state changes. Note text remains Markdown rather than being converted into a separate document format.

Paths: `src/editor.py`, `src/note_window.py`

#### Dashboard Control Plane
The centralized dashboard lists active notes and provides search, creation, visibility toggling, deletion, and drag-and-drop activation. It operates as a management surface over the note instances owned by the main manager, rather than storing an independent note model.

Paths: `src/dashboard.py`, `src/main.py`

#### Settings, Themes, and Runtime Overrides
The settings dialog controls application defaults and live per-note layout/theme overrides. Styling is centralized as Qt stylesheet/theme definitions, including glassmorphic colors and hover-transparency behavior; note windows consume these presentation settings.

Paths: `src/settings.py`, `src/styles.py`, `src/note_window.py`

#### Persistence and System Integration
Persistence is local filesystem storage: note bodies are standard Markdown under `data/notes/<id>.md`; corresponding JSON metadata stores geometry and appearance; general settings reside in `data/config.json` (created at runtime, not present in the tree). No backend service or remote datastore is indicated. `AutostartManager` bridges platform startup mechanisms: Linux desktop entries, Windows Registry, and macOS launch agents.

Paths: `src/autostart.py`, `src/main.py`, `src/settings.py`

#### Runtime and Platform Boundaries
The runtime is Python with Qt 6 via `PySide6-Essentials`; `markdown-it-py` is an installed dependency. The application depends on OS tray and windowing facilities. On Linux, `run.sh` forces Qt’s XCB backend to preserve coordinate and always-on-top behavior that Wayland may restrict.

Paths: `requirements.txt`, `run.sh`, `src/main.py`

Main entry points: [`src/note_window.py`](https://github.com/iamshrisawant/digi-notes/blob/main/src/note_window.py) (Sticky note window), [`src/main.py`](https://github.com/iamshrisawant/digi-notes/blob/main/src/main.py) (Application manager), [`src/settings.py`](https://github.com/iamshrisawant/digi-notes/blob/main/src/settings.py) (Settings dialog), [`src/autostart.py`](https://github.com/iamshrisawant/digi-notes/blob/main/src/autostart.py) (Autostart manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Launch &amp; Runtime"]
  node_run_sh["Linux launcher<br/>shell launcher<br/>[run.sh]"]
  node_run_bat["Windows launcher<br/>batch launcher<br/>[run.bat]"]
  node_requirements["Python dependencies<br/>runtime dependencies<br/>[requirements.txt]"]
end

subgraph group_desktop["Desktop Application"]
  node_main{{"Application manager<br/>Qt bootstrap<br/>[main.py]"}}
  node_tray["System tray<br/>OS integration<br/>[main.py]"]
  node_note_manager["Note manager<br/>lifecycle controller<br/>[main.py]"]
end

subgraph group_ui["Note UI &amp; Control"]
  node_sticky_note["Sticky note window<br/>frameless Qt window<br/>[note_window.py]"]
  node_editor["Markdown editor<br/>QTextEdit engine<br/>[editor.py]"]
  node_dashboard["Dashboard<br/>note control surface<br/>[dashboard.py]"]
  node_settings["Settings dialog<br/>preferences UI<br/>[settings.py]"]
  node_styles["Themes and styles<br/>Qt stylesheet definitions<br/>[styles.py]"]
end

subgraph group_local["Local Storage &amp; OS"]
  node_note_files["Markdown note bodies<br/>local Markdown files"]
  node_note_metadata["Note metadata<br/>local JSON files"]
  node_config["Application config<br/>local JSON config"]
  node_autostart["Autostart manager<br/>platform startup bridge<br/>[autostart.py]"]
  node_os_windowing["OS windowing and tray<br/>platform services"]
end

node_run_sh -->|"launches"| node_main
node_run_bat -->|"launches"| node_main
node_requirements -.->|"provides runtime"| node_main
node_main -->|"initializes"| node_tray
node_main -->|"owns"| node_note_manager
node_note_manager -->|"manages instances"| node_sticky_note
node_tray -->|"invokes actions"| node_note_manager
node_dashboard -->|"controls notes"| node_note_manager
node_sticky_note -->|"embeds"| node_editor
node_sticky_note -->|"uses"| node_styles
node_settings -->|"selects themes"| node_styles
node_settings -->|"applies overrides"| node_sticky_note
node_sticky_note -->|"reads and writes text"| node_note_files
node_sticky_note -->|"persists layout"| node_note_metadata
node_settings -->|"persists defaults"| node_config
node_settings -->|"configures"| node_autostart
node_autostart -->|"registers startup"| node_os_windowing
node_main -->|"uses Qt platform APIs"| node_os_windowing
node_sticky_note -->|"controls window state"| node_os_windowing

click node_run_sh "https://github.com/iamshrisawant/digi-notes/blob/main/run.sh"
click node_run_bat "https://github.com/iamshrisawant/digi-notes/blob/main/run.bat"
click node_requirements "https://github.com/iamshrisawant/digi-notes/blob/main/requirements.txt"
click node_main "https://github.com/iamshrisawant/digi-notes/blob/main/src/main.py"
click node_tray "https://github.com/iamshrisawant/digi-notes/blob/main/src/main.py"
click node_note_manager "https://github.com/iamshrisawant/digi-notes/blob/main/src/main.py"
click node_sticky_note "https://github.com/iamshrisawant/digi-notes/blob/main/src/note_window.py"
click node_editor "https://github.com/iamshrisawant/digi-notes/blob/main/src/editor.py"
click node_dashboard "https://github.com/iamshrisawant/digi-notes/blob/main/src/dashboard.py"
click node_settings "https://github.com/iamshrisawant/digi-notes/blob/main/src/settings.py"
click node_styles "https://github.com/iamshrisawant/digi-notes/blob/main/src/styles.py"
click node_autostart "https://github.com/iamshrisawant/digi-notes/blob/main/src/autostart.py"

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_run_sh,node_run_bat,node_requirements toneBlue
class node_main,node_tray,node_note_manager toneAmber
class node_sticky_note,node_editor,node_dashboard,node_settings,node_styles toneMint
class node_note_files,node_note_metadata,node_config,node_autostart,node_os_windowing toneRose
```

## Components

### Launch & Runtime

- [Linux launcher](https://github.com/iamshrisawant/digi-notes/blob/main/run.sh): shell launcher · Forces Qt XCB on Linux. · `run.sh`
- [Windows launcher](https://github.com/iamshrisawant/digi-notes/blob/main/run.bat): batch launcher · `run.bat`
- [Python dependencies](https://github.com/iamshrisawant/digi-notes/blob/main/requirements.txt): runtime dependencies · Provides PySide6 and markdown-it-py. · `requirements.txt`

### Desktop Application

- [Application manager](https://github.com/iamshrisawant/digi-notes/blob/main/src/main.py): Qt bootstrap · Owns the Qt lifetime, singleton lock, tray, and note lifecycle. · `src/main.py`
- [System tray](https://github.com/iamshrisawant/digi-notes/blob/main/src/main.py): OS integration · `src/main.py`
- [Note manager](https://github.com/iamshrisawant/digi-notes/blob/main/src/main.py): lifecycle controller · Creates, shows, hides, and removes note windows. · `src/main.py`

### Note UI & Control

- [Sticky note window](https://github.com/iamshrisawant/digi-notes/blob/main/src/note_window.py): frameless Qt window · Bridges persisted state to desktop window behavior. · `src/note_window.py`
- [Markdown editor](https://github.com/iamshrisawant/digi-notes/blob/main/src/editor.py): QTextEdit engine · Edits Markdown with rich styling, lists, and checkbox interactions. · `src/editor.py`
- [Dashboard](https://github.com/iamshrisawant/digi-notes/blob/main/src/dashboard.py): note control surface · Manages active note instances without an independent model. · `src/dashboard.py`
- [Settings dialog](https://github.com/iamshrisawant/digi-notes/blob/main/src/settings.py): preferences UI · Controls defaults and live per-note overrides. · `src/settings.py`
- [Themes and styles](https://github.com/iamshrisawant/digi-notes/blob/main/src/styles.py): Qt stylesheet definitions · `src/styles.py`

### Local Storage & OS

- **Markdown note bodies**: local Markdown files · Stored as data/notes/<id>.md.
- **Note metadata**: local JSON files · Stores geometry and appearance per note.
- **Application config**: local JSON config · Runtime-created data/config.json.
- [Autostart manager](https://github.com/iamshrisawant/digi-notes/blob/main/src/autostart.py): platform startup bridge · Uses desktop entries, Registry, or launch agents. · `src/autostart.py`
- **OS windowing and tray**: platform services

## Connections

- Linux launcher → Application manager: launches
- Windows launcher → Application manager: launches
- Python dependencies → Application manager: provides runtime
- Application manager → System tray: initializes
- Application manager → Note manager: owns
- Note manager → Sticky note window: manages instances
- System tray → Note manager: invokes actions
- Dashboard → Note manager: controls notes
- Sticky note window → Markdown editor: embeds
- Sticky note window → Themes and styles: uses
- Settings dialog → Themes and styles: selects themes
- Settings dialog → Sticky note window: applies overrides
- Sticky note window → Markdown note bodies: reads and writes text
- Sticky note window → Note metadata: persists layout
- Settings dialog → Application config: persists defaults
- Settings dialog → Autostart manager: configures
- Autostart manager → OS windowing and tray: registers startup
- Application manager → OS windowing and tray: uses Qt platform APIs
- Sticky note window → OS windowing and tray: controls window state