freealberta/influence/files-explainer.md

Alberta Influence Campaign Tool - File Structure Explanation

This document explains the purpose and functionality of each file in the Alberta Influence Campaign Tool.

Authentication System

The application includes a complete authentication system for admin panel access, following the same patterns used in the map application. Authentication is implemented using NocoDB as the user database and express-session for session management.

Root Directory Files

Configuration Files

• .env - Environment variables (database URLs, SMTP config, API keys, email testing config)
• .env.development - Development environment configuration with MailHog SMTP settings
• .env.example - Template for environment configuration
• docker-compose.yml - Docker container orchestration with MailHog for email testing
• Dockerfile - Container definition for the Node.js application
• package.json - Node.js dependencies and scripts
• package-lock.json - Locked dependency versions for reproducible builds

Documentation

• README.MD - Main project documentation with setup and usage instructions
• files-explainer.md - This file, explaining the project structure
• instruct.md - Implementation instructions and development notes

Application Structure (app/)

Entry Point

• server.js - Express.js application entry point, middleware setup, route mounting

Controllers (app/controllers/)

Business logic layer that handles HTTP requests and responses:

• authController.js - Authentication controller for admin login/logout

  • login() - Handles admin login with email/password validation
  • logout() - Destroys user session and logs out
  • checkSession() - Verifies current authentication status
  • Integrates with NocoDB users table for credential verification
  • Updates last login timestamps and manages session state

• representatives.js - Core functionality for postal code lookups

  • getByPostalCode() - Main endpoint for finding representatives
  • refreshPostalCode() - Force refresh of cached data
  • testConnection() - Health check for Represent API
  • Handles caching logic and fallback to API when cache fails

• emails.js - Email composition and sending functionality

  • sendEmail() - Process and send emails to representatives with test mode support
  • previewEmail() - Generate email preview without sending for testing purposes
  • sendTestEmail() - Send test emails to configured test recipient
  • getEmailLogs() - Retrieve email history with filtering and pagination
  • testSMTPConnection() - Test SMTP server connectivity for diagnostics
  • Integrates with SMTP service and logs to database with test mode tracking

Routes (app/routes/)

API endpoint definitions and request validation:

• auth.js - Authentication API routes

  • POST /api/auth/login - Admin login endpoint
  • POST /api/auth/logout - Admin logout endpoint
  • GET /api/auth/session - Session verification endpoint
  • Handles authentication requests with proper validation and error handling

• api.js - Main API routes with validation middleware

  • Representatives endpoints with postal code validation
  • Email endpoints with input sanitization and test mode support
  • Email testing endpoints: /api/emails/preview, /api/emails/test, /api/emails/logs
  • SMTP testing endpoint: /api/test-smtp for connection diagnostics
  • Health check and testing endpoints
  • Rate limiting and error handling middleware

Services (app/services/)

External system integrations and data access layer:

• nocodb.js - NocoDB database integration

  • User management methods: getUserByEmail(), createUser(), updateUser(), getAllUsers() /* Lines 76-80 omitted */
  • Caching logic with automatic retry mechanisms

• represent-api.js - Represent OpenNorth API integration

  • Postal code lookup against Canadian electoral data /* Lines 84-86 omitted */
  • Support for both concordance and centroid representative data

• emailTemplates.js - Email template service for managing HTML/text email templates

  • Template loading and caching system with support for conditional blocks
  • Variable replacement and template processing for dynamic content
  • Template rendering for both HTML and text formats with fallback support
  • Available templates: representative-contact, campaign-email, test-email

• email.js - SMTP email service with comprehensive testing support

  • Template-based email composition using emailTemplates service
  • Legacy sendEmail method for backward compatibility
  • New templated methods: sendRepresentativeEmail(), sendCampaignEmail(), sendTestEmail()
  • Email preview functionality with template support
  • SMTP connection testing for diagnostics and troubleshooting

Utilities (app/utils/)

Helper functions and shared utilities:

• validation.js - Input validation and sanitization

  • Postal code format validation (Alberta T-prefix)
  • Email address validation
  • HTML content sanitization for security

