👤 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
📅 Volunteer shift management system with calendar and grid views
✋ User shift signup and cancellation with color-coded calendar
📅 Calendar integration (Google, Outlook, Apple) for shift export
👥 Admin shift creation and management with volunteer assignment
📧 Automated shift email notifications - Send shift details to volunteers with visual progress tracking
👨‍💼 User management panel for admin users (create, delete users)
📧 Admin broadcast emailing - Rich HTML email composer with live preview and delivery tracking
📧 Listmonk Integration - Real-time sync with self-hosted newsletter platform for advanced email marketing
🔐 Role-based access control (Admin vs User permissions)Automated shift email notifications** - Send shift details to volunteers with visual progress tracking
<EFBFBD>👨‍💼 User management panel for admin users (create, delete users)
<EFBFBD> Admin broadcast emailing - Rich HTML email composer with live preview and delivery trackingntainerized web application that visualizes geographic data from NocoDB on an interactive map using Leaflet.js.

Features

🗺️ Interactive map visualization with OpenStreetMap
🔍 Unified search system with docs and address search (Ctrl+K to activate)
📍 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
📅 Volunteer shift management system with calendar and grid views
✋ User shift signup and cancellation with color-coded calendar
<EFBFBD> Calendar integration (Google, Outlook, Apple) for shift export
<EFBFBD>👥 Admin shift creation and management with volunteer assignment
<EFBFBD> Automated shift email notifications - Send shift details to volunteers
<EFBFBD>👨‍💼 User management panel for admin users (create, delete users)
<EFBFBD> Admin broadcast emailing - Rich HTML email composer with live preview
<EFBFBD>🔐 Role-based access control (Admin vs User permissions)
⏰ Temporary user accounts with automatic expiration
📧 Email notifications and password recovery via SMTP
📊 CSV data import with batch geocoding and visual progress tracking
✂️ Cut feature for geographic overlays - Admin-drawn polygons for map regions
🗺️ Interactive polygon drawing with click-to-add-points system
🎨 Customizable cut properties (color, opacity, category, visibility)
🐳 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

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

Configure Environment

Edit the .env file with your NocoDB API and API Url:

# NocoDB API Configuration
NOCODB_API_URL=https://db.cmlite.org/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=
NOCODB_SHIFTS_SHEET=
NOCODB_SHIFT_SIGNUPS_SHEET=

# Domain Configuration
DOMAIN=cmlite.org

# MkDocs Integration
MKDOCS_URL=https://cmlite.org
MKDOCS_SEARCH_URL=https://cmlite.org
MKDOCS_SITE_SERVER_PORT=4002

# Server Configuration
PORT=3000
NODE_ENV=production

# Session Secret (Generate with: openssl rand -hex 32)
SESSION_SECRET=your-secure-random-string

# Map Defaults (Edmonton, Alberta, Canada)
DEFAULT_LAT=53.5461
DEFAULT_LNG=-113.4938
DEFAULT_ZOOM=11

# Optional: Map Boundaries (prevents users from adding points outside area)
# BOUND_NORTH=53.7
# BOUND_SOUTH=53.4
# BOUND_EAST=-113.3
# BOUND_WEST=-113.7

# Cloudflare Settings
TRUST_PROXY=true
COOKIE_DOMAIN=.cmlite.org

# Allowed Origins
ALLOWED_ORIGINS=https://map.cmlite.org,http://localhost:3000

# Email Configuration (Required for full functionality)
# Used for password recovery, shift notifications, and admin broadcast emails
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
EMAIL_FROM_NAME=CMlite Support
EMAIL_FROM_ADDRESS=noreply@cmlite.org
APP_NAME=CMlite Map

# Listmonk Integration (Optional - enhances email marketing capabilities)
LISTMONK_URL=http://localhost:9000
LISTMONK_USERNAME=admin
LISTMONK_PASSWORD=your-listmonk-password
LISTMONK_ENABLED=true
LISTMONK_SYNC_ON_STARTUP=true
LISTMONK_AUTO_CREATE_LISTS=true

Auto-Create Database Structure

Run the build script to create required tables:
```
chmod +x build-nocodb.sh
./build-nocodb.sh
```
This creates six 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
- Shifts - Shift scheduling and management
- Shift Signups - User shift registrations
- Cuts - Geographic polygon overlays for map regions
Get Table URLs

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

