# cachebag/ticked architecture

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

- Interactive diagram: https://gitdiagram.com/cachebag/ticked
- Repository: https://github.com/cachebag/ticked

## Overview

##### Project type and purpose
- **Type**: Terminal-based full-stack-like application (Python CLI/TUI)
- **Purpose**: Task and productivity manager with modules for calendar sync (CalDAV), Canvas LMS integration, Nest editor features, Spotify control, plus local task storage and utilities (system-stats, timers).

##### File structure
- **ticked/app.py** – Application entry point (initializes Textual TUI).
- **ticked/config/** – Configuration and theming.
- **ticked/core/** – Business logic & data layer:
- **database/** – Local DB access (ticked_db.py) and CalDAV sync (caldav_sync.py)
- **ticked/ui/** – UI layer:
- **screens/** – High-level screen controllers (over_arching.py)
- **views/** – Individual views (calendar, canvas, nest, pomodoro, settings, spotify, welcome)
- **mixins/** – Shared UI behaviors (focus handling).
- **ticked/widgets/** – Reusable UI widgets (task_widget).
- **ticked/utils/** – Helper modules (system_stats, time_utils).
- **External integrations**: Canvas API, Spotify API, iOS/Google/Outlook CalDAV.
- **Dev & CI**: docs/, GitHub workflows, tests/, check.sh, security_scan.py.

##### README for additional insights
- Core features: Task management, NEST+ (code editing UX), CANVAS LMS, Spotify.
- Dependencies: Python, Textual framework, requests or specific API clients for Canvas/Spotify.
- Deployment: pip and Homebrew packages—single binary/CLI entry.

##### Main components & relationships
a. **UI Layer** (TUI)
- Screens & Views (Textual)
- Widgets
–– interacts with **Application Core** via a controller/dispatcher (app.py → screens → views → widgets)
b. **Application Core**
- **Task & Schedule Manager**
- **CalDAV Sync** (abstracts Google/iOS/Outlook calendars)
- **Canvas LMS Client**
- **Spotify Client**
- Interacts with **Database Layer** to read/write local data.
c. **Database Layer**
- Local SQLite (via ticked_db.py)
- Sync operations (candaV_sync) read/write calendar events.
d. **Utilities**
- System statistics (CPU/RAM)
- Time utilities (pomodoro timer, date formatting)
e. **External Services**
- CalDAV servers (Google, Outlook, iCloud)
- Canvas LMS REST API
- Spotify Web API
f. **Configuration**
- theme.tcss, config loader – applies user preferences to UI.
g. **Documentation & CI** (separate, for developer workflow).

##### Architectural patterns & design principles
- **Clear Layering**: UI ←→ Core ←→ Data
- **Modularity**: Each integration (Canvas, Spotify, CalDAV) in its own module.
- **Event-Driven/Message Passing**: Textual framework uses events to update state & UI.
- **Separation of Concerns**: Utils vs. core vs. UI.
- **Single Responsibility**: Each view/widget has one job.

##### Putting it all together
- Off to the right, **External Services** clouds.
- Bottom: **Config & Utils** feeding into UI/Core.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Point
    App["Application Entry Point\n(app.py)"]:::entry
    click App "https://github.com/cachebag/ticked/blob/main/ticked/app.py"

    subgraph "Ticked Application"
        direction TB

        %% UI Layer
        subgraph "Textual TUI"
            direction TB
            Screen["Main Controller Screen\n(over_arching.py)"]:::ui
            click Screen "https://github.com/cachebag/ticked/blob/main/ticked/ui/screens/over_arching.py"

            subgraph "Views"
                direction TB
                CalendarView["CalendarView\n(calendar.py)"]:::ui
                click CalendarView "https://github.com/cachebag/ticked/blob/main/ticked/ui/views/calendar.py"
                CalendarSetup["CalendarSetup\n(calendar_setup.py)"]:::ui
                click CalendarSetup "https://github.com/cachebag/ticked/blob/main/ticked/ui/views/calendar_setup.py"
                CanvasView["CanvasView\n(canvas.py)"]:::ui
                click CanvasView "https://github.com/cachebag/ticked/blob/main/ticked/ui/views/canvas.py"
                NestView["NestView\n(nest.py)"]:::ui
                click NestView "https://github.com/cachebag/ticked/blob/main/ticked/ui/views/nest.py"
                PomodoroView["PomodoroView\n(pomodoro.py)"]:::ui
                click PomodoroView "https://github.com/cachebag/ticked/blob/main/ticked/ui/views/pomodoro.py"
                SettingsView["SettingsView\n(settings.py)"]:::ui
                click SettingsView "https://github.com/cachebag/ticked/blob/main/ticked/ui/views/settings.py"
                SpotifyView["SpotifyView\n(spotify.py)"]:::ui
                click SpotifyView "https://github.com/cachebag/ticked/blob/main/ticked/ui/views/spotify.py"
                SpotifyAuthView["SpotifyAuthView\n(spotify_auth.py)"]:::ui
                click SpotifyAuthView "https://github.com/cachebag/ticked/blob/main/ticked/ui/views/spotify_auth.py"
                WelcomeView["WelcomeView\n(welcome.py)"]:::ui
                click WelcomeView "https://github.com/cachebag/ticked/blob/main/ticked/ui/views/welcome.py"
            end

            Mixins["FocusMixin\n(focus_mixin.py)"]:::ui
            click Mixins "https://github.com/cachebag/ticked/blob/main/ticked/ui/mixins/focus_mixin.py"
            Widgets["TaskWidget\n(task_widget.py)"]:::ui
            click Widgets "https://github.com/cachebag/ticked/blob/main/ticked/widgets/task_widget.py"
        end

        %% Core Services
        subgraph "Core Services"
            direction TB
            TaskManager["Task & Schedule Manager"]:::core
            CaldavClient["CalDAV Sync Client"]:::core
            CanvasClient["Canvas LMS Client"]:::core
            SpotifyClient["Spotify Client"]:::core
        end

        %% Database Layer
        subgraph "Database Layer"
            direction TB
            DB["SQLite DB\n(ticked_db.py)"]:::db
            click DB "https://github.com/cachebag/ticked/blob/main/ticked/core/database/ticked_db.py"
            CaldavSync["CalDAV Sync\n(caldav_sync.py)"]:::db
            click CaldavSync "https://github.com/cachebag/ticked/blob/main/ticked/core/database/caldav_sync.py"
        end

        %% Config & Utils
        subgraph "Configuration & Utilities"
            direction TB
            ConfigInit["Config Loader\n(__init__.py)"]:::util
            click ConfigInit "https://github.com/cachebag/ticked/blob/main/ticked/config/__init__.py"
            Theme["Theme Definitions\n(theme.tcss)"]:::util
            click Theme "https://github.com/cachebag/ticked/blob/main/ticked/config/theme.tcss"
            SystemStats["System Stats\n(system_stats.py)"]:::util
            click SystemStats "https://github.com/cachebag/ticked/blob/main/ticked/utils/system_stats.py"
            TimeUtils["Time Utilities\n(time_utils.py)"]:::util
            click TimeUtils "https://github.com/cachebag/ticked/blob/main/ticked/utils/time_utils.py"
        end

        %% Internal Flows
        App -->|initializes| Screen
        Screen -->|renders| CalendarView
        Screen -->|renders| CalendarSetup
        Screen -->|renders| CanvasView
        Screen -->|renders| NestView
        Screen -->|renders| PomodoroView
        Screen -->|renders| SettingsView
        Screen -->|renders| SpotifyView
        Screen -->|renders| SpotifyAuthView
        Screen -->|renders| WelcomeView

        Screen -->|uses| Mixins
        CalendarView -->|uses| Widgets

        %% UI to Core
        Screen -->|user actions| TaskManager
        Screen -->|user actions| CaldavClient
        Screen -->|user actions| CanvasClient
        Screen -->|user actions| SpotifyClient
        PomodoroView -->|uses| TimeUtils
        Screen -->|displays stats| SystemStats

        %% Core to Database
        TaskManager -->|SQL INSERT/SELECT| DB
        CaldavClient -->|sync calls| CaldavSync
        CaldavSync -->|SQL INSERT/SELECT| DB

        %% Config Injection
        ConfigInit -->|loads preferences| Screen
        ConfigInit -->|loads preferences| TaskManager

        %% Utils Injection
        TimeUtils -->|timer| TaskManager
        SystemStats -->|metrics| Screen

        %% Core to External Services
        CaldavClient -->|CalDAV| CalDAVCloud
        CanvasClient -->|REST/OAuth2| CanvasAPI
        SpotifyClient -->|OAuth2/REST| SpotifyAPI
    end

    %% External Services
    CalDAVCloud["CalDAV Servers\n(Google, Outlook, iCloud)"]:::external
    CanvasAPI["Canvas LMS API"]:::external
    SpotifyAPI["Spotify Web API"]:::external

    %% Docs & Tests
    subgraph "Documentation & Tests"
        direction TB
        DocsCanvas["Canvas Docs\n(canvas.md)"]:::doc
        click DocsCanvas "https://github.com/cachebag/ticked/blob/main/docs/canvas.md"
        DocsNest["Nest Docs\n(nest.md)"]:::doc
        click DocsNest "https://github.com/cachebag/ticked/blob/main/docs/nest.md"
        DocsSpotify["Spotify Docs\n(spotify.md)"]:::doc
        click DocsSpotify "https://github.com/cachebag/ticked/blob/main/docs/spotify.md"
        DocsTask["Task Docs\n(task.md)"]:::doc
        click DocsTask "https://github.com/cachebag/ticked/blob/main/docs/task.md"
        TestDB["Test Database\n(test_database.py)"]:::test
        click TestDB "https://github.com/cachebag/ticked/blob/main/tests/test_database.py"
        TestNest["Test Nest\n(test_nest.py)"]:::test
        click TestNest "https://github.com/cachebag/ticked/blob/main/tests/test_nest.py"
        TestStats["Test SystemStats\n(test_system_stats.py)"]:::test
        click TestStats "https://github.com/cachebag/ticked/blob/main/tests/test_system_stats.py"
        TestUtils["Test Utils\n(test_utils.py)"]:::test
        click TestUtils "https://github.com/cachebag/ticked/blob/main/tests/test_utils.py"
    end

    %% Classes
    classDef entry fill:#f9f,stroke:#333,stroke-width:1px
    classDef ui fill:#cff,stroke:#036,stroke-width:1px
    classDef core fill:#cfc,stroke:#063,stroke-width:1px
    classDef db fill:#fcf,stroke:#963,stroke-width:1px
    classDef util fill:#eee,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
    classDef external fill:#ecc,stroke:#639,stroke-width:1px,stroke-dasharray: 2 2
    classDef doc fill:#fff2cc,stroke:#996515,stroke-width:1px
    classDef test fill:#e6e6e6,stroke:#333,stroke-width:1px
```
