wsnh2022/dailyfocus

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.