Update Environment with URLs

Edit your .env file and add the table URLs:

NOCODB_VIEW_URL=https://db.cmlite.org/dashboard/#/nc/pnsalzrup2zqvz8/m6g7bkzv7s1w2ur
NOCODB_LOGIN_SHEET=https://db.cmlite.org/dashboard/#/nc/pnsalzrup2zqvz8/mizyc64e4r7ppzh
NOCODB_SETTINGS_SHEET=https://db.cmlite.org/dashboard/#/nc/pnsalzrup2zqvz8/mix06f2mlep7gqb
NOCODB_SHIFTS_SHEET=https://db.cmlite.org/dashboard/#/nc/pnsalzrup2zqvz8/mkx0tex0iquus1u
NOCODB_SHIFT_SIGNUPS_SHEET=https://db.cmlite.org/dashboard/#/nc/pnsalzrup2zqvz8/mi8jg1tn26mu8fj
NOCODB_CUTS_SHEET=https://db.cmlite.org/dashboard/#/nc/pnsalzrup2zqvz8/mxxxxxxxxxxxxxx

Build and Deploy

Build the Docker image and start the application:

# Build the Docker image
docker-compose build

# Start the application
docker-compose up -d

Verify Installation
- Check container status: docker-compose ps
- View logs: docker-compose logs -f map-viewer
- Access the application at: http://localhost:3000
- Access shift management at: http://localhost:3000/shifts.html
- Access admin panel at: http://localhost:3000/admin.html (admin users only)

Database Schema

The build script automatically creates the following table structure:

Main Locations Table

ID (ID): Auto-incrementing primary key
Geo-Location (GeoData): Geographic coordinate data
latitude (Decimal): Precision 8, Scale 8
longitude (Decimal): Precision 8, 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 (PhoneNumber): Phone number with validation
Unit Number (Single Line Text): Unit or apartment number
Support Level (Single Select): Options: "1" (Green), "2" (Yellow), "3" (Orange), "4" (Red)
Address (Single Line Text): Street address
Sign (Checkbox): Has campaign sign
Sign Size (Single Select): Options: "Regular" (Blue), "Large" (Green), "Unsure" (Orange)
Notes (Long Text): Additional details and comments
created_by_user (Single Line Text): Creator email
last_updated_by_user (Single Line Text): Last updater email

ID (ID): Auto-incrementing primary key
Email (Email): User email address (required)
Password (Single Line Text): User password (required)
Name (Single Line Text): User display name
Admin (Checkbox): Admin privileges
UserType (Single Select): Options: "user" (Blue), "temp" (Orange) - User role type
ExpiresAt (DateTime): Expiration date for temporary users
ExpireDays (Number): Number of days until temp user expires
Created At (DateTime): Account creation timestamp
Last Login (DateTime): Last login timestamp

Settings Table

ID (ID): Auto-incrementing primary key
created_at (DateTime): Record creation timestamp
created_by (Single Line Text): Creator identifier
Geo-Location (Single Line Text): Format "latitude;longitude"
latitude (Decimal): Precision 8, Scale 8
longitude (Decimal): Precision 8, Scale 8
zoom (Number): Map zoom level
Walk Sheet Title (Single Line Text): Title for walk sheets
Walk Sheet Subtitle (Single Line Text): Subtitle for walk sheets
Walk Sheet Footer (Long Text): Footer text for walk sheets
QR Code 1 URL (URL): First QR code link
QR Code 1 Label (Single Line Text): First QR code label
QR Code 2 URL (URL): Second QR code link
QR Code 2 Label (Single Line Text): Second QR code label
QR Code 3 URL (URL): Third QR code link
QR Code 3 Label (Single Line Text): Third QR code label

Shifts Table

ID (ID): Auto-incrementing primary key
Title (Single Line Text): Shift title (required)
Description (Long Text): Detailed shift description
Date (Date): Shift date (required)
Start Time (Time): Shift start time (required)
End Time (Time): Shift end time (required)
Location (Single Line Text): Shift location
Max Volunteers (Number): Maximum volunteer capacity (required)
Current Volunteers (Number): Current volunteer count
Status (Single Select): Options: "Open" (Green), "Full" (Orange), "Cancelled" (Red)
Created By (Single Line Text): Creator identifier
Created At (DateTime): Creation timestamp
Updated At (DateTime): Last update timestamp

