freealberta/map/README.md

# NocoDB Map Viewer

A containerized web application that visualizes geographic data from NocoDB on an interactive map using Leaflet.js.

## Features

- 🗺️ Interactive map visualization with OpenStreetMap
- 📍 Real-time geolocation support
- ➕ Add new locations directly from the map
- 🔄 Auto-refresh every 30 seconds
- 📱 Responsive design for mobile devices
- 🔒 Secure API proxy to protect credentials
- 👤 User authentication with login system
- ⚙️ Admin panel for system configuration
- 🎯 Configurable map start location
- 📋 Walk Sheet generator for door-to-door canvassing
- 🔗 QR code integration for digital resources
- 🐳 Docker containerization for easy deployment
- 🆓 100% open source (no proprietary dependencies)

## Quick Start

### Prerequisites

- Docker and Docker Compose
- NocoDB instance with API access
- NocoDB API token

### Installation

1. **Get NocoDB API Token**

   1. Login to your NocoDB instance
   2. Click user icon → **Account Settings** → **API Tokens**
   3. Create new token with read/write permissions
   4. Copy the token for the next step

2. **Configure Environment**

   Edit the `.env` file with your NocoDB API and API Url:
   ```env
   # NocoDB API Configuration
   NOCODB_API_URL=https://your-nocodb-instance.com/api/v1
   NOCODB_API_TOKEN=your-api-token-here

   # These will be populated after running build-nocodb.sh
   NOCODB_VIEW_URL=
   NOCODB_LOGIN_SHEET=
   NOCODB_SETTINGS_SHEET=

   # Server Configuration
   PORT=3000
   NODE_ENV=production
   SESSION_SECRET=your-secure-random-string

   # Map Defaults (Edmonton, AB)
   DEFAULT_LAT=53.5461
   DEFAULT_LNG=-113.4938
   DEFAULT_ZOOM=11
   ```

3. **Auto-Create Database Structure**

   Run the build script to create required tables:
   ```bash
   chmod +x build-nocodb.sh
   ./build-nocodb.sh
   ```

   This creates three tables:
   - **Locations** - Main map data with geo-location, contact info, support levels
   - **Login** - User authentication (email, name, admin flag)
   - **Settings** - Admin configuration and QR codes

4. **Get Table URLs**

   After the script completes:
   1. Login to your NocoDB instance
   2. Navigate to your project ("Map Viewer Project")
   3. Copy the view URLs for each table from your browser address bar
   4. URLs should look like: `https://your-nocodb.com/dashboard/#/nc/project-id/table-id`

5. **Update Environment with URLs**

   Edit your `.env` file and add the table URLs:
   ```env
   NOCODB_VIEW_URL=https://your-nocodb.com/dashboard/#/nc/project-id/locations-table-id
   NOCODB_LOGIN_SHEET=https://your-nocodb.com/dashboard/#/nc/project-id/login-table-id
   NOCODB_SETTINGS_SHEET=https://your-nocodb.com/dashboard/#/nc/project-id/settings-table-id
   ```

6. **Build and Deploy**

   Build the Docker image and start the application:
   ```bash
   # Build the Docker image
   docker-compose build

   # Start the application
   docker-compose up -d
   ```

7. **Verify Installation**

   - Check container status: `docker-compose ps`
   - View logs: `docker-compose logs -f map-viewer`
   - Access the application at: http://localhost:3000

## Database Schema

The build script automatically creates the following table structure:

### Main Locations Table
- `Geo-Location` (Geo-Data): Format "latitude;longitude" 
- `latitude` (Decimal): Precision 10, Scale 8
- `longitude` (Decimal): Precision 11, Scale 8
- `First Name` (Single Line Text): Person's first name
- `Last Name` (Single Line Text): Person's last name
- `Email` (Email): Email address
- `Phone` (Single Line Text): Phone number
- `Unit Number` (Single Line Text): Unit or apartment number
- `Support Level` (Single Select): Options: "1", "2", "3", "4" (1=Strong Support/Green, 2=Moderate Support/Yellow, 3=Low Support/Orange, 4=No Support/Red)
- `Address` (Single Line Text): Street address
- `Sign` (Checkbox): Has campaign sign
- `Sign Size` (Single Select): Options: "Small", "Medium", "Large"
- `Notes` (Long Text): Additional details and comments
- `title` (Text): Location name (legacy field)
- `category` (Single Select): Classification (legacy field)

### Login Table
- `Email` (Email): User email address
- `Name` (Single Line Text): User display name  
- `Admin` (Checkbox): Admin privileges

