freealberta/mkdocs/docs/build/influence.md

# Influence Build Guide

Influence is BNKops campaign tool for connecting Alberta residents with their elected representatives across all levels of government.

!!! info "Complete Configuration"
    For detailed configuration, usage instructions, and troubleshooting, see the main [Influence README](https://gitea.bnkops.com/admin/changemaker.lite/src/branch/main/influence/README.MD).

!!! tip "Email Testing"
    The application includes MailHog integration for safe email testing during development. All test emails are caught locally and never sent to actual representatives.

## Prerequisites

- Docker and Docker Compose installed
- NocoDB instance with API access
- SMTP email configuration (or use MailHog for testing)
- Domain name (optional but recommended for production)

## Quick Build Process

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

Navigate to the influence directory and create your environment file:

```bash
cd influence
cp example.env .env
```

Edit the `.env` file with your configuration:

```env
# Server Configuration
NODE_ENV=production
PORT=3333

# NocoDB Configuration
NOCODB_API_URL=https://your-nocodb-instance.com
NOCODB_API_TOKEN=your_nocodb_api_token_here
NOCODB_PROJECT_ID=your_project_id_here

# Email Configuration (Production 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=BNKops Influence Campaign
SMTP_FROM_EMAIL=your_email@gmail.com

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100
```

#### Development Mode Configuration

For development and testing, use MailHog to catch emails:

```env
# Development Mode
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="BNKops Influence Campaign (DEV)"

# Email Testing
TEST_EMAIL_RECIPIENT=developer@example.com
```

### 3. Auto-Create Database Structure

Run the build script to create required NocoDB tables:

```bash
chmod +x scripts/build-nocodb.sh
./scripts/build-nocodb.sh
```

This creates six tables:
- **Campaigns** - Campaign configurations with email templates and settings
- **Campaign Emails** - Tracking of all emails sent through campaigns
- **Representatives** - Cached representative data by postal code
- **Email Logs** - System-wide email delivery logs
- **Postal Codes** - Canadian postal code geolocation data
- **Users** - Admin authentication and access control

### 4. Build and Deploy

Build the Docker image and start the application:

```bash
# Build the Docker image
docker compose build

# Start the application (includes MailHog in development)
docker compose up -d
```

## Verify Installation

1. Check container status:
   ```bash
   docker compose ps
   ```

2. View logs:
   ```bash
   docker compose logs -f app
   ```

3. Access the application:
   - **Main App**: http://localhost:3333
   - **Admin Panel**: http://localhost:3333/admin.html
   - **Email Testing** (dev): http://localhost:3333/email-test.html
   - **MailHog UI** (dev): http://localhost:8025

## Initial Setup

### 1. Create Admin User

Access the admin panel at `/admin.html` and create your first administrator account.

### 2. Create Your First Campaign

1. Login to the admin panel
2. Click **"Create Campaign"**
3. Configure basic settings:
   - Campaign title and description
   - Email subject and body template
   - Upload cover photo (optional)
4. Set campaign options:
   - ✅ Allow SMTP Email - Enable server-side sending
   - ✅ Allow Mailto Link - Enable browser-based mailto
   - ✅ Collect User Info - Request name and email
   - ✅ Show Email Count - Display engagement metrics
   - ✅ Allow Email Editing - Let users customize message
5. Select target government levels (Federal, Provincial, Municipal, School Board)
6. Set status to **Active** to make campaign public
7. Click **"Create Campaign"**

### 3. Test Representative Lookup

1. Visit the homepage
2. Enter an Alberta postal code (e.g., T5N4B8)
3. View representatives at all government levels
4. Test email sending functionality

## Development Workflow

### Email Testing Interface

Access the email testing interface at `/email-test.html` (requires admin login):

**Features:**
- 📧 **Quick Test** - Send test email with one click
- 👁️ **Email Preview** - Preview email formatting before sending
- ✏️ **Custom Composition** - Test with custom subject and message
- 📊 **Email Logs** - View all sent emails with filtering
- 🔧 **SMTP Diagnostics** - Test connection and troubleshoot

### MailHog Web Interface

Access MailHog at http://localhost:8025 to:
- View all caught emails during development
- Inspect email content, headers, and formatting
- Search and filter test emails
- Verify emails never leave your local environment

### Switching to Production

When ready to deploy to production:

1. Update `.env` with production SMTP settings:
   ```env
   EMAIL_TEST_MODE=false
   NODE_ENV=production
   SMTP_HOST=smtp.your-provider.com
   SMTP_USER=your-real-email@domain.com
   SMTP_PASS=your-real-password
   ```

2. Restart the application:
   ```bash
   docker compose restart
   ```

## Key Features

### Representative Lookup
- Search by Alberta postal code (T prefix)
- Display federal MPs, provincial MLAs, municipal representatives
- Smart caching with NocoDB for fast performance
- Graceful fallback to Represent API when cache unavailable

### Campaign System
- Create unlimited advocacy campaigns
- Upload cover photos for campaign pages
- Customizable email templates
- Optional user information collection
- Toggle email count display for engagement metrics
- Multi-level government targeting

### Email Integration
- SMTP email sending with delivery confirmation
- Mailto link support for browser-based email
- Comprehensive email logging
- Rate limiting for API protection
- Test mode for safe development

## API Endpoints

### Public Endpoints
- `GET /` - Homepage with representative lookup
- `GET /campaign/:slug` - Individual campaign page
- `GET /api/public/campaigns` - List active campaigns
- `GET /api/representatives/by-postal/:postalCode` - Find representatives
- `POST /api/emails/send` - Send campaign email

### Admin Endpoints (Authentication Required)
- `GET /admin.html` - Campaign management dashboard
- `GET /email-test.html` - Email testing interface
- `POST /api/emails/preview` - Preview email without sending
- `POST /api/emails/test` - Send test email
- `GET /api/test-smtp` - Test SMTP connection

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

### View Logs
```bash
# Follow application logs
docker compose logs -f app

# View MailHog logs (development)
docker compose logs -f mailhog
```

### Database Backup
```bash
# Backup is handled through NocoDB
# Access NocoDB admin panel to export tables
```

### Health Check
```bash
curl http://localhost:3333/api/health
```

## Troubleshooting

### NocoDB Connection Issues
- Verify `NOCODB_API_URL` and `NOCODB_API_TOKEN` in `.env`
- Run `./scripts/build-nocodb.sh` to ensure tables exist
- Application works without NocoDB (API fallback mode)

### Email Not Sending
- In development: Check MailHog UI at http://localhost:8025
- Verify SMTP credentials in `.env`
- Use `/email-test.html` interface for diagnostics
- Check email logs via admin panel
- Review `docker compose logs -f app` for errors

### No Representatives Found
- Ensure postal code starts with 'T' (Alberta only)
- Try different postal code format (remove spaces)
- Check Represent API status: `curl http://localhost:3333/api/test-represent`
- Review application logs for API errors

### Campaign Not Appearing
- Verify campaign status is set to "Active"
- Check campaign configuration in admin panel
- Clear browser cache and reload homepage
- Review console for JavaScript errors

## Production Deployment

### Environment Configuration
```env
NODE_ENV=production
EMAIL_TEST_MODE=false
PORT=3333

# Use production SMTP settings
SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-production-email@domain.com
SMTP_PASS=your-production-password
```

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

# Monitor health
watch curl http://localhost:3333/api/health
```

### Monitoring
- Health check endpoint: `/api/health`
- Email logs via admin panel
- NocoDB integration status in logs
- Rate limiting metrics in application logs

## Security Considerations

- 🔒 Always use strong passwords for admin accounts
- 🔒 Enable HTTPS in production (use reverse proxy)
- 🔒 Rotate SMTP credentials regularly
- 🔒 Monitor email logs for suspicious activity
- 🔒 Set appropriate rate limits based on expected traffic
- 🔒 Keep NocoDB API tokens secure and rotate periodically
- 🔒 Use `EMAIL_TEST_MODE=false` only in production

## Support

For detailed configuration, troubleshooting, and usage instructions, see:
- [Main Influence README](https://gitea.bnkops.com/admin/changemaker.lite/src/branch/main/influence/README.MD)
- [Campaign Settings Guide](https://gitea.bnkops.com/admin/changemaker.lite/src/branch/main/influence/CAMPAIGN_SETTINGS_GUIDE.md)
- [Files Explainer](https://gitea.bnkops.com/admin/changemaker.lite/src/branch/main/influence/files-explainer.md)