Shift Signups Table

ID (ID): Auto-incrementing primary key
Shift ID (Number): Reference to shifts table (required)
Shift Title (Single Line Text): Copy of shift title for reference
User Email (Email): User's email address (required)
User Name (Single Line Text): User's display name
Signup Date (DateTime): When user signed up
Status (Single Select): Options: "Confirmed" (Green), "Cancelled" (Red)

Cuts Table

ID (ID): Auto-incrementing primary key
name (Single Line Text): Cut name/title (required)
description (Long Text): Detailed description of the cut
geojson (Long Text): GeoJSON polygon data (required)
bounds_north (Decimal): Northern boundary latitude (Precision 8, Scale 8)
bounds_south (Decimal): Southern boundary latitude (Precision 8, Scale 8)
bounds_east (Decimal): Eastern boundary longitude (Precision 8, Scale 8)
bounds_west (Decimal): Western boundary longitude (Precision 8, Scale 8)
color (Single Line Text): Hex color code (default: "#007bff")
opacity (Decimal): Fill opacity 0-1 (Precision 3, Scale 2, default: 0.3)
category (Single Line Text): Category/tag for organization
is_public (Checkbox): Whether cut is visible to non-admin users (default: true)
created_by (Single Line Text): Creator email
created_at (DateTime): Creation timestamp
updated_at (DateTime): Last update timestamp

Email Features

The system includes comprehensive email functionality powered by SMTP configuration:

🔧 Admin Email Broadcasting

Rich HTML email composer with live preview and formatting toolbar
Mass email sending to all registered users
Professional email templates with consistent branding
Real-time recipient counting and success/failure tracking
Visual progress tracking with animated progress bars and individual email status
Detailed delivery reports showing successful sends and failure reasons
Support for rich text content including headers, lists, links, and formatting

📅 Shift Email Notifications

Automated shift detail emails sent to all volunteers
Professional HTML templates with complete shift information
Shift status tracking (open, full, cancelled) in emails
Volunteer management - add/remove users from shifts
Calendar integration - Google, Outlook, and Apple calendar export
Visual progress indicators with real-time sending status per volunteer
Email status reporting with success/failure details and error messages

👤 User Account Emails

Login credential delivery for new users
Password recovery with secure email notifications
Temporary user accounts with automatic expiration tracking
Professional HTML and plain text email templates

📧 Email Template System

Responsive HTML templates with professional design
Variable substitution for personalized content
Multi-format support (HTML and plain text)
Consistent branding across all email communications

Listmonk Integration

The application includes real-time integration with Listmonk, a self-hosted newsletter and mailing list manager, enabling advanced email marketing capabilities and subscriber management.

🔄 Real-Time Synchronization

The system automatically synchronizes data between the Map application and Listmonk:

Automatic List Creation: Creates and maintains email lists for different user segments
Real-Time Updates: New locations and users are instantly synced to Listmonk
Bi-Directional Sync: Unsubscribes in Listmonk update the Map database
Error Handling: Visual status indicators and detailed logging for sync failures

📋 Automated List Management

The integration automatically manages the following Listmonk subscriber lists:

All Locations: Complete list of all mapped locations with contact information
All Users: List of all registered Map application users
Support Level Lists: Separate lists for each support level (1-4) for targeted campaigns
Sign Status Lists: Lists based on campaign sign status (Has Sign, No Sign)
Combined Lists: Smart combinations like "Support Level 4 with Signs" for precision targeting

⚙️ Configuration

Add the following environment variables to your .env file:

# Listmonk Integration (Optional - enhances email marketing capabilities)
LISTMONK_API_URL=http://172.20.0.9:9000/api
LISTMONK_USERNAME=admin
LISTMONK_PASSWORD=your-listmonk-password
LISTMONK_SYNC_ENABLED=true

# Listmonk Sync Settings
LISTMONK_INITIAL_SYNC=true  # Set to true only for first run to sync existing data

🔍 Finding the Correct Listmonk API URL

The LISTMONK_API_URL must point to the internal Docker network address where Listmonk is running. Here are several methods to find the correct URL:

Method 1: Using Docker Inspect (Recommended)

If Listmonk is running in a Docker container, find its internal IP address:

# List all running containers
docker ps

# Find the Listmonk container name/ID, then inspect it
docker inspect <listmonk-container-name> | grep IPAddress

