# alainm23/planify architecture

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

- Interactive diagram: https://gitdiagram.com/alainm23/planify
- Repository: https://github.com/alainm23/planify

## Overview

1. **Repository shape: one shared core, multiple frontends**
   Planify is a Vala/GTK4 desktop application split into a reusable `core` layer and several entry-point frontends: the main GUI in `src`, a lightweight `quick-add` app, a `cli` tool, and a GNOME Shell `search-provider`. The architecture is centered on sharing the same task/domain logic across these surfaces.

2. **Domain model lives in `core/Objects`**
   The core layer defines the application’s main entities: tasks/items, projects, sections, labels, reminders, attachments, due dates, sources/accounts, release metadata, and filter objects such as Today, Inbox, Scheduled, Completed, etc. These objects are the canonical data shape used by both UI and service code.

3. **Core services provide the application’s backend**
   `core/Services` contains the non-UI logic that underpins the app: database access, settings, event bus, logging, backup export, calendar-event calculations, color scheme handling, and provider-specific sync clients. This layer is the boundary between UI and persistence/networking.

4. **Local state is database-backed and settings-driven**
   The app persists its task data locally through `core/Services/Database` and `Store`, with application preferences handled through GSettings (`data/io.github.alainm23.planify.gschema.xml` and `core/Services/Settings`). The diagram should show local storage as a first-class backend, not just an in-memory model.

5. **Sync integrations are separate provider subsystems**
   Sync is split into two provider families:
   - **Todoist** under `core/Services/Todoist`
   - **CalDAV/Nextcloud** under `core/Services/CalDAV`
   
   These modules handle authentication, transport, and item/project synchronization. `libsecret` is used where credentials need secure storage, and `libsoup`/WebDAV-style clients are used for HTTP sync traffic.

6. **The main GUI in `src` is a shell around the core**
   `src/App.vala` and `src/MainWindow.vala` build the GTK4/libadwaita desktop experience: sidebar navigation, project/label/filter views, scheduled/today views, dialogs, and editing flows. The UI is organized into layouts, views, dialogs, and reusable widgets, all consuming the shared core objects and services.

7. **UI is componentized into reusable views and widgets**
   The `src/Views`, `src/Layouts`, and `src/Widgets` directories contain the presentation layer. Views represent major pages like Today, Scheduled, Project, and Labels; layouts arrange app-level containers like sidebar and item boards; widgets provide task editors, pickers, reminders, labels, attachments, and status controls. This is where most interaction logic sits, but it delegates data/state operations to core services.

8. **There is an internal event/command flow**
   `src/Services/ActionManager`, `DBusServer`, `Api`, `Notification`, `TimeMonitor`, and related classes coordinate app actions, background updates, notifications, and inter-process communication. The flow is generally: UI action → service layer → core/store/database → event bus → UI refresh/notifications.

9. **Multiple external entry points reuse the same backend concepts**
   - `cli` provides a terminal interface for task creation and validation, backed by D-Bus connectivity and shared parsing/formatting code.
   - `quick-add` is a small app for fast task entry, also using D-Bus.
   - `search-provider` exposes tasks/projects to GNOME Shell search through a repository/search adapter.
   
   These are separate binaries, but they rely on the same task model and local/backend state.

10. **Calendar and date scheduling are a distinct subsystem**
   Date handling is not just UI decoration: `core/Services/CalendarEvents` and the calendar widgets in both `core` and `src` support recurring schedules, due dates, reminders, and date-range views. This subsystem is what powers scheduled/today/tomorrow-style filtering and calendar displays.

11. **Resources, theming, and translations are bundled at build time**
   The project uses GTK resource bundles (`data/io.github.alainm23.planify.gresource.xml`) for icons, images, CSS, sounds, and UI definitions, plus GNOME application metadata and desktop/service files. Translation catalogs under `po/` are a significant part of the build and are surfaced in CI and release workflows.

12. **Build and test structure mirrors the architecture**
   Meson is the build system, with separate targets for the main app, CLI, quick-add, and search provider. Tests are organized under `test/` with coverage for CLI behavior and CalDAV integration, reinforcing that the critical boundaries are parsing/validation, sync, and shared backend behavior rather than only UI rendering.

