alainm23/planify

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.