# PWA Implementation Guide

## Overview
The Port Nimara Portal has been implemented as a Progressive Web App (PWA) to provide users with a native app-like experience on mobile devices.

## Features Implemented

### 1. PWA Configuration
- **App Name**: Port Nimara Portal
- **Short Name**: Port Nimara
- **Theme Color**: #387bca (brand primary color)
- **Background Color**: #ffffff
- **Display Mode**: standalone
- **Start URL**: /
- **Icons**: Multiple sizes from 72x72 to 512x512 pixels

### 2. Install Banner
- **Location**: Login page, below the login form
- **Behavior**: 
  - Only shows on mobile devices
  - Hidden if app is already installed (standalone mode)
  - Shows only once (dismissal stored in localStorage)
  - Animated slide-in with 1-second delay

### 3. Installation Flow
- **Android**: Direct browser install prompt
- **iOS**: Step-by-step instructions modal
- **Other browsers**: Fallback instructions

### 4. Offline Support
- **Service Worker**: Auto-updating with Workbox
- **Caching**: Network-first for API calls, cache-first for assets
- **Navigation Fallback**: Routes to home page when offline

## Files Added/Modified

### New Files
- `components/PWAInstallBanner.vue` - Install banner component
- `composables/usePWA.ts` - PWA functionality composable
- `plugins/pwa.client.ts` - PWA initialization plugin
- `docs/pwa-implementation.md` - This documentation

### Modified Files
- `nuxt.config.ts` - Added PWA configuration
- `pages/login.vue` - Added install banner component

## Configuration Details

### PWA Module Settings
```typescript
pwa: {
  registerType: 'autoUpdate',
  manifest: {
    name: 'Port Nimara Portal',
    short_name: 'Port Nimara',
    description: 'Port Nimara Client Portal - Manage your berth interests and expressions of interest',
    theme_color: '#387bca',
    background_color: '#ffffff',
    display: 'standalone',
    orientation: 'portrait',
    start_url: '/',
    scope: '/',
    icons: [/* 8 icon sizes */]
  },
  workbox: {
    // Caching strategies
  }
}
```

### Icon Requirements
The following icon sizes are configured:
- 72x72, 96x96, 128x128, 144x144 (Android)
- 152x152, 192x192 (iOS, Android)
- 384x384, 512x512 (Splash screens, large displays)

All icons are located in `/public/icons/` and based on the circular Port Nimara logo.

### Browser Support
- **Chrome/Edge (Android)**: Full PWA support with install prompt
- **Safari (iOS)**: Manual installation via "Add to Home Screen"
- **Firefox**: Basic PWA support
- **Other browsers**: Graceful degradation with instructions

## Usage Instructions

### For Users
1. Visit the login page on a mobile device
2. If eligible, an install banner will appear below the login form
3. Tap "Install App" to begin installation
4. Follow platform-specific instructions if needed

### For Developers
The PWA functionality is automatically initialized. Use the `usePWA()` composable to access PWA state:

```typescript
const { isInstalled, canInstall, install, isMobile, isIOS } = usePWA();
```

## Testing
- Test on actual mobile devices for best results
- Use Chrome DevTools > Application > Manifest to verify configuration
- Check Service Worker registration in DevTools > Application > Service Workers
- Test offline functionality by disabling network

## Deployment Notes
- Ensure HTTPS is enabled (required for PWA)
- Icons must be accessible via direct URLs
- Service worker will be auto-generated and registered
- Manifest will be auto-generated from nuxt.config.ts settings

## Future Enhancements
- Push notifications
- Background sync
- App shortcuts
- Share target functionality
- Install banner in dashboard for non-mobile users