Initial commit

.junie/plans/time-tracking-pwa-setup.md

@@ -0,0 +1,103 @@
+# Requirements
+
+### Overview & Goals
+Build an offline-first PWA for construction workers to track time quickly and easily on-site.
+
+### User Stories
+- As a worker, I want to quickly log my time (start/end, task, client) so that I don't lose time during my workday.
+- As a worker, I want the app to suggest previous clients/tasks so I don't have to re-type everything.
+- As a worker, I want to copy my previous day's report so I can quickly start a new day.
+- As a worker, I want to use the app without an internet connection so that I can work in remote areas.
+- As a worker, I want the app to be readable and usable in all lighting conditions and with messy hands/gloves.
+- As a worker, I want the summary of my previous day to be read-only so I don't accidentally modify it.
+- As a worker, I want to configure how long historical reports are kept, while ensuring the last day's report is always available.
+
+### Functional Requirements
+- Log time entry (Start time, End time, Task name, Client name).
+- Suggest frequent/recent values for Task and Client.
+- View previous day's report and copy it to current day.
+- Offline-first storage (IndexedDB).
+- PWA installable on mobile devices.
+- High-contrast, easy-to-use mobile UI (large hit targets).
+- Previous day report is read-only.
+- Configurable retention time for historical reports in Settings.
+- Retention policy ensures the most recent report is never deleted.
+
+# Technical Design
+
+### Technical Stack
+- **Framework**: Svelte
+- **Build Tool**: Vite
+- **Database**: IndexedDB (via `Dexie.js`)
+- **PWA**: `vite-plugin-pwa` (Service Worker)
+
+### Key Decisions
+- **Offline-first**: All data stored locally using `Dexie.js`/IndexedDB. No backend required.
+- **UI Design**: Minimalist design with large touch targets for easy use with gloves.
+- **Svelte Stores**: For local state management within the app.
+- **Data Retention**: Periodic cleanup of logs based on user-defined retention policy, excluding the latest day.
+- **Read-Only UI**: Dedicated components or read-only mode for historical reports.
+
+### File Structure
+- `src/lib/db.js` — Database setup, Dexie instance, and retention cleanup logic.
+- `src/lib/stores/` — Svelte stores for app state.
+- `src/components/` — Reusable UI components.
+- `src/routes/` — Application pages (Input, Summary, Settings).
+
+### Architecture Diagram
+```mermaid
+graph LR
+    UI[Svelte UI] -->|Read/Write| State[Svelte Stores]
+    State -->|Persist| DB[(IndexedDB)]
+    SW[Service Worker] -->|Cache| UI
+    DB -->|Read| UI
+```
+
+# Testing
+
+### Validation Approach
+- Verify PWA manifest installation.
+- Test offline functionality (turn off network, reload).
+- Test CRUD operations on time logs in offline mode.
+- Verify UI responsiveness and touch-target size on simulated mobile view.
+
+### Key Scenarios
+- Adding a time log entry while offline.
+- Suggesting a previously added client.
+- Copying yesterday's entries to today.
+- Verifying data persists after browser refresh.
+
+# Delivery Steps
+
+### ✓ Step 1: Setup Project and PWA Infrastructure
+Initialize the project and configure PWA capabilities.
+- Set up a Svelte project with Vite.
+- Configure `vite-plugin-pwa` for offline support (manifest, service worker).
+- Setup essential project structure (directories for components, stores, services, models).
+
+### ✓ Step 2: Implement Local Database and Data Models
+Implement the local database layer and data models.
+- Set up `Dexie.js` for IndexedDB management.
+- Define data models for reports, clients, tasks, and historical data.
+- Create service methods to handle CRUD operations on the local database and retention policy settings.
+
+### ✓ Step 3: Develop Core UI and Input Features
+Develop core UI components and input forms.
+- Build the main input screen for adding time logs (designed for large touch targets).
+- Create a list view to display the current day's entries.
+- Implement the 'Copy from Yesterday' functionality.
+- Ensure the UI is responsive, high-contrast, and optimized for mobile usage.
+
+### * Step 4: Implement Features and Data Logic
+Implement automatic suggestions, retention logic, and read-only views.
+- Integrate logic to suggest recent/frequent clients and tasks based on previous entries.
+- Implement sorting and filtering for the \"summary\" view of the previous day.
+- Add read-only enforcement for historical reports.
+- Implement data cleanup job based on user-defined retention policy.
+- Add basic data validation and formatting to ensure error-free entry.
+
+###   Step 5: Final Polish and UX Optimization
+Perform UI polish and accessibility testing.
+- Optimize the interface for usability with gloves/messy hands (e.g., larger tap areas).
+- Add high-contrast mode or ensure default theme is clear.
+- Perform final testing of offline behavior and PWA installation.