diff --git a/CLAUDE.md b/CLAUDE.md index 41ff37c..1417217 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -138,8 +138,15 @@ CREATE TABLE locations ( **Profanity Database (`profanity.db`)**: Managed by the `ProfanityFilter` class for content moderation. -### Frontend (Progressive Enhancement) -The application uses progressive enhancement to work with and without JavaScript: +### Frontend (Progressive Web App + Progressive Enhancement) +The application is a full Progressive Web App with offline capabilities and progressive enhancement: + +**PWA Features:** +- **public/manifest.json**: Web app manifest for installation +- **public/sw.js**: Service worker for offline functionality and caching +- **public/icons/**: Complete icon set for all device sizes (72px to 512px) +- **public/offline.html**: Offline fallback page when network is unavailable +- **PWA Meta Tags**: Added to all HTML files for proper app behavior **JavaScript-Enhanced Experience:** - **public/app.js**: Main implementation using Leaflet.js @@ -158,6 +165,11 @@ The application uses progressive enhancement to work with and without JavaScript - **Static map generation**: Auto-fitted Mapbox static images showing all report locations - **Progressive enhancement**: noscript tags and "Basic View" button for accessibility +**Offline Capabilities:** +- **Service Worker Caching**: Essential files cached for offline access +- **Offline Page**: Custom offline experience with automatic reconnection +- **Install Prompt**: Automatic PWA installation prompts on compatible devices + ### API Endpoints **Public endpoints:** @@ -202,15 +214,17 @@ SCSS files are in `src/scss/`: ### Key Design Patterns 1. **TypeScript-First Architecture**: Full type safety with strict type checking -2. **Progressive Enhancement**: Works completely without JavaScript via server-side rendering -3. **Security-by-Design**: Rate limiting, input validation, and authentication built into core routes -4. **Modular Route Architecture**: Routes accept dependencies as parameters for testability -5. **Dual Database Design**: Separate databases for application data and content moderation -6. **Type-Safe Database Operations**: All database interactions use typed models -7. **Comprehensive Testing**: 125+ tests covering units, integration, and security scenarios -8. **Graceful Degradation**: Fallback geocoding providers and error handling -9. **Automated Maintenance**: Cron-based cleanup of expired reports -10. **Accessibility-First**: noscript fallbacks and server-side static map generation +2. **Progressive Web App**: Installable, offline-capable with service worker caching +3. **Progressive Enhancement**: Works completely without JavaScript via server-side rendering +4. **Security-by-Design**: Rate limiting, input validation, and authentication built into core routes +5. **Modular Route Architecture**: Routes accept dependencies as parameters for testability +6. **Dual Database Design**: Separate databases for application data and content moderation +7. **Type-Safe Database Operations**: All database interactions use typed models +8. **Comprehensive Testing**: 125+ tests covering units, integration, and security scenarios +9. **Graceful Degradation**: Fallback geocoding providers and error handling +10. **Automated Maintenance**: Cron-based cleanup of expired reports +11. **Accessibility-First**: noscript fallbacks and server-side static map generation +12. **Offline-First Design**: Service worker caching with automatic updates ### Deployment - Automated deployment script for Debian 12 ARM64 in `scripts/deploy.sh` diff --git a/README.md b/README.md index 4d6d2f2..30633bd 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ A community-driven web application for tracking winter road conditions and icy h - πŸ—ΊοΈ **Interactive Map** - Real-time location tracking centered on Grand Rapids - ⚑ **Fast Geocoding** - Lightning-fast address lookup with Mapbox API +- πŸ“± **Progressive Web App** - Install on mobile home screen, works offline - 🚫 **JavaScript-Free Mode** - Complete functionality without JavaScript via server-side rendering - πŸ–ΌοΈ **Static Maps** - Auto-generated Mapbox static images for non-JS users - πŸ”„ **Auto-Expiration** - Reports automatically removed after 48 hours @@ -172,10 +173,31 @@ See `docs/deployment.md` for detailed manual deployment instructions. ### API Documentation Interactive API documentation available at `/api-docs` when running the server. +## PWA Installation + +### Mobile Devices +1. Open the app in your mobile browser +2. Look for the "Add to Home Screen" prompt +3. Tap "Add" to install the app on your home screen +4. The app will work offline and behave like a native app + +### Desktop Browsers +1. Visit the app in Chrome, Edge, or Safari +2. Look for the install icon in the address bar +3. Click "Install" to add the app to your desktop +4. Launch from your applications folder or start menu + +### PWA Features +- **Offline Access:** View cached reports when disconnected +- **App-like Experience:** Standalone window, no browser UI +- **Home Screen Icon:** Quick access like native apps +- **Automatic Updates:** Always stay current when online + ## Technology Stack - **Backend:** Node.js, Express.js, SQLite, TypeScript -- **Frontend:** Progressive Enhancement (Vanilla JavaScript + Server-side rendering) +- **Frontend:** Progressive Web App with Progressive Enhancement + - **PWA:** Installable, offline-capable, service worker caching - **Enhanced:** Leaflet.js interactive maps with real-time updates - **Fallback:** Server-side HTML tables with static Mapbox images - **Geocoding:** Mapbox API (with Nominatim fallback) diff --git a/public/admin.html b/public/admin.html index c39c699..55d2d6c 100644 --- a/public/admin.html +++ b/public/admin.html @@ -4,8 +4,24 @@ Great Lakes Ice Report Admin - + + + + + + + + + + + + + + + + + + + + diff --git a/public/manifest.json b/public/manifest.json new file mode 100644 index 0000000..f91b97c --- /dev/null +++ b/public/manifest.json @@ -0,0 +1,75 @@ +{ + "name": "Great Lakes Ice Report", + "short_name": "Ice Report", + "description": "Community-driven winter road conditions and icy hazards tracker for the Great Lakes region", + "start_url": "/", + "display": "standalone", + "orientation": "portrait-primary", + "background_color": "#ffffff", + "theme_color": "#2196F3", + "lang": "en-US", + "scope": "/", + "categories": ["weather", "transportation", "utilities"], + "icons": [ + { + "src": "/icons/icon-72.svg", + "sizes": "72x72", + "type": "image/svg+xml", + "purpose": "any" + }, + { + "src": "/icons/icon-96.svg", + "sizes": "96x96", + "type": "image/svg+xml", + "purpose": "any" + }, + { + "src": "/icons/icon-128.svg", + "sizes": "128x128", + "type": "image/svg+xml", + "purpose": "any" + }, + { + "src": "/icons/icon-144.svg", + "sizes": "144x144", + "type": "image/svg+xml", + "purpose": "any" + }, + { + "src": "/icons/icon-152.svg", + "sizes": "152x152", + "type": "image/svg+xml", + "purpose": "any" + }, + { + "src": "/icons/icon-192.svg", + "sizes": "192x192", + "type": "image/svg+xml", + "purpose": "any" + }, + { + "src": "/icons/icon-384.svg", + "sizes": "384x384", + "type": "image/svg+xml", + "purpose": "any" + }, + { + "src": "/icons/icon-512.svg", + "sizes": "512x512", + "type": "image/svg+xml", + "purpose": "any" + }, + { + "src": "/icons/icon-192-maskable.svg", + "sizes": "192x192", + "type": "image/svg+xml", + "purpose": "maskable" + }, + { + "src": "/icons/icon-512-maskable.svg", + "sizes": "512x512", + "type": "image/svg+xml", + "purpose": "maskable" + } + ] +} \ No newline at end of file diff --git a/public/offline.html b/public/offline.html new file mode 100644 index 0000000..4e9aa69 --- /dev/null +++ b/public/offline.html @@ -0,0 +1,89 @@ + + + + + + Offline - Great Lakes Ice Report + + + + +
+
+
πŸ“‘
+

You're Offline

+

It looks like you've lost your internet connection. The Great Lakes Ice Report needs an internet connection to show current road conditions and submit new reports.

+ +

When you're back online, you'll be able to:

+ + + + +

+ This app works best with an internet connection for up-to-date safety information. +

+
+
+ + + + \ No newline at end of file diff --git a/public/privacy.html b/public/privacy.html index ea6476b..1c82a0b 100644 --- a/public/privacy.html +++ b/public/privacy.html @@ -4,8 +4,24 @@ Privacy Policy - Great Lakes Ice Report - - + + + + + + + + + + + + + + + + + +