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

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

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.