347 lines
9.7 KiB
Markdown
347 lines
9.7 KiB
Markdown
# BNKops Influence Campaign Tool
|
|
|
|
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
|
|
|
|
1. **Clone and navigate to the project**:
|
|
```bash
|
|
cd /path/to/changemaker.lite/influence
|
|
```
|
|
|
|
2. **Configure environment**:
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your configuration
|
|
```
|
|
|
|
3. **Set up NocoDB tables**:
|
|
```bash
|
|
./scripts/build-nocodb.sh
|
|
```
|
|
|
|
4. **Start the application**:
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
5. **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
|
|
|
|
1. **Use development configuration**:
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
2. **Start with MailHog included**:
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
3. **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
|
|
|
|
1. **Safe Development**:
|
|
```bash
|
|
# Ensure test mode is enabled
|
|
EMAIL_TEST_MODE=true
|
|
|
|
# Start development environment
|
|
docker compose up --build
|
|
```
|
|
|
|
2. **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
|
|
|
|
3. **Production Deployment**:
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
|
|
1. **NocoDB Connection Errors**:
|
|
- Check API URL and token in .env
|
|
- Run `./scripts/build-nocodb.sh` to setup tables
|
|
- Application works without NocoDB (API fallback)
|
|
|
|
2. **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
|
|
|
|
3. **No Representatives Found**:
|
|
- Ensure postal code starts with 'T' (Alberta)
|
|
- Check Represent API status
|
|
- Try different postal code format
|
|
|
|
### Log Analysis
|
|
```bash
|
|
# 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.
|
|
|