# Example output:
# "IPAddress": "172.20.0.9"

Your LISTMONK_API_URL would then be: http://172.20.0.9:9000/api

Method 2: Using Docker Network Inspection

If both containers are on the same Docker network:

# List Docker networks
docker network ls

# Inspect the network (usually named after your docker-compose project)
docker network inspect <network-name>

# Look for the Listmonk container in the "Containers" section
# Note the "IPv4Address" value

Method 3: Using Container Names (Docker Compose)

If using Docker Compose with both services in the same docker-compose.yml:

# In your docker-compose.yml
services:
  listmonk:
    image: listmonk/listmonk:latest
    container_name: listmonk
    # ... other config

  map-app:
    # ... your map application config

You can use the service name: LISTMONK_API_URL=http://listmonk:9000/api

Method 4: Check Docker Compose Logs

# View Listmonk container logs to see what IP it's binding to
docker-compose logs listmonk

# Look for lines like:
# listmonk_1  | INFO[0000] listmonk started. IP: 0.0.0.0:9000

Method 5: Testing Connectivity

Test if your URL is correct by running a test from within your Map application container:

# Access your map application container
docker exec -it <map-container-name> /bin/bash

# Test connectivity to Listmonk
curl http://172.20.0.9:9000/api/health
# Should return: {"data":true}

# Or test with your credentials
curl -u "admin:your-password" http://172.20.0.9:9000/api/lists

Common IP Ranges

Docker typically assigns containers to these network ranges:

172.17.0.x - Default bridge network
172.18.0.x - Custom bridge networks
172.20.0.x - Docker Compose networks
192.168.x.x - Some custom networks

Troubleshooting Connection Issues

If you're having connection problems:

Verify Listmonk is running: docker ps | grep listmonk
Check port exposure: Ensure Listmonk exposes port 9000
Network connectivity: Both containers must be on the same Docker network
Firewall rules: Ensure no firewalls block inter-container communication
DNS resolution: Try IP address instead of container name if DNS fails

Example Working Configuration

# Working example from a real deployment
LISTMONK_API_URL=http://172.20.0.9:9000/api
LISTMONK_USERNAME=API
LISTMONK_PASSWORD=s0f6qSuWTGMX8AWbz8f4EQxGFSZCZxAC
LISTMONK_SYNC_ENABLED=true
LISTMONK_INITIAL_SYNC=true

Note

: Never use localhost or 127.0.0.1 for the Listmonk URL when running in Docker containers, as this refers to the container's own loopback interface, not the Listmonk container.

📊 Admin Features

Administrators have access to comprehensive Listmonk management tools:

Real-Time Status Monitoring

Connection Status: Live indicator showing Listmonk connectivity
Sync Statistics: Real-time counts of subscribers, lists, and sync operations
Error Notifications: Popup alerts and terminal logs for sync failures
Last Sync Timestamps: Track when data was last synchronized

Bulk Operations

Full Resync: Manually trigger complete data synchronization
Selective Sync: Sync specific data types (locations, users, lists)
Progress Tracking: Visual progress bars for bulk operations
Detailed Reports: Success/failure counts with error details

List Management

Auto-List Creation: Automatically create and maintain subscriber lists
Custom Segmentation: Create lists based on support levels, sign status, and combinations
Subscriber Counts: Real-time subscriber counts for each list
List Status Monitoring: Track list health and sync status

🔌 API Integration Points

The Listmonk integration adds the following API endpoints:

Admin Listmonk Endpoints (requires admin privileges)

GET /api/listmonk/status - Get connection status and sync statistics
POST /api/listmonk/sync/full - Trigger full synchronization
POST /api/listmonk/sync/locations - Sync locations only
POST /api/listmonk/sync/users - Sync users only
POST /api/listmonk/test-connection - Test Listmonk connectivity
POST /api/listmonk/reinitialize - Recreate all lists and resync data
GET /api/listmonk/lists - Get all Listmonk lists with subscriber counts

🚀 Getting Started with Listmonk

Set up Listmonk: Deploy Listmonk using Docker Compose (see parent project documentation)
Configure Integration: Add Listmonk credentials to your .env file
Initialize Lists: Lists are automatically created on first startup
Monitor Status: Check the admin panel for sync status and connection health
Customize Campaigns: Use Listmonk's web interface to create targeted email campaigns

