freealberta/influence/DEPLOYMENT_GUIDE.md

Response Wall Verification Feature - Deployment Guide

Overview

This guide walks you through deploying the new Response Wall verification features that were added to the Influence Campaign Tool.

Features Implemented

1. Postal Code Lookup for Response Submission

• Users can search by postal code to find their representatives
• Auto-fills representative details when selected
• Validates Alberta postal codes (T prefix)
• Fallback to manual entry if needed

2. Representative Verification System

• Optional email verification for submitted responses
• Representatives receive verification emails with unique tokens
• Representatives can verify or report responses
• Verified responses display with special badge
• Disputed responses are hidden from public view

Deployment Steps

Step 1: Update Database Schema

Run the NocoDB setup script to create/update tables with new verification fields:

cd /path/to/influence
./scripts/build-nocodb.sh

If you already have existing tables, you'll need to manually add the new columns through NocoDB UI:

1. Log into your NocoDB instance
2. Open the influence_representative_responses table
3. Add these columns:
   • representative_email - Type: Email, Required: No
   • verification_token - Type: SingleLineText, Required: No
   • verification_sent_at - Type: DateTime, Required: No
   • verified_at - Type: DateTime, Required: No
   • verified_by - Type: SingleLineText, Required: No

Step 2: Update Environment Variables

Add these variables to your .env file:

# Application Name (used in emails)
APP_NAME="BNKops Influence"

# Base URL for verification links
BASE_URL=https://yourdomain.com

# Existing variables to verify:
SMTP_HOST=your-smtp-host
SMTP_PORT=587
SMTP_USER=your-email@domain.com
SMTP_PASS=your-password
SMTP_FROM_EMAIL=your-email@domain.com
SMTP_FROM_NAME="Your Campaign Name"

⚠️ Important: The BASE_URL must be your production domain for verification links to work correctly.

Step 3: Rebuild Docker Container (if using Docker)

cd /path/to/influence
docker compose build
docker compose up -d

Step 4: Verify Email Templates

Ensure the email templates are in place:

ls -la app/templates/email/

You should see:

• response-verification.html
• response-verification.txt

Step 5: Test the Feature

Test Postal Code Lookup:

1. Go to any campaign's Response Wall
2. Click "Share a Response"
3. Enter postal code (e.g., T5K 2J1)
4. Click Search
5. Verify representatives appear
6. Select a representative
7. Confirm form auto-fills

Test Verification Email:

1. Complete the form with all required fields
2. Check "Send verification request to representative"
3. Submit the response
4. Check that confirmation message mentions email sent
5. Check representative's email inbox for verification email

Test Verification Flow:

1. Open verification email
2. Click "Verify This Response" button
3. Should see green success page
4. Check Response Wall - response should have verified badge
5. Check admin panel - response should be auto-approved

Test Report Flow:

1. Open verification email for a different response
2. Click "Report as Invalid" button
3. Should see warning page
4. Check Response Wall - response should be hidden
5. Check admin panel - response should be marked as rejected

Production Checklist

• Database schema updated with new verification fields
• Environment variables configured (APP_NAME, BASE_URL)
• Email templates exist and are readable
• SMTP settings are correct and tested
• Docker container rebuilt and running
• Postal code search tested successfully
• Verification email sent and received
• Verification link works and updates database
• Report link works and hides response
• Verified badge displays on Response Wall
• Admin panel shows verification status correctly

Security Notes

1. Token Security: Verification tokens are 32-byte cryptographically secure random strings
2. Token Expiry: Consider implementing token expiration (currently no expiry - tokens work indefinitely)
3. Rate Limiting: Existing rate limiting applies to submission endpoint
4. Email Validation: Representative emails are validated on backend
5. XSS Prevention: All user inputs are sanitized before display

Troubleshooting

Verification Emails Not Sending

• Check SMTP settings in .env
• Verify SMTP credentials are correct
• Check application logs: docker logs influence-app -f
• Test email connection: Use email test page at /email-test.html

Postal Code Search Returns No Results

• Verify Represent API is accessible
• Check REPRESENT_API_BASE in .env
• Ensure postal code is Alberta format (starts with T)
• Check browser console for errors

Verification Links Don't Work

• Verify BASE_URL in .env matches your domain
• Check that verification token was saved to database
• Ensure response ID is correct
• Check application logs for errors

Representative Dropdown Not Populating

• Check browser console for JavaScript errors
• Verify api-client.js is loaded in HTML
• Ensure API endpoint /api/representatives/by-postal/:code is accessible
• Check network tab for API response

Rollback Plan

If you need to rollback this feature:

1. Frontend Only Rollback:

   # Restore old files
   git checkout HEAD~1 -- app/public/response-wall.html
   git checkout HEAD~1 -- app/public/js/response-wall.js
   git checkout HEAD~1 -- app/public/css/response-wall.css
   

2. Full Rollback (including backend):

   # Restore all files
   git checkout HEAD~1
   docker compose build
   docker compose up -d
   

3. Database Cleanup (optional):

   • The new columns don't hurt anything if left in place
   • You can manually remove them through NocoDB UI if desired

Support

For issues or questions:

• Check application logs: docker logs influence-app -f
• Review RESPONSE_WALL_UPDATES.md for implementation details
• Check files-explainer.md for file structure information

Next Steps

Recommended Enhancements:

1. Token Expiration: Implement 30-day expiration for verification tokens
2. Email Notifications: Notify submitter when representative verifies
3. Analytics Dashboard: Track verification rates and response authenticity
4. Bulk Verification: Allow representatives to verify multiple responses at once
5. Representative Dashboard: Create dedicated portal for representatives to manage responses

Future Features:

1. Support for other provinces beyond Alberta
2. SMS verification option
3. Representative accounts for ongoing engagement
4. Response comment system for public discussion
5. Export verified responses for accountability reporting