# traves-theberge/tasky architecture

> Architecture diagram of the GitHub repository traves-theberge/tasky, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/traves-theberge/tasky
- Repository: https://github.com/traves-theberge/tasky

## Overview

##### Project type and purpose
- This is a full-stack Electron desktop application (Tasky) whose purpose is to run quietly in the user’s system tray, schedule recurring reminders, play notification sounds, and display an animated desktop assistant.
- The README confirms core features: recurring reminders (via node-cron), tray integration, customizable notifications, and an interactive “assistant” overlay.

##### File structure
Top-level
- package.json, package-lock.json – npm dependencies and scripts
- build, vite.electron.config.js, vite.renderer.config.js – build/distribution artifacts and configs
- postcss.config.mjs, tailwind.config.js – CSS tooling

src/
- main.js – Electron main process entry point
- preload.js – Secure IPC bridge exposing safe APIs to the renderer
- electron/ – Backend modules for scheduling, storage, and assistant logic
– scheduler.js (node-cron job setup)
– storage.js (electron-store persistence)
– assistant.js (assistant control logic)
– assistant-script.js (front-end script injected into assistant overlay)
- renderer/ – React/Vite frontend
– index.html, renderer.jsx (app bootstrap)
– App.jsx, App.css
- components/ & components/ui/ – React UI components (settings, controls)
- assets/ – media files (notification.mp3)
- lib/utils.js – shared utilities

##### README for additional insights
- Confirms Electron + React + Vite + Tailwind CSS + node-cron + electron-store
- Describes config file locations (OS-specific)
- Highlights features: tray interactions, notification delivery, assistant avatars, settings UI

a. Main components
1. Electron Main Process
- Entry: main.js
- Scheduling orchestration (scheduler.js)
- Data persistence (storage.js using electron-store)
- IPC channels to/from Preload & Renderer
2. Preload Script (preload.js)
- Exposes a limited set of IPC methods (e.g., getConfig, scheduleReminder, playSound)
- Ensures renderer security
3. Renderer (React App)
- UI for settings and assistant display
- Components (SettingSection, CustomSwitch, etc.)
- Invokes IPC APIs via window.api
4. Assistant Overlay
- assistant.js controls avatar positioning & animations
- assistant-script.js injected into a transparent BrowserWindow for the assistant
5. Scheduler (node-cron)
- Runs in main process
- Fires reminder events at configured times/days
6. Notification subsystem
- Plays audio (notification.mp3)
- Displays system notifications or custom popup windows
7. Data Store (electron-store)
- Config JSON persisted per OS
8. OS Integration
- Auto-start registration
- Native notifications (optional)

b. Relationships & interactions
- Main spawns Renderer window (settings UI) via BrowserWindow
- Renderer ↔ Preload via IPC for read/write config and control toggles
- Main → Scheduler (reads config, schedules jobs) → emits “reminder” events
- On “reminder” event: Main → plays sound, triggers assistant overlay window, and/or native notification → Renderer may display custom notification bubble
- Assistant overlay window loads assistant-script.js which calls back to assistant.js for animation and speech bubbles

c. Architectural patterns & design principles
- Separation of concerns: Main process handles OS-level operations, scheduling, storage; Renderer handles UI/UX
- Secure IPC: use of preload.js to whitelist only necessary APIs
- Modularization: electron/ folder isolates backend modules; components/ui isolates reusable React controls
- Configuration as code: All settings persisted in JSON with a clear schema

