Progressive Web App (PWA)

Purpose and Scope

This document describes the Progressive Web App implementation for TalentSync, which provides offline capabilities, app-like installation experience, and optimized asset caching for the Next.js frontend. The PWA layer is built using next-pwa with Workbox, generating a service worker that intercepts network requests and implements sophisticated caching strategies.

For information about the Next.js frontend application structure, see Frontend Architecture. For deployment and build processes, see Deployment & Infrastructure.

PWA Configuration

The PWA is configured in frontend/next.config.js1-6 using the next-pwa wrapper around Workbox. The configuration is applied as a higher-order function wrapping the Next.js configuration.

Configuration Parameters:

Sources: frontend/next.config.js1-6 frontend/package.json68

Service Worker Architecture

The service worker is generated during the Next.js build process and outputs to frontend/public/sw.js It uses Workbox 6.6.0 for service worker functionality, with a companion library at frontend/public/workbox-1bb06f5e.js

Core Behaviors:

1. Installation Phase: Precaches all static assets listed in the build manifest
2. Activation Phase: Claims all clients immediately and cleans up outdated caches
3. Fetch Phase: Intercepts network requests and applies caching strategies based on route patterns
4. Message Handling: Supports CACHE_URLS message type for runtime caching

Sources: frontend/public/sw.js1 frontend/public/workbox-1bb06f5e.js1

Caching Strategies

The service worker implements multiple caching strategies optimized for different asset types. Each strategy is registered as a route pattern using e.registerRoute().

Strategy Details

NetworkFirst Strategy

Used for critical paths and dynamic data that should be fresh:

CacheFirst Strategy

Used for immutable assets that rarely change:

StaleWhileRevalidate Strategy

Used for assets that can be served stale while updating in background:

Cross-Origin Strategy

Cross-origin requests use NetworkFirst with shorter cache duration:

Sources: frontend/public/sw.js1

Asset Precaching

During the build process, next-pwa generates a manifest of all static assets to be precached. These assets are cached during the service worker installation phase.

Precached Asset Categories

Precache Implementation

The service worker uses e.precacheAndRoute() to register all build assets:

// From sw.js (minified)
e.precacheAndRoute([
  {url:"/_next/app-build-manifest.json",revision:"..."},
  {url:"/_next/static/chunks/framework-*.js",revision:"..."},
  // ... hundreds of other assets
  {url:"/manifest.json",revision:"..."}
], {ignoreURLParametersMatching:[]})

Key Features:

• Each asset includes a revision hash for cache busting
• Assets are downloaded and cached during service worker installation
• Failed precache downloads cause installation to fail
• Updates trigger new service worker installation with updated assets

Sources: frontend/public/sw.js1

Offline Capabilities

The PWA provides comprehensive offline support through multiple mechanisms:

Offline Scenarios

Fully Supported Offline:

• Previously visited pages (from next-data cache)
• All precached static assets (JS, CSS, fonts, images)
• Start URL / always available
• Static images and media files (up to cache limits)

Limited Offline Support:

• API requests (if previously cached, max 16 entries)
• Dynamic data (up to 1 day cache age)

Not Available Offline:

• Authentication endpoints (/api/auth/* excluded from caching)
• Fresh data requiring real-time updates
• User-specific content not previously loaded

Sources: frontend/public/sw.js1

PWA Manifest and Icons

The PWA manifest defines the app's appearance when installed on a device.

Manifest Structure

Icon Requirements:

• 192x192 for Android home screen
• 512x512 for splash screen
• SVG for scalability
• All icons located in /public/icons/

Install Behavior:

• display: standalone - App opens without browser UI
• start_url: / - Opens to landing page on launch
• Platform-specific install prompts handled by browser

Sources: frontend/public/sw.js1 (precache list shows manifest.json and icon files)

Build and Deployment Integration

The PWA generation is integrated into the Next.js build pipeline and deployment workflow.

Build Process Steps

1. Pre-build: Prisma client generation frontend/package.json7
2. Build: next build command with next-pwa wrapper frontend/package.json7
3. PWA Generation:
   • next-pwa analyzes build output
   • Generates precache manifest with all static assets
   • Creates sw.js with Workbox configuration
   • Copies Workbox runtime library
4. Docker Build: Assets copied to production image
5. Deployment: Containers restarted, new service worker deployed

Service Worker Updates

When new code is deployed:

1. Browser detects new sw.js file (different hash)
2. New service worker installs in background
3. skipWaiting: true forces immediate activation
4. Old caches cleaned via cleanupOutdatedCaches()
5. New precache manifest downloaded
6. Page automatically uses updated assets

Sources: frontend/next.config.js1-6 frontend/package.json7 .github/workflows/deploy.yaml35-39

Service Worker Registration

While next-pwa handles automatic registration, the registration happens client-side when the Next.js application loads.

Registration Flow

Registration Configuration:

• Automatic registration via register: true frontend/next.config.js3
• Immediate activation via skipWaiting: true frontend/next.config.js4
• Scope: / (entire application)
• Update check: On navigation and periodically

Sources: frontend/next.config.js1-6

Cache Management

The service worker implements sophisticated cache management to prevent unlimited storage growth.

Cache Expiration Policies

Cache Cleanup

The service worker implements automatic cleanup:

1. On Activation: cleanupOutdatedCaches() removes old versioned caches
2. On Storage Pressure: Quota exceeded errors trigger emergency cleanup
3. On Update: New precache replaces old precache entries
4. Periodic: Expiration plugin checks timestamps and entry counts

Implementation: ExpirationPlugin from Workbox handles automated cleanup based on the configured limits.

Sources: frontend/public/sw.js1

API Request Handling

API requests are handled with a custom route matcher that excludes authentication endpoints from caching.

API Route Patterns

Excluded from Caching:

• /api/auth/[...nextauth] - NextAuth session management
• /api/auth/register - User registration
• /api/auth/verify-email - Email verification
• /api/auth/reset-password - Password reset
• /api/auth/delete-account - Account deletion
• All other /api/auth/* routes

Cached with NetworkFirst:

• /api/analysis - Resume analysis results
• /api/ats - ATS evaluation
• /api/cold-mail - Cold email generation
• /api/resumes/* - Resume data
• /api/dashboard - Dashboard statistics
• All other non-auth API routes

Configuration:

• Network timeout: 10 seconds
• Cache name: apis
• Max entries: 16
• Max age: 86400 seconds (1 day)

Sources: frontend/public/sw.js1

Development vs Production Behavior

The PWA behaves differently in development and production environments:

Development Mode Detection: frontend/next.config.js5

disable: process.env.NODE_ENV === "development"

This prevents caching issues during development where frequent file changes would conflict with service worker caching.

Sources: frontend/next.config.js1-6

Summary

The TalentSync PWA implementation provides:

1. Automated Generation: Service worker automatically generated during Next.js build via next-pwa
2. Intelligent Caching: Multiple strategies (NetworkFirst, CacheFirst, StaleWhileRevalidate) optimized for different asset types
3. Offline Support: Precached assets and runtime caching enable core functionality offline
4. Automatic Updates: Service worker updates seamlessly when new versions deploy
5. Cache Management: Automatic expiration and cleanup prevent unlimited storage growth
6. API Security: Authentication endpoints excluded from caching to prevent security issues
7. Production-Only: Disabled in development to avoid interference with hot module replacement

The implementation leverages Workbox 6.6.0 for robust service worker functionality and follows PWA best practices for installability, offline support, and performance optimization.

Sources: frontend/next.config.js1-6 frontend/public/sw.js1 frontend/public/workbox-1bb06f5e.js1 frontend/package.json68