# wsnh2022/dailyfocus architecture

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

- Interactive diagram: https://gitdiagram.com/wsnh2022/dailyfocus
- Repository: https://github.com/wsnh2022/dailyfocus

## Overview

1. **Application shell**
   - This is a React 18 single-page app built with Vite and Tailwind.
   - `src/main.jsx` bootstraps the app, `App.jsx` defines routing and global app setup, and `BottomNav` provides the main tab navigation.
   - The Pomodoro fullscreen view hides the bottom nav, so it behaves like a focused mode within the same SPA.

2. **Primary domain model**
   - The app is centered on three persistent record types in IndexedDB via Dexie: `task_templates`, `daily_logs`, and `pomodoro_sessions`.
   - `task_templates` are reusable task definitions, `daily_logs` are per-date task instances and day-state records, and `pomodoro_sessions` capture timer history.
   - Most UI state is a live projection of this persisted model rather than a separate backend-driven system.

3. **State management boundary**
   - Zustand (`src/store/useAppStore.js`) is the in-memory coordination layer for the active date, today’s tasks, timer IDs, toasts, and other UI flags.
   - The pattern is optimistic: the store updates first, then Dexie writes follow through query helpers in `src/db/queries.js`.
   - This keeps the app responsive while the IndexedDB layer remains the source of truth across reloads and offline use.

4. **Home screen workflow**
   - `HomeScreen` is the core operating surface: it shows the date strip, day state, momentum/streak summary, and the task list for the selected day.
   - `TaskCard` dispatches to checkbox, countdown, or Pomodoro task behavior; `SortableTaskCard` adds drag-to-reorder for pending tasks only.
   - Completed items are intentionally collapsed, so the architecture prioritizes current work over historical clutter.

5. **Date planning and midnight rollover**
   - The app supports future planning by saving pre-planned tasks into `daily_logs` with a `prePlanned` flag and `pp_`-prefixed IDs.
   - `useMidnightArchive` handles the day boundary: it merges templates and any pre-planned entries into the new active day when the date changes.
   - The 14-day date strip and heatmap both read from the same date-keyed data model, so future days and past history are just different views over the same storage.

6. **Timer subsystem**
   - `useCountdown` powers generic countdown tasks, while `usePomodoro` implements the multi-phase Pomodoro state machine.
   - A single active-timer rule is enforced app-wide via `activeTimerId` in the Zustand store.
   - Timer recovery is designed for mobile interruptions: countdowns watch visibility changes, and Pomodoro state is persisted to localStorage so it can resume after refresh or screen lock.

7. **History and streak analytics**
   - `useStreak` reads all logs and computes streak metrics and dot summaries using utilities in `src/utils/streakCalc.js`.
   - `HistoryScreen` visualizes this data with a 13-week heatmap, calendar views, and a day-detail modal.
   - The momentum bar on the home screen is effectively a lightweight analytics dashboard built from the same log data.

8. **Task creation and editing**
   - `EditorScreen` is the dedicated task-entry boundary, and it receives an optional `targetDate` from the home screen for future-date edits.
   - `TaskEditor` is the main form, supported by picker components for color, emoji, and timer type.
   - For future dates, quick-assign chips let the user clone saved task templates directly into that date’s log.

9. **Pomodoro mini-app**
   - `AppsScreen` hosts the Pomodoro app as a standalone mode rather than just a timer widget.
   - `PomodoroApp` manages task selection, phase transitions, set tracking, sound profile selection, and automatic completion of the linked task when the session finishes.
   - Sound and voice feedback are cross-cutting concerns handled by `src/utils/sound.js`, with haptics in `vibrate.js`.

10. **Backup, export, and settings**
    - `SettingsScreen` is where the user configures the app subtitle, Pomodoro sound preferences, and data maintenance actions.
    - `backupExport.js` covers JSON backup/export, CSV export for history, restore/import, and destructive clear-all flows.
    - The README’s “persistent storage” behavior matters architecturally: the app explicitly asks `navigator.storage.persist()` to reduce the risk of browser eviction of offline data.

11. **Offline/PWA and deployment**
    - This is an offline-first PWA: assets are cached by the Workbox-based PWA setup, and `public/offline.html` provides fallback behavior.
    - Icons are generated into `public/icons`, and the app is deployed to GitHub Pages through the GitHub Actions workflow in `.github/workflows/deploy.yml`.
    - The hosting/deployment model matters because the app is designed to run fully client-side with no custom server.

