A comprehensive web application that helps Alberta residents connect with their elected representatives across all levels of government. Users can find their representatives by postal code and send direct emails to advocate for important issues.

Features

Representative Lookup: Find elected officials by Alberta postal code (T prefixed)
Multi-Level Government: Displays federal MPs, provincial MLAs, and municipal representatives
Contact Information: Shows photos, email addresses, phone numbers, and office locations
Direct Email: Built-in email composer to contact representatives
Smart Caching: Fast performance with NocoDB caching and graceful fallback to live API
Responsive Design: Works seamlessly on desktop and mobile devices
Real-time Data: Integrates with Represent OpenNorth API for up-to-date information

Technology Stack

Backend: Node.js with Express.js
Database: NocoDB (REST API)
External API: Represent OpenNorth Canada API
Frontend: Vanilla JavaScript, HTML5, CSS3
Email: SMTP integration
Deployment: Docker with docker-compose
Rate Limiting: Express rate limiter for API protection

Quick Start

Prerequisites

Docker and Docker Compose
Access to existing NocoDB instance
SMTP email configuration

Installation

Clone and navigate to the project:
```
cd /path/to/changemaker.lite/influence
```

Configure environment:

cp .env.example .env
# Edit .env with your configuration

Set up NocoDB tables:
```
./scripts/build-nocodb.sh
```
Start the application:
```
docker compose up --build
```
Access the application:
- Open http://localhost:3333
- Enter an Alberta postal code (e.g., T5N4B8)
- View your representatives and send emails

Development Mode

Email Testing with MailHog

For development and testing, the application includes MailHog integration to safely test email functionality without sending real emails to elected officials.

Quick Setup for Development

Use development configuration:

# Your .env should include these settings for development:
NODE_ENV=development
EMAIL_TEST_MODE=true
SMTP_HOST=mailhog
SMTP_PORT=1025
SMTP_USER=test
SMTP_PASS=test
TEST_EMAIL_RECIPIENT=your-email@example.com

Start with MailHog included:
```
docker compose up --build
```
Access development tools:
- Application: http://localhost:3333
- Email Testing Interface: http://localhost:3333/email-test.html (admin login required)
- MailHog Web UI: http://localhost:8025 (view all caught emails)

Email Testing Features

Test Mode Benefits:

✅ All emails redirected to your test recipient
✅ Original recipient shown in subject line: [TEST - Original: real@email.com] Subject
✅ Safe testing without spamming elected officials
✅ Complete email logging with test mode indicators

Email Testing Interface (/email-test.html):

Quick Test: Send test email with one click
Email Preview: See exactly how emails will look before sending
Custom Composition: Test with your own subject and message content
Email Logs: View all sent emails with test/live filtering
SMTP Diagnostics: Test connection and troubleshoot issues

