freealberta/influence/files-explainer.md

# BNKops Influence Campaign Tool - File Structure Explanation

This document explains the purpose and functionality of each file in the BNKops 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.