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:

```bash
npm install
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.

To build for production:

```bash
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:**
```bash
npm run deploy
```

**Using nu shell:**
```bash
npm run deploy:nu
```

**Manual deployment:**
```bash
./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:**
   ```bash
   sudo mkdir -p /opt/sd-park-pass-locator
   sudo chown $USER:$USER /opt/sd-park-pass-locator
   ```

2. **Install PM2 globally:**
   ```bash
   npm install -g pm2
   ```

3. **Configure PM2 to start on boot:**
   ```bash
   pm2 startup
   pm2 save
   ```

4. **Set up nginx reverse proxy** (optional but recommended):
   ```nginx
   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;
       }
   }
   ```