🔍 Status Indicators

The system provides visual feedback on integration status:

🟢 Connected: Listmonk is accessible and syncing properly
🟡 Warning: Sync delays or minor issues detected
🔴 Error: Connection failed or sync errors occurred
⚪ Disabled: Listmonk integration is disabled

📈 Benefits

Enhanced Email Marketing: Leverage Listmonk's advanced campaign features
Automated Segmentation: Automatic subscriber lists based on Map data
Improved Deliverability: Professional email marketing infrastructure
Real-Time Updates: Always-current subscriber information
Detailed Analytics: Track email engagement and campaign performance
Professional Templates: Rich HTML email templates and campaign builder

🔧 Troubleshooting

Common issues and solutions:

Connection Failed: Verify Listmonk URL and credentials in .env
Sync Errors: Check terminal logs for detailed error messages
Missing Lists: Enable LISTMONK_AUTO_CREATE_LISTS=true and restart
Slow Sync: Monitor network connectivity and Listmonk performance
Duplicate Subscribers: The system automatically handles duplicates using email addresses

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

Shifts Endpoints (requires authentication)

GET /api/shifts - Get all available shifts
GET /api/shifts/my-signups - Get current user's shift signups
POST /api/shifts/:shiftId/signup - Sign up for a shift
POST /api/shifts/:shiftId/cancel - Cancel shift signup

Shifts Admin Endpoints (requires admin privileges)

GET /api/shifts/admin - Get all shifts including cancelled ones
POST /api/shifts/admin - Create new shift
PUT /api/shifts/admin/:id - Update existing shift
DELETE /api/shifts/admin/:id - Delete shift
POST /api/shifts/admin/:shiftId/add-user - Add user to shift
DELETE /api/shifts/admin/:shiftId/remove-user/:userId - Remove user from shift
POST /api/shifts/admin/:shiftId/email-details - Email shift details to all volunteers

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

User Management Endpoints (requires admin privileges)

GET /api/users - Get all users
POST /api/users - Create new user
DELETE /api/users/:id - Delete user
POST /api/users/:id/send-login-details - Send login details to user
POST /api/users/email-all - Send broadcast email to all users

Cuts Endpoints

Public Cuts Endpoints (requires authentication)

GET /api/cuts/public - Get all public cuts visible to users

Admin Cuts Endpoints (requires admin privileges)

GET /api/cuts - Get all cuts (including private ones)
POST /api/cuts - Create new cut
GET /api/cuts/:id - Get single cut by ID
PUT /api/cuts/:id - Update existing cut
DELETE /api/cuts/:id - Delete cut

Geocoding Endpoints (requires authentication)

GET /api/geocode/reverse?lat=<lat>&lng=<lng> - Reverse geocode coordinates to address
GET /api/geocode/forward?address=<address> - Forward geocode address to coordinates
GET /api/geocode/search?query=<query>&limit=<number> - Search for multiple address matches
GET /api/geocode/cache/stats - Get geocoding cache statistics (admin only)

All geocoding endpoints include rate limiting (30 requests per 15 minutes per IP) and support Cloudflare IP detection for accurate rate limiting.

Shifts Management

The application includes a comprehensive volunteer shift management system accessible at /shifts.html.

User Features

Dual View Options: Toggle between grid view and calendar view for shift display
Calendar View: Interactive monthly calendar showing shifts with color-coded indicators:
- Green: Shifts you've signed up for
- Blue: Available shifts you can join
- Gray: Full shifts (no spots available)
View Available Shifts: See all upcoming shifts with date, time, and capacity information
Sign Up for Shifts: One-click signup for available shifts (works in both views)
My Shifts Dashboard: View all your current shift signups at the top of the page
Cancel Signups: Cancel your shift signups when needed
Date Filtering: Filter shifts by specific dates (applies to both views)
Real-time Updates: Shift availability updates dynamically
Interactive Calendar: Click on calendar shifts for detailed popup with signup options
Calendar Navigation: Navigate between months to view future shifts

Admin Features

Administrators have additional capabilities for managing shifts:

Create New Shifts: Add new volunteer shifts with date, time, location, and capacity
Edit Existing Shifts: Modify shift details, times, or capacity
Cancel Shifts: Mark shifts as cancelled (they remain in system but hidden from users)
View All Signups: See who has signed up for each shift
Manage Capacity: Set maximum number of volunteers per shift
Email Notifications: Send shift details to all volunteers via email