12. **Extra content subsystem**
    - The repo also contains a small learning/app-launcher area: `AppsScreen`, `EnglishApp`, `BookmarksApp`, and the Python learning screens under `src/components/apps/python`.
    - Python lesson content lives in `src/data/python`, with scripts like `parse-python-md.mjs` and `python_fundamentals.md` indicating a content-generation pipeline for lesson data.
    - `usePyodide` suggests the Python experience runs in-browser rather than depending on a backend, keeping it aligned with the offline-first architecture.

13. **Shared UI and cross-cutting concerns**
    - `Modal`, `Toast`, and `ErrorBoundary` are the main shared UI primitives used across screens.
    - Constants and validators in `src/constants` and `src/utils/dayStateValidator.js` enforce domain rules like day-state limits and color/day-state options.
    - This keeps validation and feedback centralized instead of duplicated across each screen.

Main entry points: [`src/App.jsx`](https://github.com/wsnh2022/dailyfocus/blob/main/src/App.jsx) (App shell), [`src/components/home/HomeScreen.jsx`](https://github.com/wsnh2022/dailyfocus/blob/main/src/components/home/HomeScreen.jsx) (Home screen), [`src/db/queries.js`](https://github.com/wsnh2022/dailyfocus/blob/main/src/db/queries.js) (Query helpers), [`src/store/useAppStore.js`](https://github.com/wsnh2022/dailyfocus/blob/main/src/store/useAppStore.js) (App store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App shell"]
  node_node_main["main.jsx<br/>entrypoint<br/>[main.jsx]"]
  node_node_app["App shell<br/>router/layout<br/>[App.jsx]"]
  node_node_bottomnav["Bottom nav<br/>navigation<br/>[BottomNav.jsx]"]
end

subgraph group_group_state["State and data"]
  node_node_store["App store<br/>zustand state<br/>[useAppStore.js]"]
  node_node_db[("Dexie DB<br/>indexeddb<br/>[schema.js]")]
  node_node_queries["Query helpers<br/>db access<br/>[queries.js]"]
end

subgraph group_group_home["Home workflow"]
  node_node_home["Home screen<br/>daily workspace<br/>[HomeScreen.jsx]"]
  node_node_taskcard["Task cards<br/>task ui<br/>[TaskCard.jsx]"]
  node_node_datestrip["Date strip<br/>date selector<br/>[DateStrip.jsx]"]
  node_node_midnight["Midnight archive<br/>day rollover"]
end

subgraph group_group_timer["Timers"]
  node_node_countdown["Countdown<br/>timer hook<br/>[useCountdown.js]"]
  node_node_pomodoro["Pomodoro hook<br/>timer state machine<br/>[usePomodoro.js]"]
end

subgraph group_group_history["History"]
  node_node_history["History screen<br/>analytics view<br/>[HistoryScreen.jsx]"]
  node_node_streak["Streak calc<br/>analytics logic<br/>[useStreak.js]"]
end

subgraph group_group_editor["Editor"]
  node_node_editor["Editor screen<br/>task editor<br/>[EditorScreen.jsx]"]
  node_node_taskeditor["Task editor<br/>form<br/>[TaskEditor.jsx]"]
end

subgraph group_group_apps["Apps"]
  node_node_apps["Apps screen<br/>launcher<br/>[AppsScreen.jsx]"]
  node_node_pomoapp["Pomodoro app<br/>mini-app<br/>[PomodoroApp.jsx]"]
  node_node_python["Python lessons<br/>content app"]
end

subgraph group_group_shared["Shared UI"]
  node_node_settings["Settings<br/>preferences<br/>[SettingsScreen.jsx]"]
  node_node_shared["Shared UI<br/>primitives<br/>[Modal.jsx]"]
  node_node_backup["Backup export<br/>data maintenance<br/>[backupExport.js]"]
  node_node_sound["Sound utils<br/>feedback<br/>[sound.js]"]
end

subgraph group_group_platform["Platform"]
  node_node_offline["Offline/PWA<br/>platform<br/>[offline.html]"]
end

node_node_main -->|"mounts"| node_node_app
node_node_app -->|"uses"| node_node_bottomnav
node_node_app -->|"routes to"| node_node_home
node_node_app -->|"routes to"| node_node_history
node_node_app -->|"routes to"| node_node_editor
node_node_app -->|"routes to"| node_node_apps
node_node_app -->|"routes to"| node_node_settings
node_node_store -->|"persists via"| node_node_queries
node_node_queries -->|"reads/writes"| node_node_db
node_node_home -->|"reads state"| node_node_store
node_node_home -->|"renders"| node_node_taskcard
node_node_home -->|"shows"| node_node_datestrip
node_node_home -->|"rolls over"| node_node_midnight
node_node_taskcard -->|"starts"| node_node_countdown
node_node_taskcard -->|"starts"| node_node_pomodoro
node_node_midnight -->|"merges logs"| node_node_queries
node_node_countdown -->|"locks active timer"| node_node_store
node_node_pomodoro -->|"locks active timer"| node_node_store
node_node_history -->|"derives metrics"| node_node_streak
node_node_streak -->|"reads logs"| node_node_queries
node_node_editor -->|"contains"| node_node_taskeditor
node_node_editor -->|"saves tasks"| node_node_queries
node_node_apps -->|"hosts"| node_node_pomoapp
node_node_apps -->|"hosts"| node_node_python
node_node_pomoapp -->|"uses"| node_node_sound
node_node_pomoapp -->|"completes tasks"| node_node_queries
node_node_settings -->|"manages data"| node_node_backup
node_node_settings -->|"configures"| node_node_sound
node_node_home -->|"uses"| node_node_shared
node_node_history -->|"uses"| node_node_shared
node_node_app -->|"ships with"| node_node_offline
node_node_backup -->|"exports/imports"| node_node_db

click node_node_main "https://github.com/wsnh2022/dailyfocus/blob/main/src/main.jsx"
click node_node_app "https://github.com/wsnh2022/dailyfocus/blob/main/src/App.jsx"
click node_node_bottomnav "https://github.com/wsnh2022/dailyfocus/blob/main/src/components/shared/BottomNav.jsx"
click node_node_store "https://github.com/wsnh2022/dailyfocus/blob/main/src/store/useAppStore.js"
click node_node_db "https://github.com/wsnh2022/dailyfocus/blob/main/src/db/schema.js"
click node_node_queries "https://github.com/wsnh2022/dailyfocus/blob/main/src/db/queries.js"
click node_node_home "https://github.com/wsnh2022/dailyfocus/blob/main/src/components/home/HomeScreen.jsx"
click node_node_taskcard "https://github.com/wsnh2022/dailyfocus/blob/main/src/components/home/TaskCard.jsx"
click node_node_datestrip "https://github.com/wsnh2022/dailyfocus/blob/main/src/components/home/DateStrip.jsx"
click node_node_midnight "https://github.com/wsnh2022/dailyfocus/blob/main/src/hooks/useMidnightArchive.js"
click node_node_countdown "https://github.com/wsnh2022/dailyfocus/blob/main/src/hooks/useCountdown.js"
click node_node_pomodoro "https://github.com/wsnh2022/dailyfocus/blob/main/src/hooks/usePomodoro.js"
click node_node_history "https://github.com/wsnh2022/dailyfocus/blob/main/src/components/history/HistoryScreen.jsx"
click node_node_streak "https://github.com/wsnh2022/dailyfocus/blob/main/src/hooks/useStreak.js"
click node_node_editor "https://github.com/wsnh2022/dailyfocus/blob/main/src/components/editor/EditorScreen.jsx"
click node_node_taskeditor "https://github.com/wsnh2022/dailyfocus/blob/main/src/components/editor/TaskEditor.jsx"
click node_node_apps "https://github.com/wsnh2022/dailyfocus/blob/main/src/components/apps/AppsScreen.jsx"
click node_node_pomoapp "https://github.com/wsnh2022/dailyfocus/blob/main/src/components/apps/PomodoroApp.jsx"
click node_node_python "https://github.com/wsnh2022/dailyfocus/blob/main/src/components/apps/python/PythonLvl1Screen.jsx"
click node_node_settings "https://github.com/wsnh2022/dailyfocus/blob/main/src/components/settings/SettingsScreen.jsx"
click node_node_shared "https://github.com/wsnh2022/dailyfocus/blob/main/src/components/shared/Modal.jsx"
click node_node_backup "https://github.com/wsnh2022/dailyfocus/blob/main/src/utils/backupExport.js"
click node_node_sound "https://github.com/wsnh2022/dailyfocus/blob/main/src/utils/sound.js"
click node_node_offline "https://github.com/wsnh2022/dailyfocus/blob/main/public/offline.html"

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_node_main,node_node_app,node_node_bottomnav,node_node_apps,node_node_pomoapp,node_node_python toneBlue
class node_node_store,node_node_db,node_node_queries,node_node_settings,node_node_shared,node_node_backup,node_node_sound toneAmber
class node_node_home,node_node_taskcard,node_node_datestrip,node_node_midnight,node_node_offline toneMint
class node_node_countdown,node_node_pomodoro toneRose
class node_node_history,node_node_streak toneIndigo
class node_node_editor,node_node_taskeditor toneTeal
```

## Components

### App shell

React/Vite entrypoints and global navigation.

- [main.jsx](https://github.com/wsnh2022/dailyfocus/blob/main/src/main.jsx): entrypoint · Bootstraps the React app. · `src/main.jsx`
- [App shell](https://github.com/wsnh2022/dailyfocus/blob/main/src/App.jsx): router/layout · Defines routing and global app setup. · `src/App.jsx`
- [Bottom nav](https://github.com/wsnh2022/dailyfocus/blob/main/src/components/shared/BottomNav.jsx): navigation · Primary tab navigation, hidden in focused Pomodoro mode. · `src/components/shared/BottomNav.jsx`

### State and data

Client-side persistence and in-memory coordination.

- [App store](https://github.com/wsnh2022/dailyfocus/blob/main/src/store/useAppStore.js): zustand state · In-memory coordination for active date, timer IDs, toasts, and UI flags. · `src/store/useAppStore.js`
- [Dexie DB](https://github.com/wsnh2022/dailyfocus/blob/main/src/db/schema.js): indexeddb · Persistent client-side storage for templates, daily logs, and sessions. · `src/db/schema.js`
- [Query helpers](https://github.com/wsnh2022/dailyfocus/blob/main/src/db/queries.js): db access · Read/write helpers that sync optimistic state to IndexedDB. · `src/db/queries.js`

### Home workflow

Core daily planning and task execution surface.

- [Home screen](https://github.com/wsnh2022/dailyfocus/blob/main/src/components/home/HomeScreen.jsx): daily workspace · Core surface for date, day state, momentum, and tasks. · `src/components/home/HomeScreen.jsx`
- [Task cards](https://github.com/wsnh2022/dailyfocus/blob/main/src/components/home/TaskCard.jsx): task ui · Checkbox, countdown, and Pomodoro task behaviors; sortable for pending items. · `src/components/home/TaskCard.jsx`
- [Date strip](https://github.com/wsnh2022/dailyfocus/blob/main/src/components/home/DateStrip.jsx): date selector · 14-day planning strip over the same date-keyed records. · `src/components/home/DateStrip.jsx`
- [Midnight archive](https://github.com/wsnh2022/dailyfocus/blob/main/src/hooks/useMidnightArchive.js): day rollover · Merges templates and pre-planned entries when the active date changes. · `src/hooks/useMidnightArchive.js`

### Timers

Countdown and Pomodoro timer logic.

- [Countdown](https://github.com/wsnh2022/dailyfocus/blob/main/src/hooks/useCountdown.js): timer hook · Generic countdown timer with visibility recovery. · `src/hooks/useCountdown.js`
- [Pomodoro hook](https://github.com/wsnh2022/dailyfocus/blob/main/src/hooks/usePomodoro.js): timer state machine · Multi-phase Pomodoro logic with persisted recovery. · `src/hooks/usePomodoro.js`

### History

Streaks, calendars, and log visualization.

- [History screen](https://github.com/wsnh2022/dailyfocus/blob/main/src/components/history/HistoryScreen.jsx): analytics view · Heatmaps, calendars, and day detail for log history. · `src/components/history/HistoryScreen.jsx`
- [Streak calc](https://github.com/wsnh2022/dailyfocus/blob/main/src/hooks/useStreak.js): analytics logic · Computes streak metrics and dot summaries from logs. · `src/hooks/useStreak.js`

### Editor

Task creation and future-date editing.

- [Editor screen](https://github.com/wsnh2022/dailyfocus/blob/main/src/components/editor/EditorScreen.jsx): task editor · Dedicated task-entry boundary, including future-date edits. · `src/components/editor/EditorScreen.jsx`
- [Task editor](https://github.com/wsnh2022/dailyfocus/blob/main/src/components/editor/TaskEditor.jsx): form · Main task form with color, emoji, and timer type pickers. · `src/components/editor/TaskEditor.jsx`

### Apps

Standalone mini-apps and learning content.

- [Apps screen](https://github.com/wsnh2022/dailyfocus/blob/main/src/components/apps/AppsScreen.jsx): launcher · Hosts standalone mini-apps, including Pomodoro and learning apps. · `src/components/apps/AppsScreen.jsx`
- [Pomodoro app](https://github.com/wsnh2022/dailyfocus/blob/main/src/components/apps/PomodoroApp.jsx): mini-app · Standalone Pomodoro mode with task linking, phases, sets, and completion. · `src/components/apps/PomodoroApp.jsx`
- [Python lessons](https://github.com/wsnh2022/dailyfocus/blob/main/src/components/apps/python/PythonLvl1Screen.jsx): content app · In-browser Python learning experience backed by local lesson data. · `src/components/apps/python/PythonLvl1Screen.jsx`

### Shared UI

Cross-cutting primitives and settings.

- [Settings](https://github.com/wsnh2022/dailyfocus/blob/main/src/components/settings/SettingsScreen.jsx): preferences · Subtitle, sound preferences, and data maintenance actions. · `src/components/settings/SettingsScreen.jsx`
- [Shared UI](https://github.com/wsnh2022/dailyfocus/blob/main/src/components/shared/Modal.jsx): primitives · Modal, toast, and error boundary used across screens. · `src/components/shared/Modal.jsx`
- [Backup export](https://github.com/wsnh2022/dailyfocus/blob/main/src/utils/backupExport.js): data maintenance · JSON backup/export, CSV export, restore/import, and clear-all flows. · `src/utils/backupExport.js`
- [Sound utils](https://github.com/wsnh2022/dailyfocus/blob/main/src/utils/sound.js): feedback · Audio, voice, and haptic feedback helpers. · `src/utils/sound.js`

### Platform

Offline/PWA packaging, export, and deployment.

- [Offline/PWA](https://github.com/wsnh2022/dailyfocus/blob/main/public/offline.html): platform · Workbox caching, offline fallback, and client-side deployment model. · `public/offline.html`

## Connections

- main.jsx → App shell: mounts · Boot entry renders the application shell.
- App shell → Bottom nav: uses · Shell provides global tab navigation.
- App shell → Home screen: routes to · Primary route lands on the home workspace.
- App shell → History screen: routes to · History is a main top-level view.
- App shell → Editor screen: routes to · Editor is a dedicated screen.
- App shell → Apps screen: routes to · Apps screen hosts extra modes.
- App shell → Settings: routes to · Settings is a top-level screen.
- App store → Query helpers: persists via · Optimistic UI state is written through query helpers.
- Query helpers → Dexie DB: reads/writes · Queries are the persistence boundary over IndexedDB.
- Home screen → App store: reads state · Home consumes active date and UI flags from the store.
- Home screen → Task cards: renders · Tasks are presented as interactive cards.
- Home screen → Date strip: shows · Date strip drives day selection.
- Home screen → Midnight archive: rolls over · Day boundary logic refreshes the active log.
- Task cards → Countdown: starts · Countdown tasks delegate to the countdown hook.
- Task cards → Pomodoro hook: starts · Pomodoro tasks delegate to the Pomodoro hook.
- Midnight archive → Query helpers: merges logs · New day setup reads and writes persisted daily records.
- Countdown → App store: locks active timer · Single active-timer rule is enforced through store state.
- Pomodoro hook → App store: locks active timer · Pomodoro shares the global active-timer boundary.
- History screen → Streak calc: derives metrics · History view is built from streak and summary calculations.
- Streak calc → Query helpers: reads logs · Analytics are computed from persisted daily logs.
- Editor screen → Task editor: contains · Screen hosts the task form workflow.
- Editor screen → Query helpers: saves tasks · Task edits are committed through database helpers.
- Apps screen → Pomodoro app: hosts · Pomodoro runs as a standalone app mode.
- Apps screen → Python lessons: hosts · Learning content is exposed through the apps launcher.
- Pomodoro app → Sound utils: uses · Pomodoro app triggers audio and haptic feedback.
- Pomodoro app → Query helpers: completes tasks · Session completion updates the linked task and logs.
- Settings → Backup export: manages data · Settings exposes backup, restore, export, and clearing.
- Settings → Sound utils: configures · Sound preferences are set from the settings surface.
- Home screen → Shared UI: uses · Shared primitives support overlays and feedback.
- History screen → Shared UI: uses · History uses shared modal and error handling.
- App shell → Offline/PWA: ships with · The app is designed to run offline-first as a PWA.
- Backup export → Dexie DB: exports/imports · Backup flows operate on persisted local data.