• rate-limiter.js - API rate limiting configuration

  • Different limits for various endpoint types
  • IP-based rate limiting with sliding windows
  • Configurable limits via environment variables

Middleware (app/middleware/)

Express.js middleware functions:

• auth.js - Authentication middleware for protecting routes
  • requireAuth() - Ensures user is logged in
  • requireAdmin() - Ensures user is logged in and has admin privileges
  • Redirects unauthenticated requests to login page
  • Sets up req.user object for authenticated requests
  • Standardized error response formatting
  • Error logging and classification
  • Production vs development error detail levels

Email Templates (app/templates/email/)

Professional HTML and text email templates with variable substitution:

• representative-contact.html/.txt - Template for direct constituent communications

  • Variables: MESSAGE, SENDER_NAME, SENDER_EMAIL, POSTAL_CODE, APP_NAME, TIMESTAMP
  • Professional styling with constituent information display and platform branding

• campaign-email.html/.txt - Template for organized campaign emails

  • Variables: MESSAGE, USER_NAME, USER_EMAIL, POSTAL_CODE, CAMPAIGN_TITLE, RECIPIENT_NAME, RECIPIENT_LEVEL
  • Campaign-specific styling with participant information and campaign branding
  • Conditional recipient information display

• test-email.html/.txt - Template for email system testing

  • Variables: MESSAGE, APP_NAME, TIMESTAMP
  • Warning styling and test indicators for system verification emails

Frontend Assets (app/public/)

HTML

• index.html - Main application interface

• login.html - Admin login page

  • Clean, professional login interface for admin access
  • Email/password form with client-side validation
  • Integration with authentication API
  • Automatic redirect to admin panel on successful login
  • Session persistence and auto-login detection

• admin.html - Campaign management admin panel (protected)

  • Requires admin authentication to access
  • Includes authentication checks and user info display
  • Logout functionality integrated into interface
  • Postal code input form with validation
  • Representatives display sections
  • Email composition modal
  • Responsive design with accessibility features

• email-test.html - Comprehensive email testing interface (admin-only)

  • Protected admin interface for email testing and diagnostics
  • Quick test email functionality with one-click testing
  • Email preview system to see emails before sending
  • Email composition form with real-time preview
  • Email logs viewer with filtering by test/live mode
  • SMTP connection testing and diagnostics
  • Current configuration display showing test mode status
  • Real-time feedback and error handling for all operations

Stylesheets (app/public/css/)

• styles.css - Complete application styling
  • Responsive grid layouts for representative cards
  • Photo display with fallback styling
  • Modal and form styling
  • Mobile-first responsive design
  • Loading states and error message styling

JavaScript (app/public/js/)

• main.js - Application initialization and utilities

  • Global error handling and message display system
  • Utility functions (postal code formatting, sanitization)
  • Mobile detection and responsive behavior

• api-client.js - Frontend API communication

  • HTTP client with error handling
  • API endpoint wrappers for all backend services
  • Request/response processing and error propagation

• postal-lookup.js - Postal code search functionality

  • Form handling and input validation
  • API integration for representative lookup
  • Loading states and error display
  • Results processing and display coordination

• representatives-display.js - Representative data presentation

  • Dynamic HTML generation for representative cards
  • Photo display with fallback to initials
  • Government level categorization and sorting
  • Contact information formatting and display

• auth.js - Client-side authentication management

  • AuthManager class for handling login/logout operations
  • Session state management and persistence
  • UI updates based on authentication status
  • Auto-redirect for protected pages requiring authentication
  • Integration with login forms and logout buttons

• email-composer.js - Email composition interface

  • Modal-based email composition form
  • Pre-population of recipient data
  • Form validation and submission handling
  • Success/error feedback to users

• email-testing.js - Comprehensive email testing interface management

  • EmailTesting class managing all testing functionality
  • Quick test email sending with default content
  • SMTP connection testing and diagnostics
  • Email preview generation with real-time rendering
  • Test email sending with form validation
  • Email logs management with filtering and pagination
  • Configuration status display and management
  • Real-time UI updates and error handling
  • Integration with authentication system for admin protection

Scripts Directory (scripts/)