Shift Status System

Open (Green): Shift is available and accepting signups
Full (Orange): Shift has reached maximum capacity
Cancelled (Red): Shift has been cancelled by admin

The system automatically updates shift status based on current signups vs. maximum capacity.

Cut Feature - Geographic Overlays

The Cut feature allows administrators to create and manage polygon overlays on the map, useful for defining geographic regions, neighborhoods, or operational areas.

Admin Cut Creation

Administrators can create cuts through the admin panel at /admin.html:

Interactive Drawing: Click points on the map to define polygon boundaries
Real-time Preview: See the polygon shape as you draw
Point Management: Add points by clicking, finish by clicking the first point or using the complete button
Visual Feedback: Clear indicators for drawing mode and vertex points

Cut Properties

Each cut supports the following properties:

Name: Required title for the cut (e.g., "Downtown District", "Canvassing Area A")
Description: Optional detailed description of the cut's purpose
Color: Hex color code for the polygon border and fill (default: "#007bff")
Opacity: Fill transparency from 0.0 (transparent) to 1.0 (opaque) (default: 0.3)
Category: Optional categorization tag for organization
Visibility: Public (visible to all users) or Private (admin-only)

Cut Management

View All Cuts: List all existing cuts with their properties
Edit Cuts: Modify any cut property after creation
Delete Cuts: Remove cuts with confirmation prompts
Import/Export: JSON format for backup and migration
Real-time Updates: Changes appear immediately on all connected maps

Public Cut Display

Public cuts are automatically displayed on the main map for all authenticated users:

Polygon Overlays: Cuts appear as colored polygon overlays
Non-Interactive: Users can see cuts but cannot modify them
Responsive: Cuts adapt to different screen sizes and zoom levels
Performance Optimized: Efficient rendering for multiple cuts

Use Cases

Canvassing Districts: Define geographic areas for volunteer assignments
Neighborhood Boundaries: Mark community or administrative boundaries
Event Areas: Highlight locations for rallies, meetings, or activities
Restricted Zones: Mark areas requiring special attention or restrictions
Progress Tracking: Visual representation of completed campaign areas

Unified Search System

The application features a powerful unified search system accessible via the search bar in the header or by pressing Ctrl+K anywhere in the application.

Search Modes

The search system operates in two modes:

Documentation Search: Search through integrated MkDocs documentation
Address Search: Search for addresses and geographic locations
Database Search: Search through loaded location records on the map

Features

Mode Toggle: Switch between docs, address, and database search with dedicated buttons
Keyboard Shortcuts:
- Ctrl+K or Cmd+K: Focus search input from anywhere
- Escape: Close search results
- Arrow keys: Navigate through search results
- Enter: Select highlighted result
Real-time Results: Search results update as you type (minimum 2 characters)
Smart Caching: Results are cached for improved performance
QR Code Generation: Generate QR codes for documentation links
Visual Feedback: Loading states, result counts, and error handling

Documentation Search

When connected to a MkDocs documentation site:

Full-text Search: Search through all documentation content
Snippet Preview: See relevant excerpts with search terms highlighted
Direct Navigation: Click results to open documentation pages
Path Display: Shows the document path and section
QR Code Support: Generate QR codes for sharing documentation links

Address Search

For geographic location search:

Geocoding Integration: Powered by Nominatim/OpenStreetMap
Multiple Results: Returns up to 5 address matches
Map Integration: Click results to view location on map
Temporary Markers: Visual markers for search results
Quick Actions: Add locations directly from search results
Coordinate Display: Shows precise latitude/longitude coordinates

Database Search

For searching through loaded location data:

Full-text Search: Search through names, addresses, emails, phone numbers, and notes
Smart Matching: Finds partial matches across multiple fields
Result Preview: See relevant details with search terms highlighted
Map Integration: Click results to pan to location and open marker popup

Configuration

The unified search system integrates with MkDocs documentation when configured:

MKDOCS_URL=https://your-docs-site.com
MKDOCS_SEARCH_URL=https://your-docs-site.com
MKDOCS_SITE_SERVER_PORT=4002

Rate Limiting

Address search is rate-limited to prevent abuse:

30 requests per 15-minute window per IP
Cloudflare IP detection for accurate limiting
Graceful error handling for rate limit exceeded

