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
- <20> Walk Sheet generator for door-to-door canvassing
- 🔗 QR code integration for digital resources
- <20>🐳 Docker containerization for easy deployment
- 🆓 100% open source (no proprietary dependencies)

## Quick Start

### Prerequisites

- Docker and Docker Compose
- NocoDB instance with a table containing location data
- NocoDB API token

### NocoDB Table Setup

1. **Main Locations Table** - Create a table with these required columns. The format here is `Column Name - Column Type - Other Settings`:

   - `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)

2. **Login Table** - Create a table for user authentication:

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

3. **Settings Table** - Create a table for admin configuration:

   - `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

### Installation

1. Clone this repository or create the file structure as shown

2. Copy the environment template:
   ```bash
   cp .env.example .env
   ```

3. Edit `.env` with your NocoDB details:
   ```env
   NOCODB_API_URL=https://db.lindalindsay.org/api/v1
   NOCODB_API_TOKEN=your-token-here
   NOCODB_VIEW_URL=https://db.lindalindsay.org/dashboard/#/nc/p406kno3lbq4zmq/mvtryxrvze6td79
   NOCODB_LOGIN_SHEET=https://db.lindalindsay.org/dashboard/#/nc/p406kno3lbq4zmq/login_sheet_id
   NOCODB_SETTINGS_SHEET=https://db.lindalindsay.org/dashboard/#/nc/p406kno3lbq4zmq/settings_sheet_id
   ```

4. Start the application:
   ```bash
   docker-compose up -d
   ```

5. Access the map at: http://localhost:3000

## Finding NocoDB IDs

### API Token

1. Click user icon → Account Settings
2. Go to "API Tokens" tab
3. Create new token with read/write permissions

### Project and Table IDs

- Simply provide the full NocoDB view URL in `NOCODB_VIEW_URL`
- The system will automatically extract the project and table IDs

## 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 |

## 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

## 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