Update documentation for Mapbox static maps and progressive enhancement

- Add MapImageService documentation to CLAUDE.md
- Update environment variable requirements for unrestricted Mapbox tokens
- Document new server-side routes (/table, /submit-report, /map-image.png)
- Add progressive enhancement section explaining JavaScript vs non-JavaScript modes
- Update technology stack to reflect accessibility-first approach
- Document auto-fit static map generation with color-coded pins

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude Code 2025-07-06 00:14:14 -04:00
parent ebafb1fa5a
commit 5562a2386c
2 changed files with 57 additions and 19 deletions

View file

@ -6,9 +6,12 @@ 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
- 🚫 **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
- 👨‍💼 **Admin Panel** - Manage and moderate location reports
- 📱 **Responsive Design** - Works on desktop and mobile devices
- ♿ **Accessibility First** - Progressive enhancement with noscript fallbacks
- 🔒 **Privacy-Focused** - No user tracking, community safety oriented
- 🛡️ **Enhanced Security** - Coordinate validation, rate limiting, and content filtering
@ -17,6 +20,7 @@ A community-driven web application for tracking winter road conditions and icy h
### Prerequisites
- Node.js 18+
- MapBox API token (free tier available)
- **Important**: For server-side static maps, use an unrestricted token (no URL restrictions)
### Local Development
@ -89,7 +93,7 @@ SCSS files are organized in `src/scss/`:
## Environment Variables
```bash
# Required for fast geocoding
# Required for geocoding and static map generation
MAPBOX_ACCESS_TOKEN=pk.your_mapbox_token_here
# Admin panel access
@ -99,6 +103,11 @@ ADMIN_PASSWORD=your_secure_password
PORT=3000
```
**MapBox Token Requirements:**
- For interactive geocoding: Token can have URL restrictions
- For server-side static maps: Must use unrestricted token (no URL restrictions)
- Recommended: Use one unrestricted token for both features
## Deployment
### Automated Deployment (Debian 12 ARM64)
@ -140,6 +149,15 @@ See `docs/deployment.md` for detailed manual deployment instructions.
- `POST /api/locations` - Submit new location report (rate limited: 10/15min per IP)
- `GET /api/config` - Get API configuration
### Progressive Enhancement Routes
- `GET /` - Main application page with JavaScript-enhanced features
- `GET /table` - Non-JavaScript table view with static map and HTML forms
- `POST /submit-report` - Server-side form submission for non-JavaScript users
- `GET /map-image.png` - Dynamic static map generation using Mapbox Static Images API
- Query parameters: `?width=800&height=600&padding=50` for customization
- Auto-fit positioning centers on actual location coordinates
- Color-coded pins: red for regular reports, orange for persistent
### Admin Endpoints (Authentication Required)
- `GET /admin` - Admin panel (password protected)
- `GET /api/admin/locations` - Get all location reports
@ -157,12 +175,16 @@ Interactive API documentation available at `/api-docs` when running the server.
## Technology Stack
- **Backend:** Node.js, Express.js, SQLite, TypeScript
- **Frontend:** Vanilla JavaScript, Leaflet.js
- **Frontend:** Progressive Enhancement (Vanilla JavaScript + Server-side rendering)
- **Enhanced:** Leaflet.js interactive maps with real-time updates
- **Fallback:** Server-side HTML tables with static Mapbox images
- **Geocoding:** MapBox API (with Nominatim fallback)
- **Maps:** Leaflet.js (interactive) + Mapbox Static Images API (server-side)
- **Security:** Rate limiting, input validation, authentication
- **Testing:** Jest, TypeScript, 128+ tests with 76% coverage
- **Reverse Proxy:** Caddy (automatic HTTPS)
- **Database:** SQLite (lightweight, serverless)
- **Accessibility:** Full progressive enhancement with noscript support
## Contributing