Admin Panel

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

Features

Dashboard Analytics

Campaign Overview: Real-time statistics and metrics
Support Distribution: Visual breakdown of support levels (1-4)
Sign Tracking: Monitor lawn sign requests
User Analytics: Track user growth and daily entries
Performance Score: Overall campaign performance metric

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

Shift Management

Create Shifts: Set up volunteer shifts with dates, times, and capacity
Manage Volunteers: View signups and manage shift participants
Real-time Updates: See shift status changes immediately

User Management

Create Users: Add new user accounts with email and password
Role Assignment: Assign admin or user privileges
User List: View all registered users with their details and creation dates
Delete Users: Remove user accounts (with confirmation prompts)
Security: Password validation and admin-only access

Cut Management

Interactive Drawing: Click-to-add-points polygon drawing system on the map
Cut Properties: Configure name, description, color, opacity, and category
Visibility Control: Set cuts as public (visible to all users) or private (admin-only)
Real-time Preview: See cut polygons rendered on the map during creation
Cut Management: View, edit, and delete existing cuts with full CRUD operations
Import/Export: JSON import/export functionality for cut data backup and migration
Map Integration: Cuts display as colored polygon overlays on both admin and public maps
Responsive Design: Touch-friendly interface for mobile and tablet devices

Convert Data

CSV Upload: Upload CSV files containing addresses for bulk import
Drag & Drop Interface: Easy file upload with visual feedback
Real-time Geocoding: Addresses are geocoded in real-time with progress tracking
Visual Progress: Live progress bar and status updates during processing
Map Preview: Interactive map showing geocoded locations before saving
Results Table: Detailed table with success/error status for each address
Batch Save: Save all successfully geocoded locations to the database
Field Mapping: Automatically maps common CSV fields (First Name, Last Name, Email, Phone, etc.)
Error Handling: Clear error messages for failed geocoding attempts
File Validation: CSV format validation and file size limits (10MB max)

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
User management functions are restricted to admin users only

Start Location Priority

The system uses a cascading fallback system for map start location:

Database: Admin-configured location stored in Settings table (highest priority)
Environment: Default values from .env file (medium priority)
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 for locations table	Required
`NOCODB_LOGIN_SHEET`	Login table URL for authentication	Required
`NOCODB_SETTINGS_SHEET`	Settings table URL for admin config	Required
`NOCODB_SHIFTS_SHEET`	Shifts table URL for shift management	Required
`NOCODB_SHIFT_SIGNUPS_SHEET`	Shift signups table URL for user registrations	Required
`DOMAIN`	Primary domain for the application	Required
`MKDOCS_URL`	MkDocs documentation site URL	Optional
`MKDOCS_SEARCH_URL`	MkDocs search endpoint URL	Optional
`MKDOCS_SITE_SERVER_PORT`	Port for MkDocs integration	4002
`PORT`	Server port	3000
`NODE_ENV`	Environment mode	production
`SESSION_SECRET`	Session encryption secret (generate with openssl rand -hex 32)	Required
`DEFAULT_LAT`	Default map latitude	53.5461
`DEFAULT_LNG`	Default map longitude	-113.4938
`DEFAULT_ZOOM`	Default map zoom level	11
`BOUND_NORTH`	Northern boundary for map points (optional)	None
`BOUND_SOUTH`	Southern boundary for map points (optional)	None
`BOUND_EAST`	Eastern boundary for map points (optional)	None
`BOUND_WEST`	Western boundary for map points (optional)	None
`TRUST_PROXY`	Trust proxy headers (for Cloudflare)	true
`COOKIE_DOMAIN`	Cookie domain setting	.cmlite.org
`ALLOWED_ORIGINS`	CORS allowed origins (comma-separated)	Multiple URLs
`SMTP_HOST`	SMTP server hostname (required for email features)	smtp.gmail.com
`SMTP_PORT`	SMTP server port (required for email features)	587
`SMTP_SECURE`	Use SSL for SMTP (required for email features)	false
`SMTP_USER`	SMTP username (required for email features)	your-email@gmail.com
`SMTP_PASS`	SMTP password (required for email features)	your-app-password
`EMAIL_FROM_NAME`	Sender name for outgoing emails	CMlite Support
`EMAIL_FROM_ADDRESS`	Sender email address for outgoing emails	noreply@cmlite.org
`APP_NAME`	Application name used in emails and branding	CMlite Map
`EMAIL_FROM_NAME`	Email sender name (optional)	CMlite Support
`EMAIL_FROM_ADDRESS`	Email sender address (optional)	noreply@cmlite.org
`APP_NAME`	Application name for emails (optional)	CMlite Map