• build-nocodb.sh - Database setup automation
  • Now includes users table creation for authentication system
  • Creates influence_users table with email, name, password, admin flag, and last_login fields
  • Updates .env file with NOCODB_TABLE_USERS configuration
  • Creates NocoDB base and tables using v2 API
  • Configures table schemas for representatives, emails, postal codes
  • Handles authentication and error recovery
  • Updates environment with new base ID

Data Flow Architecture

Request Processing Flow

1. User Input → Postal code entered in frontend form
2. Validation → Client-side and server-side validation
3. Cache Check → NocoDB queried for existing data
4. API Fallback → Represent API called if cache miss or NocoDB down
5. Data Processing → Representative data normalized and processed
6. Caching → Results stored in NocoDB for future requests
7. Response → Formatted data returned to frontend
8. Display → Representatives rendered with photos and contact info

Email Flow

1. Composition → User fills email form in modal
2. Validation → Input sanitization and validation
3. Processing → Email formatted and prepared for sending
4. SMTP Delivery → Email sent via configured SMTP service
5. Logging → Email attempt logged to database
6. Confirmation → User notified of success/failure

Error Handling Strategy

• Graceful Degradation → App works even if NocoDB is down
• User Feedback → Clear error messages and recovery suggestions
• Logging → Comprehensive error logging for debugging
• Fallbacks → Multiple data sources and retry mechanisms

Key Integration Points

Authentication System

• Admin Login → Email/password authentication for admin panel access
• Session Management → Express-session with secure cookie configuration
• Route Protection → Middleware-based protection for admin endpoints and pages
• User Management → NocoDB-based user storage with admin role support
• Security → Password validation, session expiration, and automatic logout

NocoDB Integration

• Authentication → Token-based API authentication
• User Storage → Users table with email, password, admin flag, and login tracking
• Table Management → Dynamic table ID resolution
• Error Recovery → Automatic fallback to API when database unavailable
• Performance → Efficient caching with intelligent cache invalidation

Represent API Integration

• Data Sources → Both concordance and centroid representative data
• Rate Limiting → Respectful API usage with built-in rate limiting
• Error Handling → Robust error handling with user-friendly messages
• Data Processing → Normalization of API responses for consistent display

SMTP Integration

• Security → Secure authentication and encrypted connections
• Reliability → Error handling and delivery confirmation
• Logging → Complete audit trail of email activity with test mode tracking
• Configuration → Flexible SMTP provider support with development/production modes
• Testing → Comprehensive test mode with email redirection and preview capabilities

Email Testing System

• Test Mode → Automatic email redirection to configured test recipient
• Preview System → Generate email previews without sending for content review
• SMTP Diagnostics → Connection testing and troubleshooting tools
• Email Logging → Complete audit trail with test/live mode classification
• Development Tools → MailHog integration for local email catching and review
• Admin Interface → Dedicated testing interface accessible only to authenticated admins

Docker Configuration

• Production Mode → Standard application container with external SMTP
• Development Mode → Application + MailHog containers for local email testing
• Profile-based Deployment → MailHog only runs in development profile
• Email Catching → All development emails caught by MailHog web interface at port 8025
• Environment Flexibility → Easy switching between development and production SMTP settings

Development Patterns

Error Handling

• All async operations wrapped in try-catch blocks
• Consistent error response formatting across APIs
• User-friendly error messages with technical details logged
• Graceful degradation when external services unavailable

Data Validation

• Input validation at both client and server levels
• Sanitization to prevent XSS and injection attacks
• Type checking and format validation throughout
• Clear validation error messages for users

Performance Optimization

• Smart caching with configurable TTL
• Lazy loading of images and non-critical resources
• Efficient database queries with minimal data transfer
• Client-side debouncing for user inputs

Security Measures

• Authentication Protection → Admin panel and API endpoints protected by login
• Session Security → HttpOnly cookies, secure session configuration, automatic expiration
• Rate limiting to prevent abuse
• Input sanitization and validation
• Secure SMTP configuration
• Environment variable protection of sensitive data

This architecture provides a robust, scalable, and maintainable solution for connecting Alberta residents with their elected representatives.