d. Key technologies & frameworks
- Electron (main, preload, BrowserWindow, Tray)
- React + Vite (renderer UI)
- Tailwind CSS (styling)
- node-cron (scheduling)
- electron-store (persistent config)

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Electron Main Process" 
    direction TB
    Main["Main Process<br/>(main.js)"]:::main
    Tray["System Tray Integration"]:::os
    AutoStart["Auto-Start Registration"]:::os
    Scheduler["Scheduler<br/>(node-cron)"]:::backend
    Storage["Config Store<br/>(electron-store)"]:::storage
    AssistantCtrl["Assistant Controller<br/>(assistant.js)"]:::backend
    NotificationSub["Notification Subsystem"]:::backend
    AssistantOverlayWnd["Assistant Overlay Window"]:::backend
  end

  subgraph "Preload Script" 
    direction TB
    Preload["Preload Bridge<br/>(preload.js)"]:::preload
  end

  subgraph "Renderer (React App)" 
    direction TB
    HTML["index.html"]:::renderer
    Renderer["renderer.jsx"]:::renderer
    App["App.jsx"]:::ui
    AppCSS["App.css"]:::ui
    Components["components/ & ui/"]:::ui
  end

  subgraph "Shared Utilities"
    Utils["utils.js"]:::utils
  end

  subgraph "Assets"
    Asset["notification.mp3"]:::asset
  end

  %% User Interaction
  User["User"]:::os -->|"click tray icon"| Tray

  %% Main process orchestration
  Tray --> Main
  AutoStart --> Main
  Main --> Scheduler
  Main --> Storage
  Main --> AssistantCtrl
  Main --> NotificationSub
  Main --> AssistantOverlayWnd

  %% Scheduler events
  Scheduler -->|"onReminder"| Main

  %% Notification subsystem uses asset
  NotificationSub --> Asset

  %% IPC via Preload
  Main -.-> Preload
  Preload -.-> Renderer
  Renderer -.-> Preload
  Preload -.-> Main

  %% Renderer calls
  Renderer -->|"window.api.getConfig()"| Preload
  Renderer -->|"window.api.scheduleReminder()"| Preload
  Renderer -->|"window.api.playSound()"| Preload

  %% Utilities
  Main --> Utils
  Renderer --> Utils

  %% Assistant Overlay script
  AssistantOverlayWnd --> AssistantScript["assistant-script.js"]:::backend
  AssistantScript --> AssistantCtrl

  %% Click Events
  click Main "https://github.com/traves-theberge/tasky/blob/main/src/main.js"
  click Preload "https://github.com/traves-theberge/tasky/blob/main/src/preload.js"
  click Renderer "https://github.com/traves-theberge/tasky/blob/main/src/renderer/renderer.jsx"
  click HTML "https://github.com/traves-theberge/tasky/blob/main/src/renderer/index.html"
  click App "https://github.com/traves-theberge/tasky/blob/main/src/renderer/App.jsx"
  click AppCSS "https://github.com/traves-theberge/tasky/blob/main/src/renderer/App.css"
  click Components "https://github.com/traves-theberge/tasky/tree/main/src/components/"
  click Scheduler "https://github.com/traves-theberge/tasky/blob/main/src/electron/scheduler.js"
  click Storage "https://github.com/traves-theberge/tasky/blob/main/src/electron/storage.js"
  click AssistantCtrl "https://github.com/traves-theberge/tasky/blob/main/src/electron/assistant.js"
  click AssistantScript "https://github.com/traves-theberge/tasky/blob/main/src/electron/assistant-script.js"
  click Asset "https://github.com/traves-theberge/tasky/blob/main/src/assets/notification.mp3"
  click Utils "https://github.com/traves-theberge/tasky/blob/main/src/lib/utils.js"

  %% Styles
  classDef main fill:#ffeadb,stroke:#e07a5f,stroke-width:2px
  classDef preload fill:#d0eef2,stroke:#3d5a80,stroke-width:2px
  classDef renderer fill:#e8f1f5,stroke:#293241,stroke-width:2px
  classDef ui fill:#f1f6f9,stroke:#3d5a80,stroke-width:2px
  classDef backend fill:#f0efeb,stroke:#2a9d8f,stroke-width:2px
  classDef storage fill:#e8f1f2,stroke:#8338ec,stroke-width:2px
  classDef os fill:#fff2cc,stroke:#f4a261,stroke-width:2px
  classDef asset fill:#f0efeb,stroke:#2a9d8f,stroke-width:2px
  classDef utils fill:#f6eddf,stroke:#264653,stroke-width:2px
```
