# jerryzliu/dayflow architecture

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

- Interactive diagram: https://gitdiagram.com/jerryzliu/dayflow
- Repository: https://github.com/jerryzliu/dayflow

## Overview

##### File structure
- Top-level directories:
- Dayflow/ — the Xcode project and all Swift source code
- docs/ — documentation, AppCast, images, hero assets
- scripts/ — release automation (DMG creation, Sparkle signing, appcast updates)
- .github/ — issue templates
- Inside Dayflow/Dayflow:
- App/ — SwiftUI entry points (AppDelegate, DayflowApp, AppState, InactivityMonitor)
- Core/ — capture (Recording), analysis orchestration (AnalysisManager, TimeParsing), AI provider interfaces (LLMService, GeminiDirectProvider, OllamaProvider, etc.), networking (FaviconService), security (KeychainManager), thumbnails, storage managers
- Models/ — data models for timeline cards and categories
- Views/ — SwiftUI MVVM layers: Components, Onboarding flows, UI screens (DashboardView, JournalView, SettingsView, etc.)
- System/ — low-level macOS integrations (StatusBarController, SilentUserDriver, UpdaterManager, HardwareInfo)
- Utilities/ — coloring, logging, Sentry, Gemini API helpers

##### Key insights from README
- Four main pipeline phases: Capture → Analyze → Generate → Display → Cleanup
- Two AI modes: Gemini (cloud calls) vs. Local (Ollama/LM Studio endpoint)
- Storage: video chunks on disk + chunks.sqlite for metadata
- Permissions: Screen & Audio Recording
- Auto-updates via Sparkle

A. Frontend / UI layer
- DayflowApp (SwiftUI) + AppDelegate → drives AppState
- Views: TimelineDashboard, JournalView, SettingsView, OnboardingFlow
B. Capture engine
- ActiveDisplayTracker + ScreenRecorder → produce 15-second .mp4 chunks at 1 FPS
- StorageManager / TimelapseStorageManager → writes video files to disk
C. Scheduling & cleanup
- InactivityMonitor / AppState scheduler → every 15 min trigger AnalysisManager
- StoragePreferences + CleanupService → auto-delete >3-day-old files
D. Analysis pipeline
- AnalysisManager + TimeParsing → batch recent video chunks
- LLMService (abstract protocol) → selects GeminiDirectProvider or OllamaProvider
- Gemini flow: single upload+transcribe call + generate cards call
- Local flow: extract frames → 30 LLM calls → merges & title generation calls
- LLMLogger → logs requests/responses (for debug/Sentry)
E. Data layer
- chunks.sqlite (SQLite) for card metadata and timeline entries
- FaviconService for website thumbnail lookups
- ThumbnailCache for UI thumbnails
F. External services
- Gemini API (cloud)
- Local LLM server (Ollama / LM Studio endpoint)
- Sparkle AppCast feed & signing service
G. System integrations
- KeychainManager for storing API keys
- UpdaterManager (Sparkle) for auto-update checks
- SilentUserDriver to interact with macOS sandbox/permissions
- HardwareInfo for device-specific tuning

##### Relationships & data flow
1. User launches DayflowApp → AppState initializes components (Recorder, Scheduler, UI)
2. ScreenRecorder captures frames → StorageManager writes chunks to disk
3. Scheduler (every 15 min) → AnalysisManager assembles video chunks
4. AnalysisManager → LLMService → chosen AI provider → returns timeline cards
5. AnalysisManager writes card metadata → SQLite
6. SwiftUI views observe AppState/Database → render timeline cards + thumbnails
7. InactivityMonitor + CleanupService periodically purge old chunks
8. UpdaterManager (in background) fetches appcast.xml → Sparkle handles new releases

##### Architectural patterns & design principles
- MVVM: SwiftUI Views bind to AppState / ObservableObjects
- Service/Provider pattern: LLMService protocol with pluggable providers (Gemini, Ollama)
- Layered architecture: UI → Application (AppState, Scheduler) → Core services → Data → External
- Separation of concerns: capture, analysis, storage, UI, external integration are modular
- Dependency injection via environment (GEMINI_API_KEY, local endpoint)