Main entry points: [`core/Objects`](https://github.com/alainm23/planify/tree/main/core/Objects) (Domain model), [`meson.build`](https://github.com/alainm23/planify/blob/main/meson.build) (Meson build), [`core/Services/Database.vala`](https://github.com/alainm23/planify/blob/main/core/Services/Database.vala) (Database), [`src/Views`](https://github.com/alainm23/planify/tree/main/src/Views) (Views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core"]
  node_core_objects["Domain model<br/>vala core objects"]
  node_core_store["Store<br/>[Store.vala]"]
  node_core_database[("Database<br/>local persistence<br/>[Database.vala]")]
  node_core_settings["Settings<br/>[Settings.vala]"]
  node_core_bus(("Event bus<br/>event coordination<br/>[EventBus.vala]"))
  node_core_calendar["Calendar logic<br/>scheduling service"]
  node_core_todoist["Todoist sync<br/>provider backend"]
  node_core_caldav["CalDAV sync<br/>provider backend"]
  node_core_widgets["Shared widgets<br/>gtk reusable widgets"]
end

subgraph group_app["Main app"]
  node_app_main["Desktop shell<br/>gtk app<br/>[App.vala]"]
  node_app_window["Main window<br/>ui shell<br/>[MainWindow.vala]"]
  node_app_views["Views<br/>presentation pages"]
  node_app_layouts["Layouts<br/>container views"]
  node_app_widgets["Widgets<br/>interactive controls"]
  node_app_services["App services<br/>runtime services"]
end

subgraph group_entry["Entry points"]
  node_entry_cli["CLI<br/>terminal binary"]
  node_entry_quick["Quick add<br/>mini app"]
  node_entry_search["Search provider<br/>gnome shell provider"]
end

subgraph group_assets["Build assets"]
  node_assets_data["Data assets<br/>resources and metadata"]
  node_assets_po["Translations<br/>localization"]
  node_build_meson["Meson build<br/>build system<br/>[meson.build]"]
end

node_app_main -->|"creates"| node_app_window
node_app_window -->|"navigates"| node_app_views
node_app_window -->|"composes"| node_app_layouts
node_app_views -->|"uses"| node_app_widgets
node_app_layouts -->|"uses"| node_app_widgets
node_app_views -->|"renders"| node_core_objects
node_app_views -->|"filters by date"| node_core_calendar
node_app_widgets -->|"edits"| node_core_objects
node_app_widgets -->|"picks dates"| node_core_calendar
node_app_services -->|"orchestrates"| node_core_store
node_app_services -->|"publishes"| node_core_bus
node_app_services -->|"persists"| node_core_database
node_core_store -->|"backed by"| node_core_database
node_core_store -->|"hosts"| node_core_objects
node_core_database -->|"configured by"| node_core_settings
node_core_calendar -->|"interprets"| node_core_objects
node_core_todoist -->|"syncs"| node_core_objects
node_core_caldav -->|"syncs"| node_core_objects
node_core_todoist -->|"reads/writes"| node_core_database
node_core_caldav -->|"reads/writes"| node_core_database
node_entry_cli -->|"uses"| node_core_objects
node_entry_cli -->|"connects"| node_core_database
node_entry_quick -->|"creates"| node_core_objects
node_entry_quick -->|"signals"| node_core_bus
node_entry_search -->|"indexes"| node_core_objects
node_entry_search -->|"queries"| node_core_store
node_build_meson -->|"builds"| node_app_main
node_build_meson -->|"builds"| node_entry_cli
node_build_meson -->|"builds"| node_entry_quick
node_build_meson -->|"builds"| node_entry_search
node_build_meson -->|"packages"| node_assets_data
node_build_meson -->|"compiles"| node_assets_po

click node_core_objects "https://github.com/alainm23/planify/tree/main/core/Objects"
click node_core_store "https://github.com/alainm23/planify/blob/main/core/Services/Store.vala"
click node_core_database "https://github.com/alainm23/planify/blob/main/core/Services/Database.vala"
click node_core_settings "https://github.com/alainm23/planify/blob/main/core/Services/Settings.vala"
click node_core_bus "https://github.com/alainm23/planify/blob/main/core/Services/EventBus.vala"
click node_core_calendar "https://github.com/alainm23/planify/tree/main/core/Services/CalendarEvents"
click node_core_todoist "https://github.com/alainm23/planify/tree/main/core/Services/Todoist"
click node_core_caldav "https://github.com/alainm23/planify/tree/main/core/Services/CalDAV"
click node_core_widgets "https://github.com/alainm23/planify/tree/main/core/Widgets"
click node_app_main "https://github.com/alainm23/planify/blob/main/src/App.vala"
click node_app_window "https://github.com/alainm23/planify/blob/main/src/MainWindow.vala"
click node_app_views "https://github.com/alainm23/planify/tree/main/src/Views"
click node_app_layouts "https://github.com/alainm23/planify/tree/main/src/Layouts"
click node_app_widgets "https://github.com/alainm23/planify/tree/main/src/Widgets"
click node_app_services "https://github.com/alainm23/planify/tree/main/src/Services"
click node_entry_cli "https://github.com/alainm23/planify/tree/main/cli"
click node_entry_quick "https://github.com/alainm23/planify/tree/main/quick-add"
click node_entry_search "https://github.com/alainm23/planify/tree/main/search-provider"
click node_assets_data "https://github.com/alainm23/planify/tree/main/data"
click node_assets_po "https://github.com/alainm23/planify/tree/main/po"
click node_build_meson "https://github.com/alainm23/planify/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_core_objects,node_core_store,node_core_database,node_core_settings,node_core_bus,node_core_calendar,node_core_todoist,node_core_caldav,node_core_widgets toneBlue
class node_app_main,node_app_window,node_app_views,node_app_layouts,node_app_widgets,node_app_services toneAmber
class node_entry_cli,node_entry_quick,node_entry_search toneMint
class node_assets_data,node_assets_po,node_build_meson toneRose
```

## Components

### Core

Shared domain model and backend services

- [Domain model](https://github.com/alainm23/planify/tree/main/core/Objects): vala core objects · Tasks, projects, sections, labels, reminders, attachments, filters, and related entities · `core/Objects`
- [Store](https://github.com/alainm23/planify/blob/main/core/Services/Store.vala): state store · Application-facing state and data access coordination · `core/Services/Store.vala`
- [Database](https://github.com/alainm23/planify/blob/main/core/Services/Database.vala): local persistence · Database-backed storage for task data and sync state · `core/Services/Database.vala`
- [Settings](https://github.com/alainm23/planify/blob/main/core/Services/Settings.vala): gsettings config · Application preferences and configuration access · `core/Services/Settings.vala`
- [Event bus](https://github.com/alainm23/planify/blob/main/core/Services/EventBus.vala): event coordination · Shared notification and refresh signaling between components · `core/Services/EventBus.vala`
- [Calendar logic](https://github.com/alainm23/planify/tree/main/core/Services/CalendarEvents): scheduling service · Due dates, recurrence, date ranges, and calendar event calculations · `core/Services/CalendarEvents`
- [Todoist sync](https://github.com/alainm23/planify/tree/main/core/Services/Todoist): provider backend · Todoist authentication and item/project synchronization · `core/Services/Todoist`
- [CalDAV sync](https://github.com/alainm23/planify/tree/main/core/Services/CalDAV): provider backend · CalDAV/Nextcloud authentication, WebDAV transport, and synchronization · `core/Services/CalDAV`
- [Shared widgets](https://github.com/alainm23/planify/tree/main/core/Widgets): gtk reusable widgets · Calendar, pickers, editors, and other UI controls reused across surfaces · `core/Widgets`

### Main app

GTK desktop shell and presentation layer

- [Desktop shell](https://github.com/alainm23/planify/blob/main/src/App.vala): gtk app · Main GTK4/libadwaita application entry and window · `src/App.vala`
- [Main window](https://github.com/alainm23/planify/blob/main/src/MainWindow.vala): ui shell · Primary navigation and application window composition · `src/MainWindow.vala`
- [Views](https://github.com/alainm23/planify/tree/main/src/Views): presentation pages · Today, scheduled, project, label, and filter pages · `src/Views`
- [Layouts](https://github.com/alainm23/planify/tree/main/src/Layouts): container views · Sidebar, boards, rows, and other app-level layout components · `src/Layouts`
- [Widgets](https://github.com/alainm23/planify/tree/main/src/Widgets): interactive controls · Task editors, attachment rows, sync controls, and reusable interaction widgets · `src/Widgets`
- [App services](https://github.com/alainm23/planify/tree/main/src/Services): runtime services · Action dispatch, DBus server, notifications, migrations, export, and time monitoring · `src/Services`

### Entry points

Secondary binaries and adapters

- [CLI](https://github.com/alainm23/planify/tree/main/cli): terminal binary · Command-line task creation and validation tool · `cli`
- [Quick add](https://github.com/alainm23/planify/tree/main/quick-add): mini app · Fast task entry window using shared backend and DBus · `quick-add`
- [Search provider](https://github.com/alainm23/planify/tree/main/search-provider): gnome shell provider · GNOME Shell search integration over tasks and projects · `search-provider`

### Build assets

Resources, translations, and packaging

- [Data assets](https://github.com/alainm23/planify/tree/main/data): resources and metadata · Desktop file, GResource bundle, schema, icons, sounds, and app metadata · `data`
- [Translations](https://github.com/alainm23/planify/tree/main/po): localization · Translation catalogs and extraction inputs used across builds · `po`
- [Meson build](https://github.com/alainm23/planify/blob/main/meson.build): build system · Build definitions for app targets, resources, and packaging · `meson.build`

## Connections

- Desktop shell → Main window: creates · Bootstraps the main application shell
- Main window → Views: navigates · Hosts the major pages and filter views
- Main window → Layouts: composes · Uses sidebar and board layouts to arrange the UI
- Views → Widgets: uses · Pages embed reusable interaction widgets
- Layouts → Widgets: uses · Layouts reuse shared row and picker widgets
- Views → Domain model: renders · Displays domain entities and filter objects
- Views → Calendar logic: filters by date · Scheduled and today-style pages depend on calendar calculations
- Widgets → Domain model: edits · Editors and pickers manipulate shared task data
- Widgets → Calendar logic: picks dates · Date and reminder widgets use scheduling logic
- App services → Store: orchestrates · Coordinates application actions against shared state
- App services → Event bus: publishes · Sends refresh and notification events
- App services → Database: persists · Reads and writes local task state
- Store → Database: backed by · Store state is persisted in the database
- Store → Domain model: hosts · Keeps canonical domain objects in memory
- Database → Settings: configured by · Storage behavior depends on application settings
- Calendar logic → Domain model: interprets · Builds scheduled views and date objects from domain data
- Todoist sync → Domain model: syncs · Maps Todoist remote data onto shared entities
- CalDAV sync → Domain model: syncs · Maps CalDAV/Nextcloud data onto shared entities
- Todoist sync → Database: reads/writes · Synchronizes remote state with local storage
- CalDAV sync → Database: reads/writes · Synchronizes remote state with local storage
- CLI → Domain model: uses · Command parsing works with the shared task model
- CLI → Database: connects · CLI actions operate against the local backend
- Quick add → Domain model: creates · Quick add builds new task entities
- Quick add → Event bus: signals · Uses DBus/event flow to hand off task creation
- Search provider → Domain model: indexes · Search provider exposes tasks and projects
- Search provider → Store: queries · Search adapter reads shared app state
- Meson build → Desktop shell: builds · Defines the main desktop target
- Meson build → CLI: builds · Defines the CLI target
- Meson build → Quick add: builds · Defines the quick-add target
- Meson build → Search provider: builds · Defines the search provider target
- Meson build → Data assets: packages · Bundles resources, schema, icons, and metadata
- Meson build → Translations: compiles · Builds translation catalogs and language assets