# reduanahmadswe/dayonedesktop architecture

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

- Interactive diagram: https://gitdiagram.com/reduanahmadswe/dayonedesktop
- Repository: https://github.com/reduanahmadswe/dayonedesktop

## Overview

1. **Overall shape**
   DayOne Desktop is a Windows-only Electron app with two user-facing surfaces sharing one local SQLite database: a compact “wallpaper panel” that sits on the desktop behind icons, and a full editor window for managing tasks, calendar, notes, and settings.

2. **Process boundary**
   The architecture is split into an Electron **main process** under `electron/` and a **renderer** React app under `src/`. The main process owns app lifecycle, windows, tray, database access, startup behavior, and native Windows integration. The renderer owns all UI and never touches the filesystem or database directly.

3. **Renderer structure**
   The renderer is organized by feature: `tasks`, `calendar`, `notes`, and `settings`, plus shared widgets used by the wallpaper panel. `src/App.tsx` routes between the desktop panel and editor shell, while `src/layouts/WallpaperLayout.tsx` and `src/layouts/EditorLayout.tsx` define the two primary UI shells.

4. **Desktop wallpaper layer**
   The desktop panel is not a normal floating window. It is attached to the Windows desktop shell using native Win32 interop in `electron/native/wallpaper.ts` with `koffi`, so it appears behind desktop icons and remains click-through. This is the key architectural boundary that makes the “today panel on the desktop” behavior possible.

5. **Window management**
   `electron/windows/windowManager.ts` centralizes creation and control of the editor window and the wallpaper window. It coordinates route loading, visibility, focus behavior, and the “second instance brings editor forward” experience. The tray and IPC window handlers both delegate to this layer.

6. **Data layer**
   Persistence is local-only via Prisma + SQLite. The Prisma schema lives in `prisma/schema.prisma`, migrations under `prisma/migrations`, and the runtime database file is stored in the app’s user data directory. The database models cover tasks, categories, notes, events, reminders, and settings.

7. **Main-process database initialization**
   `electron/database/init.ts` and `electron/database/client.ts` handle creation and initialization of the SQLite database, including default settings and seed data. The repo also has explicit seed helpers such as `seedStudentTasks.ts`, plus CLI scripts for inspection and seeding, which indicates the database is a first-class subsystem rather than incidental storage.

8. **IPC as the application boundary**
   All renderer-to-backend traffic goes through typed IPC. `electron/preload.ts` exposes a `window.dayone` bridge, and `src/services/ipcClient.ts` is the renderer-side wrapper. Channel names in `electron/ipc/channels.ts` separate concerns by domain: tasks, notes, categories, events, settings, wallpaper, and window operations.

9. **IPC handlers and state invalidation**
   The handlers under `electron/ipc/handlers/` implement CRUD and app actions in the main process. After mutations, the backend broadcasts `data:changed` so renderer views can refresh. This means UI state is driven by local DB changes plus explicit invalidation events rather than remote sync or shared memory.

10. **Background services**
   The main process includes several long-lived services: startup registration with Windows, auto-updater support, display/monitor tracking, reminder notifications, wallpaper attach retries, and a watchdog to reattach after shell restarts or sleep. These services make the app behave like a persistent desktop companion rather than a normal single-window app.

11. **Tray-centered app control**
   `electron/tray.ts` is the main user-control surface when the editor is hidden. It exposes app actions such as opening the editor, showing/hiding the wallpaper, navigating to feature sections, and toggling startup behavior. The close button does not terminate the app; tray state is part of the normal runtime model.

12. **Build and packaging pipeline**
   The project is built with Vite for the renderer, TypeScript for Electron code, Prisma client generation, and electron-builder for NSIS packaging. The build output is split between `dist/` for renderer assets and `dist-electron/` for main/preload code, with packaged native dependencies such as Prisma’s engine and `koffi` unpacked so Electron can load them correctly.

13. **Development mode differences**
   Development uses the Vite dev server plus Electron launch scripts, but the wallpaper injection path is intentionally disabled in dev. That means the true desktop-layer behavior is only exercised in installed production builds, which is an important distinction when diagramming runtime behavior versus development behavior.

