books/docs/prd/epic-5-pwa-features-production-readiness.md

Epic 5: PWA Features & Production Readiness

Epic Goal: Transform the application into a fully functional Progressive Web App with offline support, installability, and mobile optimizations, then finalize production deployment to Coolify to deliver a complete, production-ready MVP.

Story 5.1: PWA Manifest & Service Worker Setup

As a user, I want the app to be installable on my mobile device, so that it feels like a native app and is easily accessible from my home screen.

Acceptance Criteria:

1. PWA manifest file created in frontend/public/manifest.json:
   • App name: "Book Reading Tracker" (or final name)
   • Short name: "ReadTrack" (or similar)
   • Description, theme color, background color
   • Icons for various sizes (192x192, 512x512 minimum)
   • display: "standalone" for app-like experience
   • start_url: "/" and scope: "/"
2. vite-plugin-pwa configured in vite.config.js
3. Service worker generated for offline caching
4. Static assets (JS, CSS, images) cached for offline access
5. API responses cached with network-first or cache-first strategy where appropriate
6. "Add to Home Screen" prompt appears on supported browsers
7. App icon and splash screen display when launched from home screen
8. Service worker updates automatically when new version deployed
9. App works offline (cached pages accessible, with graceful degradation for API calls)
10. PWA audit (Lighthouse) passes with score >80

Story 5.2: Offline Support & Sync Strategy

As a user, I want to log reading progress even when offline, so that I don't lose data if I don't have internet connection.

Acceptance Criteria:

1. Service worker caches critical app shell (HTML, CSS, JS)
2. Reading logs can be entered offline and stored in IndexedDB (or similar local storage)
3. When connection restored, queued logs sync to backend API automatically
4. UI indicates when user is offline (banner or icon)
5. UI indicates when data is being synced
6. Conflicts handled gracefully (e.g., if same book/date logged offline then online)
7. User can view previously loaded book list and progress data offline
8. Search for new books disabled offline (requires API call)
9. Offline mode tested on mobile devices (airplane mode)

Story 5.3: Mobile Responsiveness & Touch Optimization

As a user, I want the app to work smoothly on my phone with touch-friendly interactions, so that it's easy to use on small screens.

Acceptance Criteria:

1. All screens tested and responsive on screen sizes: 320px, 375px, 414px, 768px, 1024px, 1920px
2. Touch targets minimum 44x44px for all interactive elements (buttons, links, inputs)
3. Form inputs use appropriate input types (type="number" for page numbers, type="date" for dates)
4. Mobile keyboards optimized (numeric keyboard for page input)
5. Scroll behavior smooth and natural on mobile (no janky scrolling)
6. No horizontal scrolling on mobile (all content fits within viewport)
7. Text readable without zooming (minimum 16px font size for body text)
8. Images and covers optimized for mobile (lazy loading, appropriate sizes)
9. Pull-to-refresh works on home screen for updating book list
10. Tested on real devices: iOS (iPhone) and Android

Story 5.4: Performance Optimization

As a user, I want the app to load quickly and respond instantly, so that I can log my progress without waiting.

Acceptance Criteria:

1. Lighthouse performance score >80 on mobile, >90 on desktop
2. First Contentful Paint <1.5 seconds on 3G connection
3. Time to Interactive <3 seconds on 3G connection
4. Frontend bundle size <500KB (gzipped)
5. Images optimized (compressed, appropriate formats, lazy loaded)
6. API responses compressed (gzip enabled on backend)
7. Critical CSS inlined or loaded first
8. Non-critical JavaScript lazy loaded
9. Database queries optimized (indexes used, no N+1 queries)
10. API response times <200ms for common endpoints (GET /api/books, POST /api/books/:id/logs)

Story 5.5: Error Handling & User Feedback

As a user, I want clear error messages and feedback when something goes wrong, so that I understand what happened and how to fix it.

Acceptance Criteria:

1. All API errors return user-friendly error messages (not technical stack traces)
2. Frontend displays error messages in a consistent UI pattern (toast notifications, inline errors)
3. Network errors handled gracefully ("Unable to connect. Please check your internet connection.")
4. Validation errors show specific field-level feedback ("Deadline must be in the future")
5. Loading states shown for all async operations (spinners, skeleton screens)
6. Success feedback shown after actions (e.g., "Book added!" or "Progress logged!")
7. 404 errors handled with "Not Found" page and navigation back to home
8. 500 errors handled with "Something went wrong" message and retry option
9. Empty states provide clear CTAs ("No books yet. Add your first book!")
10. Offline state clearly communicated to user

Story 5.6: Production Deployment to Coolify

As a developer, I want the application deployed to Coolify production environment, so that it's accessible to the user via a public URL with HTTPS.

Acceptance Criteria:

1. Coolify project configured with:
   • Frontend container (serving React build via nginx or similar)
   • Backend container (Node.js Express API)
   • PostgreSQL database container
2. Environment variables configured in Coolify (DATABASE_URL, API URL, etc.)
3. Database migrations run successfully on production database
4. HTTPS enabled via Coolify (automatic SSL with Let's Encrypt)
5. Custom domain configured (if applicable) or Coolify subdomain used
6. Health check endpoints monitored (/api/health)
7. Application accessible via public URL
8. PWA installable from production URL
9. Database backups configured (automated via Coolify PostgreSQL management)
10. Deployment documented in docs/deployment.md with rollback procedure

Story 5.7: Testing & Quality Assurance

As a developer, I want comprehensive testing to ensure the MVP works correctly, so that we can ship a reliable product.

Acceptance Criteria:

1. Unit tests written for:
   • Frontend: Pace calculation logic, form validation, utility functions
   • Backend: API endpoints, paceCalculationService, openLibraryService
2. Integration tests written for:
   • All backend API endpoints with test database
   • Frontend API integration (mocked backend responses)
3. Test coverage >70% for critical business logic (pace calculation, logging, validation)
4. Manual testing checklist completed:
   • Add book flow (search, select, set deadline, add)
   • Log progress flow (tap book, enter page, save)
   • View book list with progress metrics
   • View calendar with logged days
   • Install PWA on mobile device
   • Use app offline, sync when online
   • Responsive design on multiple screen sizes
5. Cross-browser testing completed (Chrome, Safari, Firefox on desktop; Safari iOS, Chrome Android)
6. Accessibility testing (keyboard navigation, screen reader basics)
7. Performance testing (Lighthouse audits pass thresholds)
8. Critical bugs fixed, known issues documented

---