sd-park-pass-map/README.md

San Diego Beach Park Pass Locator

A real-time web application that shows the availability of San Diego library beach parking passes on an interactive map with notification and sorting features.

Features

• Real-time availability checking from BiblioCommons API
• Interactive map showing all library locations with zoom controls hidden for mobile
• Color-coded markers (green = available, red = not available)
• Information about pass types (pure pass vs. backpack with pass)
• Push notification system - Get browser notifications when passes become available
• Distance-based sorting - Sort libraries by distance from GPS or zip code location
• Smart sorting options - Sort by name, availability, or distance
• Collapsible control panel - Hide/show the main panel for better map viewing
• Mobile-friendly responsive design

New Features

🔔 Push Notification System

• Web push notifications compatible with Safari and all major browsers
• Add notifications for specific libraries and pass types
• Real-time browser notifications when passes become available
• Permission management with clear enable/disable status

📍 Location-Based Sorting

• GPS location or manual San Diego zip code entry (92101-92173)
• Calculate accurate distances to libraries
• Sort libraries by proximity to your location
• Fallback options when GPS is unavailable

🎛️ Collapsible Interface

• Expandable/collapsible main control panel
• Better map visibility on mobile devices
• Smooth animations and transitions
• Persistent state during use

📋 Enhanced Library List

• Detailed library information with real-time status
• Multiple sorting options (name, availability, distance)
• Distance display in miles when location is set
• Improved accessibility and mobile usability

How it works

The application fetches data from two different BiblioCommons entries:

• S161C1690437 - Pure parking pass
• S161C1805116 - Backpack item containing a parking pass

It then displays the availability status on an interactive map centered on San Diego, with additional features for notifications and sorting.

Development

To run the development server:

npm install
npm run dev

Open http://localhost:3000 with your browser to see the result.

To build for production:

npm run build
npm start

API Endpoints

• /api/availability - Returns current availability data for all libraries
• /api/notifications - Returns stored notification requests (for future expansion)

Library Locations

The application includes all San Diego Public Library branches that have beach parking passes available, with accurate coordinates for proper map positioning.

Dependencies

• Next.js 14 with App Router
• React Leaflet for interactive maps
• TypeScript for type safety
• Local storage for notification persistence

Usage Guide

1. View Current Availability: The map shows all libraries with colored markers
2. Sort Libraries: Use the dropdown to sort by name, availability, or distance from your location
3. Get Location-Based Sorting: Click "📍 Get Location" to enable distance sorting
4. Set Up Notifications:
   • Click "+ Add" in the Notifications section
   • Select a library and pass types you're interested in
   • Click "Check Now" to manually check your notifications
5. Manage Notifications: Remove notifications by clicking the "✕" button

Manual Check Process

To manually verify the data, you can:

1. Visit https://sandiego.bibliocommons.com/v2/record/S161C1690437 (pure pass)
2. Visit https://sandiego.bibliocommons.com/v2/record/S161C1805116 (backpack with pass)
3. Click "Availability by location" on each page
4. Check the status column for "Available" items

Future Enhancements

The notification system is designed to be expandable for:

• Email notifications
• Background checking with web workers
• Account-based notification management
• Mobile push notifications

Deployment to Linode

Prerequisites

• SSH access configured to your Linode server (alias: linode)
• Node.js and npm installed on the remote server
• PM2 installed globally on the remote server: npm install -g pm2
• rsync available on your local machine

Quick Deploy

You can use either the bash or nu shell deployment script:

Using bash:

npm run deploy

Using nu shell:

npm run deploy:nu

Manual deployment:

./deploy.sh

Deployment Process

The deployment script will:

1. 📦 Sync source files to /opt/sd-park-pass-locator/ (excluding node_modules, .next, etc.)
2. 📥 Install production dependencies on the remote server
3. 🏗️ Build the application on the remote server
4. 🔄 Restart the PM2 service

Remote Server Setup

On your Linode server, ensure the following:

1. Create the application directory:

   sudo mkdir -p /opt/sd-park-pass-locator
   sudo chown $USER:$USER /opt/sd-park-pass-locator
   

2. Install PM2 globally:

   npm install -g pm2
   

3. Configure PM2 to start on boot:

   pm2 startup
   pm2 save
   

4. Set up nginx reverse proxy (optional but recommended):

   server {
       listen 80;
       server_name your-domain.com;
   
       location / {
           proxy_pass http://localhost:3000;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
           proxy_cache_bypass $http_upgrade;
       }
   }