##### Don’t over-engineer—capture every logical component
- Even small utilities (KeychainManager, FaviconService) deserve representation if they play a role in overall flow
- Onboarding flow as a startup path before the regular pipeline

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "UI Layer"
    DayflowApp["DayflowApp"]:::ui
    AppDelegate["AppDelegate"]:::ui
    StatusBarController["StatusBarController"]:::ui
    DashboardView["DashboardView"]:::ui
    JournalView["JournalView"]:::ui
    SettingsView["SettingsView"]:::ui
    OnboardingFlow["OnboardingFlow"]:::ui
  end

  subgraph "Application Layer"
    AppState["AppState"]:::app
    InactivityMonitor["InactivityMonitor"]:::app
    UpdaterManager["UpdaterManager"]:::app
  end

  subgraph "Core Layer"
    subgraph "Recording Engine"
      ActiveDisplayTracker["ActiveDisplayTracker"]:::core
      ScreenRecorder["ScreenRecorder"]:::core
      StorageManager["StorageManager"]:::core
      TimelapseStorageManager["TimelapseStorageManager"]:::core
      StoragePreferences["StoragePreferences"]:::core
      VideoProcessingService["VideoProcessingService"]:::core
    end
    subgraph "Analysis Pipeline"
      AnalysisManager["AnalysisManager"]:::core
      TimeParsing["TimeParsing"]:::core
    end
    subgraph "AI Services"
      LLMService["LLMService"]:::core
      GeminiDirectProvider["GeminiDirectProvider"]:::core
      OllamaProvider["OllamaProvider"]:::core
      DayflowBackendProvider["DayflowBackendProvider"]:::core
      LLMLogger["LLMLogger"]:::core
    end
    subgraph "Networking & Thumbnails"
      FaviconService["FaviconService"]:::core
      ThumbnailCache["ThumbnailCache"]:::core
      KeychainManager["KeychainManager"]:::core
    end
  end

  subgraph "Data Layer"
    VideoStorage["Video Storage (Disk)"]:::data
    chunksDB["chunks.sqlite"]:::data
  end

  subgraph "External Interfaces"
    GeminiAPI["Gemini API"]:::ext
    LocalLLM["Local LLM Server"]:::ext
    AppCastFeed["AppCast Feed"]:::ext
  end

  AppDelegate -->|on launch| DayflowApp
  DayflowApp --> AppState
  AppState --> StatusBarController
  AppState --> DashboardView
  AppState --> OnboardingFlow
  AppState --> InactivityMonitor
  AppState --> UpdaterManager

  ActiveDisplayTracker --> ScreenRecorder
  ScreenRecorder -->|writes chunks| StorageManager
  StorageManager --> VideoStorage
  TimelapseStorageManager --> VideoStorage
  StoragePreferences --> StorageManager
  VideoProcessingService --> StorageManager

  InactivityMonitor -->|every 15min| AnalysisManager
  AnalysisManager --> TimeParsing
  AnalysisManager --> LLMService
  LLMService --> GeminiDirectProvider
  LLMService --> OllamaProvider
  LLMService --> DayflowBackendProvider
  LLMService --> LLMLogger
  GeminiDirectProvider -->|cloud call| GeminiAPI
  OllamaProvider -->|local calls| LocalLLM
  DayflowBackendProvider -->|backend| LocalLLM

  AnalysisManager --> chunksDB
  FaviconService --> chunksDB
  ThumbnailCache --> chunksDB
  DashboardView --> chunksDB
  JournalView --> chunksDB
  DashboardView --> ThumbnailCache
  JournalView --> ThumbnailCache

  UpdaterManager --> AppCastFeed
  KeychainManager --> LLMService

  click DayflowApp "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/App/DayflowApp.swift"
  click AppDelegate "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/App/AppDelegate.swift"
  click AppState "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/App/AppState.swift"
  click InactivityMonitor "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/App/InactivityMonitor.swift"
  click StatusBarController "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/System/StatusBarController.swift"
  click DashboardView "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Views/UI/DashboardView.swift"
  click JournalView "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Views/UI/JournalView.swift"
  click SettingsView "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Views/UI/SettingsView.swift"
  click OnboardingFlow "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Views/Onboarding/OnboardingFlow.swift"
  click ActiveDisplayTracker "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/Recording/ActiveDisplayTracker.swift"
  click ScreenRecorder "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/Recording/ScreenRecorder.swift"
  click StorageManager "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/Recording/StorageManager.swift"
  click TimelapseStorageManager "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/Recording/TimelapseStorageManager.swift"
  click StoragePreferences "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/Recording/StoragePreferences.swift"
  click VideoProcessingService "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/Recording/VideoProcessingService.swift"
  click AnalysisManager "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/Analysis/AnalysisManager.swift"
  click TimeParsing "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/Analysis/TimeParsing.swift"
  click LLMService "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/AI/LLMService.swift"
  click GeminiDirectProvider "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/AI/GeminiDirectProvider.swift"
  click OllamaProvider "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/AI/OllamaProvider.swift"
  click DayflowBackendProvider "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/AI/DayflowBackendProvider.swift"
  click LLMLogger "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/AI/LLMLogger.swift"
  click FaviconService "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/Net/FaviconService.swift"
  click ThumbnailCache "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/Thumbnails/ThumbnailCache.swift"
  click KeychainManager "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/Core/Security/KeychainManager.swift"
  click UpdaterManager "https://github.com/jerryzliu/dayflow/blob/main/Dayflow/Dayflow/System/UpdaterManager.swift"

  classDef ui fill:#add8e6,stroke:#000,stroke-width:1px
  classDef app fill:#b0e0e6,stroke:#000,stroke-width:1px
  classDef core fill:#98fb98,stroke:#0a0,stroke-width:1px
  classDef data fill:#ffe4b5,stroke:#aa5500,stroke-width:1px
  classDef ext fill:#ffd700,stroke:#c68700,stroke-width:1px
```