14. **Key end-to-end flows**
   The main architectural flow is: renderer UI action → preload bridge → IPC handler → Prisma/SQLite update → `data:changed` broadcast → renderer refresh. The desktop-specific flow adds another path: main process boot → wallpaper attach service → native Win32 desktop parenting → always-visible today panel. These two flows define the repo’s core behavior.

Main entry points: [`electron/main.ts`](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/main.ts) (Main entry), [`electron/ipc/handlers/index.ts`](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/ipc/handlers/index.ts) (IPC handlers), [`src/App.tsx`](https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/App.tsx) (App shell), [`src/services/ipcClient.ts`](https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/services/ipcClient.ts) (IPC client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_main["Electron main"]
  node_electron_main["Main entry<br/>electron bootstrap<br/>[main.ts]"]
  node_window_manager["Window manager<br/>window orchestration<br/>[windowManager.ts]"]
  node_tray(("Tray control<br/>app control<br/>[tray.ts]"))
  node_ipc_handlers["IPC handlers<br/>backend api<br/>[index.ts]"]
  node_ipc_channels["Channel map<br/>ipc contract<br/>[channels.ts]"]
  node_preload_bridge["Preload bridge<br/>context bridge<br/>[preload.ts]"]
  node_wallpaper_native{{"Desktop attach<br/>win32 interop<br/>[wallpaper.ts]"}}
  node_wallpaper_service["Wallpaper service<br/>desktop service"]
  node_startup_services["Background services<br/>runtime services<br/>[startupService.ts]"]
end

subgraph group_renderer["Renderer UI"]
  node_renderer_app["App shell<br/>react entry<br/>[App.tsx]"]
  node_wallpaper_layout["Wallpaper layout<br/>ui shell"]
  node_editor_layout["Editor layout<br/>ui shell<br/>[EditorLayout.tsx]"]
  node_feature_pages["Feature pages<br/>ui features<br/>[TasksPage.tsx]"]
  node_widgets["Wallpaper widgets<br/>ui widgets<br/>[index.tsx]"]
  node_ipc_client["IPC client<br/>renderer api<br/>[ipcClient.ts]"]
  node_stores["UI stores<br/>state"]
end

subgraph group_data["Local data"]
  node_db_client[("DB client<br/>sqlite access<br/>[client.ts]")]
  node_db_init["DB init<br/>seed/init<br/>[init.ts]"]
  node_schema["Schema<br/>[schema.prisma]"]
  node_migrations["Migrations<br/>[migration.sql]"]
end

subgraph group_build["Build & packaging"]
  node_build_tooling["Build tooling<br/>toolchain<br/>[vite.config.ts]"]
  node_packaging["Packaging<br/>installer build"]
end

node_electron_main -->|"creates"| node_window_manager
node_electron_main -->|"owns"| node_tray
node_electron_main -->|"registers"| node_ipc_handlers
node_electron_main -->|"loads"| node_preload_bridge
node_electron_main -->|"starts"| node_startup_services
node_window_manager -->|"attaches"| node_wallpaper_service
node_wallpaper_service -->|"uses"| node_wallpaper_native
node_ipc_handlers -->|"queries"| node_db_client
node_db_init -->|"initializes"| node_db_client
node_schema -->|"evolves to"| node_migrations
node_preload_bridge -->|"exposes"| node_ipc_client
node_ipc_client -->|"calls"| node_ipc_handlers
node_ipc_handlers -->|"uses"| node_ipc_channels
node_renderer_app -->|"routes"| node_wallpaper_layout
node_renderer_app -->|"routes"| node_editor_layout
node_editor_layout -->|"hosts"| node_feature_pages
node_wallpaper_layout -->|"hosts"| node_widgets
node_feature_pages -->|"reads/writes"| node_ipc_client
node_widgets -->|"reads"| node_ipc_client
node_stores -->|"supports"| node_renderer_app
node_build_tooling -->|"bundles"| node_renderer_app
node_build_tooling -->|"compiles"| node_electron_main
node_packaging -->|"packages"| node_wallpaper_native

click node_electron_main "https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/main.ts"
click node_window_manager "https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/windows/windowManager.ts"
click node_tray "https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/tray.ts"
click node_ipc_handlers "https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/ipc/handlers/index.ts"
click node_ipc_channels "https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/ipc/channels.ts"
click node_preload_bridge "https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/preload.ts"
click node_wallpaper_native "https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/native/wallpaper.ts"
click node_wallpaper_service "https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/services/wallpaperAttachService.ts"
click node_startup_services "https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/services/startupService.ts"
click node_db_client "https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/database/client.ts"
click node_db_init "https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/database/init.ts"
click node_schema "https://github.com/reduanahmadswe/dayonedesktop/blob/main/prisma/schema.prisma"
click node_migrations "https://github.com/reduanahmadswe/dayonedesktop/blob/main/prisma/migrations/20260627000000_init/migration.sql"
click node_renderer_app "https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/App.tsx"
click node_wallpaper_layout "https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/layouts/WallpaperLayout.tsx"
click node_editor_layout "https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/layouts/EditorLayout.tsx"
click node_feature_pages "https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/features/tasks/components/TasksPage.tsx"
click node_widgets "https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/widgets/WallpaperTodayPanel/index.tsx"
click node_ipc_client "https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/services/ipcClient.ts"
click node_stores "https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/store/useSettingsStore.ts"
click node_build_tooling "https://github.com/reduanahmadswe/dayonedesktop/blob/main/vite.config.ts"
click node_packaging "https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron-builder.yml"

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_electron_main,node_window_manager,node_tray,node_ipc_handlers,node_ipc_channels,node_preload_bridge,node_wallpaper_native,node_wallpaper_service,node_startup_services toneBlue
class node_renderer_app,node_wallpaper_layout,node_editor_layout,node_feature_pages,node_widgets,node_ipc_client,node_stores toneAmber
class node_db_client,node_db_init,node_schema,node_migrations toneMint
class node_build_tooling,node_packaging toneRose
```

## Components

### Electron main

App lifecycle, windows, IPC, native integration, and local services.

- [Main entry](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/main.ts): electron bootstrap · Starts the Electron app and wires together main-process subsystems. · `electron/main.ts`
- [Window manager](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/windows/windowManager.ts): window orchestration · Creates and coordinates editor and wallpaper windows, focus, route loading, and instance behavior. · `electron/windows/windowManager.ts`
- [Tray control](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/tray.ts): app control · System tray actions for opening the app, toggling surfaces, and startup behavior. · `electron/tray.ts`
- [IPC handlers](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/ipc/handlers/index.ts): backend api · Typed application actions for tasks, notes, events, reminders, settings, wallpaper, and window ops. · `electron/ipc/handlers/index.ts`
- [Channel map](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/ipc/channels.ts): ipc contract · Shared channel names that define renderer-to-main boundaries by domain. · `electron/ipc/channels.ts`
- [Preload bridge](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/preload.ts): context bridge · Exposes the window.dayone API to the renderer as the only backend entrypoint. · `electron/preload.ts`
- [Desktop attach](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/native/wallpaper.ts): win32 interop · Native Win32 wallpaper parenting that attaches the panel behind desktop icons. · `electron/native/wallpaper.ts`
- [Wallpaper service](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/services/wallpaperAttachService.ts): desktop service · Retries and maintains the desktop-shell attachment for the wallpaper surface. · `electron/services/wallpaperAttachService.ts`
- [Background services](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/services/startupService.ts): runtime services · Startup registration, display tracking, reminders, updater support, and watchdog behavior. · `electron/services/startupService.ts`

### Renderer UI

React UI, feature pages, layouts, widgets, and client-side state.

- [App shell](https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/App.tsx): react entry · Routes between wallpaper panel and editor shell in the renderer. · `src/App.tsx`
- [Wallpaper layout](https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/layouts/WallpaperLayout.tsx): ui shell · Layout for the desktop-attached today panel. · `src/layouts/WallpaperLayout.tsx`
- [Editor layout](https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/layouts/EditorLayout.tsx): ui shell · Layout for the full editor window. · `src/layouts/EditorLayout.tsx`
- [Feature pages](https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/features/tasks/components/TasksPage.tsx): ui features · Task, calendar, notes, and settings screens in the editor. · `src/features/tasks/components/TasksPage.tsx`
- [Wallpaper widgets](https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/widgets/WallpaperTodayPanel/index.tsx): ui widgets · Shared desktop-panel widgets such as tasks, notes, clock, date, and calendar month. · `src/widgets/WallpaperTodayPanel/index.tsx`
- [IPC client](https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/services/ipcClient.ts): renderer api · Renderer-side wrapper around the dayone bridge for backend calls and refresh flow. · `src/services/ipcClient.ts`
- [UI stores](https://github.com/reduanahmadswe/dayonedesktop/blob/main/src/store/useSettingsStore.ts): state · Client state for settings, theme, and wallpaper behavior. · `src/store/useSettingsStore.ts`

### Local data

Prisma schema, SQLite persistence, migrations, and seed data.

- [DB client](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/database/client.ts): sqlite access · Creates and initializes the Prisma-backed SQLite client and runtime database state. · `electron/database/client.ts`
- [DB init](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron/database/init.ts): seed/init · Bootstraps default settings and initial database state. · `electron/database/init.ts`
- [Schema](https://github.com/reduanahmadswe/dayonedesktop/blob/main/prisma/schema.prisma): prisma schema · Defines tasks, categories, notes, events, reminders, and settings models. · `prisma/schema.prisma`
- [Migrations](https://github.com/reduanahmadswe/dayonedesktop/blob/main/prisma/migrations/20260627000000_init/migration.sql): db migrations · Database schema evolution for the local SQLite store. · `prisma/migrations/20260627000000_init/migration.sql`

### Build & packaging

Tooling for development, bundling, and installer packaging.

- [Build tooling](https://github.com/reduanahmadswe/dayonedesktop/blob/main/vite.config.ts): toolchain · Vite, TypeScript, and Electron launch scripts for development and production builds. · `vite.config.ts`
- [Packaging](https://github.com/reduanahmadswe/dayonedesktop/blob/main/electron-builder.yml): installer build · Electron Builder packaging, native dependency handling, and NSIS installer output. · `electron-builder.yml`

## Connections

- Main entry → Window manager: creates · Main process delegates window lifecycle to the centralized manager.
- Main entry → Tray control: owns · Tray is initialized from the app bootstrap.
- Main entry → IPC handlers: registers · Main bootstrap wires typed IPC handlers.
- Main entry → Preload bridge: loads · Preload exposes the renderer bridge.
- Main entry → Background services: starts · Bootstraps background services on app launch.
- Window manager → Wallpaper service: attaches · Window manager coordinates the wallpaper surface lifecycle.
- Wallpaper service → Desktop attach: uses · Desktop attachment relies on native Win32 interop.
- IPC handlers → DB client: queries · Handlers perform CRUD through the local database client.
- DB init → DB client: initializes · Database startup sets defaults and seed state.
- Schema → Migrations: evolves to · Schema is realized through generated migrations.
- Preload bridge → IPC client: exposes · Renderer consumes the backend through the bridge and client wrapper.
- IPC client → IPC handlers: calls · Renderer actions dispatch to main-process handlers.
- IPC handlers → Channel map: uses · Handlers and renderer share domain channel names.
- App shell → Wallpaper layout: routes · App shell selects the desktop panel layout.
- App shell → Editor layout: routes · App shell selects the editor window layout.
- Editor layout → Feature pages: hosts · Editor shell renders the feature views.
- Wallpaper layout → Wallpaper widgets: hosts · Wallpaper surface is composed from shared widgets.
- Feature pages → IPC client: reads/writes · Feature pages load and mutate data through IPC.
- Wallpaper widgets → IPC client: reads · Desktop widgets pull data via the renderer client.
- UI stores → App shell: supports · Client state feeds layout and theme behavior.
- Build tooling → App shell: bundles · Vite builds the React renderer.
- Build tooling → Main entry: compiles · TypeScript build produces main-process output.
- Packaging → Desktop attach: packages · Installer build ships native modules required for desktop attachment.