### Settings Table
- `key` (Single Line Text): Setting identifier
- `title` (Single Line Text): Display name
- `value` (Long Text): Setting value
- `Geo-Location` (Text): Format "latitude;longitude"
- `latitude` (Decimal): Precision 10, Scale 8
- `longitude` (Decimal): Precision 11, Scale 8
- `zoom` (Number): Map zoom level
- `category` (Single Select): Setting category
- `updated_by` (Single Line Text): Last updater email
- `updated_at` (DateTime): Last update time
- `qr_code_1_image` (Attachment): QR code 1 image
- `qr_code_2_image` (Attachment): QR code 2 image
- `qr_code_3_image` (Attachment): QR code 3 image

## API Endpoints

### Public Endpoints

- `GET /api/locations` - Fetch all locations (requires auth)
- `POST /api/locations` - Create new location (requires auth)
- `GET /api/locations/:id` - Get single location (requires auth)
- `PUT /api/locations/:id` - Update location (requires auth)
- `DELETE /api/locations/:id` - Delete location (requires auth)
- `GET /api/config/start-location` - Get map start location
- `GET /health` - Health check

### Authentication Endpoints

- `POST /api/auth/login` - User login
- `GET /api/auth/check` - Check authentication status
- `POST /api/auth/logout` - User logout

### Admin Endpoints (requires admin privileges)

- `GET /api/admin/start-location` - Get start location with source info
- `POST /api/admin/start-location` - Update map start location
- `GET /api/admin/walk-sheet-config` - Get walk sheet configuration
- `POST /api/admin/walk-sheet-config` - Save walk sheet configuration

## Admin Panel

Users with admin privileges can access the admin panel at `/admin.html` to configure system settings.

### Features

#### Start Location Configuration

- **Interactive Map**: Visual interface for selecting coordinates
- **Real-time Preview**: See changes immediately on the admin map
- **Validation**: Built-in coordinate and zoom level validation

#### Walk Sheet Generator

- **Printable Forms**: Generate 8.5x11 walk sheets for door-to-door canvassing
- **QR Code Integration**: Add up to 3 QR codes with custom URLs and labels
- **Form Field Matching**: Automatically matches fields from the main location form
- **Live Preview**: See changes as you type
- **Print Optimization**: Proper formatting for printing or PDF export
- **Persistent Storage**: All QR codes and settings saved to NocoDB
- **Real-time Preview**: See changes immediately on the admin map
- **Validation**: Built-in coordinate and zoom level validation

### Access Control

- Admin access is controlled via the `Admin` checkbox in the Login table
- Only authenticated users with admin privileges can access `/admin.html`
- Admin status is checked on every request to admin endpoints

### Start Location Priority

The system uses a cascading fallback system for map start location:
1. **Database**: Admin-configured location stored in Settings table (highest priority)
2. **Environment**: Default values from .env file (medium priority)  
3. **Hardcoded**: Edmonton, Canada coordinates (lowest priority)

## Configuration

All configuration is done via environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `NOCODB_API_URL` | NocoDB API base URL | Required |
| `NOCODB_API_TOKEN` | API authentication token | Required |
| `NOCODB_VIEW_URL` | Full NocoDB view URL | Required |
| `NOCODB_LOGIN_SHEET` | Login table URL for authentication | Required |
| `NOCODB_SETTINGS_SHEET` | Settings table URL for admin config | Optional |
| `PORT` | Server port | 3000 |
| `DEFAULT_LAT` | Default map latitude | 53.5461 |
| `DEFAULT_LNG` | Default map longitude | -113.4938 |
| `DEFAULT_ZOOM` | Default map zoom level | 11 |

## Maintenance Commands

### Update Application
```bash
docker-compose down
git pull origin main
docker-compose build
docker-compose up -d
```

### Development Mode
```bash
cd app
npm install
npm run dev
```

### Health Check
```bash
curl http://localhost:3000/health
```

## Development

To run in development mode:

1. Install dependencies:
   ```bash
   cd app
   npm install
   ```

2. Start with hot reload:
   ```bash
   npm run dev
   ```

## Security Considerations

- API tokens are kept server-side only
- CORS is configured for security
- Rate limiting prevents abuse
- Input validation on all endpoints
- Helmet.js for security headers

## Troubleshooting

### Locations not showing

- Verify table has `geodata`, `latitude`, and `longitude` columns
- Check that coordinates are valid numbers
- Ensure API token has read permissions

### Cannot add locations

- Verify API token has write permissions
- Check browser console for errors
- Ensure coordinates are within valid ranges

### Connection errors

- Verify NocoDB instance is accessible
- Check API URL format
- Confirm network connectivity

### Build Script Issues

- Ensure NocoDB instance is accessible
- Verify API token has admin permissions
- Check that the NocoDB database is clean (delete all bases before running)

## License

MIT License - See LICENSE file for details

## Support

For issues or questions:
1. Check the troubleshooting section
2. Review NocoDB documentation
3. Open an issue on GitHub

## Known Bugs 

- First load of page often fails, need to debug 
- Want UI for dots to have an edit button that then brings up the form