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)
- **`.env.example`** - Template for environment configuration
- **`docker-compose.yml`** - Docker container orchestration for development/production
- **`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
  - `send()` - Process and send emails to representatives
  - `getLogs()` - Retrieve email history with filtering
  - Integrates with SMTP service and logs to database

### 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
  - 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()`
  - Handles users table operations for authentication system
  - CRUD operations for representatives, emails, postal codes
  - Table ID mapping and API client configuration
  - Error handling with graceful degradation
  - Caching logic with automatic retry mechanisms

- **`represent-api.js`** - Represent OpenNorth API integration
  - Postal code lookup against Canadian electoral data
  - Representative data fetching and processing
  - API response transformation and error handling
  - Support for both concordance and centroid representative data

- **`email.js`** - SMTP email service
  - Email composition and HTML template rendering
  - SMTP client configuration and sending
  - Delivery confirmation and error handling
  - Email logging and status tracking

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

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

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

## 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
- **Configuration** → Flexible SMTP provider support

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