Maintenance Commands

Update Application

docker-compose down
git pull origin main
docker-compose build
docker-compose up -d

Development Mode

cd app
npm install
npm run dev

Health Check

curl http://localhost:3000/health

Development

To run in development mode:

Install dependencies:
```
cd app
npm install
```
Start with hot reload:
```
npm run dev
```

Usage Guide

Email Features

Admin Broadcasting

Access the admin panel at /admin.html
Navigate to the "User Management" section
Click "Email All Users" to open the email composer
Use the rich text editor to format your message
Preview your email before sending
Send to all registered users with delivery tracking

Shift Email Notifications

In the admin panel, go to "Shift Management"
Click "Manage Volunteers" for any shift
Add or remove volunteers as needed
Click "Email Shift Details" to notify all volunteers
Professional emails include shift details, location, and calendar links

User Management

Create new users (regular or temporary with expiration)
Send login credentials automatically via email
Password recovery through secure email notifications
Temporary users receive expiration warnings

Calendar Integration

Users can export shifts to Google Calendar, Outlook, or Apple Calendar
Calendar invites include all shift details and location information
One-click calendar integration for better volunteer organization

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 Geo-Location, 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)

Email Issues

Emails not sending:

Verify SMTP configuration in .env file
Check SMTP credentials are correct
Test SMTP connection with your email provider
Review application logs for email errors

Gmail SMTP setup:

Enable 2-factor authentication on your Google account
Generate an App Password (not your regular password)
Use smtp.gmail.com as SMTP_HOST with port 587
Set SMTP_SECURE to false for STARTTLS

Email templates not rendering:

Check that all template files exist in app/templates/email/
Verify template variable names match controller implementations
Review logs for template rendering errors

Shift emails not working:

Ensure shift signups table is properly configured
Verify users have valid email addresses
Check that email templates include all required variables

License

MIT License - See LICENSE file for details

Support

For issues or questions:

Check the troubleshooting section
Review NocoDB documentation
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

README.md Unescape Escape

NocoDB Map V- 🔒 Secure API proxy to protect credentials

Features

Quick Start

Prerequisites

Installation

Database Schema

Main Locations Table

Login Table

Settings Table

Shifts Table

Shift Signups Table

Cuts Table

Email Features

🔧 Admin Email Broadcasting

📅 Shift Email Notifications

👤 User Account Emails

📧 Email Template System

Listmonk Integration

🔄 Real-Time Synchronization

📋 Automated List Management

⚙️ Configuration

🔍 Finding the Correct Listmonk API URL

Method 1: Using Docker Inspect (Recommended)

Method 2: Using Docker Network Inspection

Method 3: Using Container Names (Docker Compose)

Method 4: Check Docker Compose Logs

Method 5: Testing Connectivity

Common IP Ranges

Troubleshooting Connection Issues

Example Working Configuration

📊 Admin Features

Real-Time Status Monitoring

Bulk Operations

List Management

🔌 API Integration Points

Admin Listmonk Endpoints (requires admin privileges)

🚀 Getting Started with Listmonk

🔍 Status Indicators

📈 Benefits

🔧 Troubleshooting

API Endpoints

Public Endpoints

Shifts Endpoints (requires authentication)

Shifts Admin Endpoints (requires admin privileges)

Authentication Endpoints

Admin Endpoints (requires admin privileges)

User Management Endpoints (requires admin privileges)

Cuts Endpoints

Public Cuts Endpoints (requires authentication)

Admin Cuts Endpoints (requires admin privileges)

Geocoding Endpoints (requires authentication)

Shifts Management

User Features

Admin Features

Shift Status System

Cut Feature - Geographic Overlays

Admin Cut Creation

Cut Properties

Cut Management

Public Cut Display

Use Cases

Unified Search System

Search Modes

Features

Documentation Search

Address Search

Database Search

Configuration

Rate Limiting

Admin Panel

Features

Dashboard Analytics

Start Location Configuration

Walk Sheet Generator

Shift Management

User Management

Cut Management

Convert Data

Access Control

README.md