MailHog Web Interface (http://localhost:8025):

View all emails caught during development
Inspect email content, headers, and formatting
Search and filter caught emails
No emails leave your local environment

Development Workflow

Safe Development:

# Ensure test mode is enabled
EMAIL_TEST_MODE=true

# Start development environment
docker compose up --build

Test Email Functionality:
- Use the main app to send emails (they'll be redirected)
- Check MailHog UI to see the actual email content
- Use /email-test.html for advanced testing and preview

Production Deployment:

# Switch to production SMTP settings
EMAIL_TEST_MODE=false
SMTP_HOST=smtp.your-provider.com
SMTP_USER=your-real-email@domain.com
SMTP_PASS=your-real-password

# Restart application
docker compose restart

Development Environment Variables

# Development Mode Configuration
NODE_ENV=development
EMAIL_TEST_MODE=true

# MailHog SMTP (for development)
SMTP_HOST=mailhog
SMTP_PORT=1025
SMTP_SECURE=false
SMTP_USER=test
SMTP_PASS=test
SMTP_FROM_EMAIL=dev@albertainfluence.local
SMTP_FROM_NAME="Alberta Influence Campaign (DEV)"

# Email Testing
TEST_EMAIL_RECIPIENT=developer@example.com

# Production SMTP (commented out for dev)
# SMTP_HOST=smtp.protonmail.ch
# SMTP_PORT=587
# SMTP_USER=your-production-email@domain.com
# SMTP_PASS=your-production-password

Configuration

Environment Variables (.env)

# Server Configuration
NODE_ENV=production
PORT=3333

# NocoDB Configuration
NOCODB_API_URL=https://db.cmlite.org
NOCODB_API_TOKEN=your_nocodb_token
NOCODB_PROJECT_ID=your_project_id

# Email Configuration (SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_app_password
SMTP_FROM_NAME=Alberta Influence Campaign
SMTP_FROM_EMAIL=your_email@gmail.com

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

API Endpoints

Representatives

GET /api/representatives/by-postal/:postalCode - Get representatives by postal code
POST /api/representatives/refresh-postal/:postalCode - Refresh cached data

Email

POST /api/emails/send - Send email to representative
GET /api/emails/logs - Get email sending logs (with filters)

Email Testing (Development)

POST /api/emails/preview - Preview email without sending (admin only)
POST /api/emails/test - Send test email to configured recipient (admin only)
GET /api/test-smtp - Test SMTP connection (admin only)

Health

GET /api/health - Application health check
GET /api/test-represent - Test Represent API connection

Database Schema

Representatives Table

postal_code, name, email, district_name
elected_office, party_name, representative_set_name
url, photo_url, cached_at

Emails Table

recipient_email, recipient_name, sender_email
subject, message, status, sent_at

Postal Codes Table

postal_code, city, province
centroid_lat, centroid_lng, last_updated

Development

Project Structure

influence/
├── app/
│   ├── controllers/     # Business logic
│   ├── routes/         # API routes
│   ├── services/       # External integrations
│   ├── utils/          # Helper functions
│   ├── middleware/     # Express middleware
│   ├── public/         # Frontend assets
│   └── server.js       # Express app entry point
├── scripts/
│   └── build-nocodb.sh # Database setup
├── docker-compose.yml  # Container orchestration
├── Dockerfile         # Container definition
└── .env              # Environment configuration

Key Components

RepresentativesController: Handles postal code lookups and caching
EmailController: Manages email composition, sending, and testing
NocoDBService: Database operations with error handling
RepresentAPI: Integration with OpenNorth Represent API
EmailService: SMTP email functionality with test mode support
Email Testing System: Preview, test, and log email functionality for development

Features in Detail

Smart Caching System

First request fetches from Represent API and caches in NocoDB
Subsequent requests served from cache for fast performance
Graceful fallback to API when NocoDB is unavailable
Automatic error recovery and retry logic

Representative Display

Shows photo with fallback to initials
Contact information including phone and address
Party affiliation and government level
Direct links to official profiles

Email Integration

Modal-based email composer
Pre-filled recipient information
SMTP sending with delivery confirmation
Email history and logging

Error Handling

Comprehensive error logging
User-friendly error messages
API fallback mechanisms
Rate limiting protection

Production Deployment

Docker Production

# Build and start in production mode
docker compose -f docker-compose.yml up -d --build

# View logs
docker compose logs -f app

# Scale if needed
docker compose up --scale app=2

Monitoring

Health check endpoint: /api/health
Application logs via Docker
NocoDB integration status monitoring
Email delivery tracking

Troubleshooting

Common Issues

NocoDB Connection Errors:
- Check API URL and token in .env
- Run ./scripts/build-nocodb.sh to setup tables
- Application works without NocoDB (API fallback)
Email Not Sending:
- Verify SMTP credentials in .env
- Check spam/junk folders
- Review email logs via API endpoint
- In development: Check MailHog UI at http://localhost:8025
- Use email testing interface at /email-test.html for diagnostics
No Representatives Found:
- Ensure postal code starts with 'T' (Alberta)
- Check Represent API status
- Try different postal code format

Log Analysis

# View application logs
docker compose logs app

# Follow logs in real-time
docker compose logs -f app

# Check specific errors
docker compose logs app | grep ERROR

Contributing

This is part of the larger changemaker.lite project. Follow the established patterns for:

Error handling and logging
API response formats
Database integration
Frontend component structure

License

Part of the changemaker.lite project ecosystem.