# Changemaker Lite V2 Documentation

!!! success "V2 is Production Ready"
    Changemaker Lite V2 is a complete architectural rebuild now running in production. This documentation covers the modern TypeScript stack with dual API architecture, React admin interface, and comprehensive feature modules.

## Overview

Changemaker Lite V2 is a self-hosted political campaign platform that consolidates advocacy email campaigns, geographic mapping, volunteer management, and administration into a single unified TypeScript stack.

### Key Highlights

- **Dual API Architecture**: Express.js (main features) + Fastify (media library)
- **Modern Stack**: TypeScript, Prisma + Drizzle ORM, PostgreSQL 16, Redis
- **React Admin**: Vite + Ant Design + Zustand state management
- **JWT Authentication**: Secure role-based access control with refresh tokens
- **Comprehensive Features**: 14 backend modules, 42 frontend pages, 8 critical services
- **Production Monitoring**: Prometheus, Grafana, Alertmanager with 12 custom metrics
- **Security Audited**: 13 findings addressed (Feb 2026)

## Architecture Diagram

```mermaid
graph TB
    User[User Browser]
    Nginx[Nginx Reverse Proxy]
    Admin[React Admin GUI<br/>port 3000]
    ExpressAPI[Express API<br/>port 4000<br/>Prisma ORM]
    FastifyAPI[Fastify Media API<br/>port 4100<br/>Drizzle ORM]
    Postgres[(PostgreSQL 16)]
    Redis[(Redis)]
    BullMQ[BullMQ Queues]
    Listmonk[Listmonk<br/>Newsletter]
    Prometheus[Prometheus<br/>Monitoring]

    User --> Nginx
    Nginx --> |app.cmlite.org| Admin
    Nginx --> |api.cmlite.org| ExpressAPI
    Nginx --> |media.cmlite.org| FastifyAPI

    Admin --> ExpressAPI
    Admin --> FastifyAPI

    ExpressAPI --> Postgres
    ExpressAPI --> Redis
    ExpressAPI --> BullMQ

    FastifyAPI --> Postgres
    FastifyAPI --> Redis

    BullMQ --> Redis
    ExpressAPI --> Listmonk
    ExpressAPI --> Prometheus
    FastifyAPI --> Prometheus
```

## Feature Modules

### Influence Module
Email advocacy campaigns targeting elected representatives with:

- Campaign management with rich text editor
- Canadian representative lookup (postal code → MP/MPP/councillor)
- Public campaign pages with email submission
- Response wall with upvoting and moderation
- BullMQ async email queue with SMTP delivery
- Email verification and tracking

[Learn more →](features/influence/overview.md)

### Map Module
Geographic mapping and volunteer canvassing with:

- Location CRUD with multi-provider geocoding (6 providers)
- Cut (polygon) management with spatial queries
- Volunteer shift scheduling and signup system
- Full canvassing system with GPS tracking and visit recording
- Walk sheets and QR codes for printable forms
- NAR 2025 data import (Canadian electoral data)

[Learn more →](features/map/overview.md)

### Landing Pages
GrapesJS-based page builder with:

- WYSIWYG editor with custom blocks
- Public rendering at `/p/:slug`
- MkDocs export for static documentation
- Mobile-responsive templates

[Learn more →](features/landing-pages/overview.md)

### Email Templates
Template management system with:

- GrapesJS email editor
- Variable substitution
- Integration with campaign emails
- Version control

[Learn more →](features/email-templates/overview.md)

### Media Manager
Video library management with:

- Dual API architecture (Fastify microservice)
- Shared media public gallery
- Reaction system (6 standard emojis)
- Job queue monitoring
- Bulk operations

[Learn more →](features/media/overview.md)

### Newsletter Integration
Listmonk sync with:

- Participant/location/user syncing
- Subscriber list management
- Health monitoring
- API integration

[Learn more →](features/newsletter/overview.md)

### Observability
Comprehensive monitoring with:

- Prometheus metrics (12 custom metrics)
- Grafana dashboards (3 pre-configured)
- Alertmanager notifications
- Service health checks
- Data quality dashboard

[Learn more →](features/observability/overview.md)

## Quick Links

### Getting Started
- [Quick Start Guide](getting-started/quick-start.md) - Get running in 5 minutes
- [Installation](getting-started/installation.md) - Detailed setup instructions
- [Environment Setup](getting-started/environment.md) - Configure your .env file
- [First Login](getting-started/first-login.md) - Access the admin interface

### Architecture
- [Architecture Overview](architecture/index.md) - System design and components
- [Dual API Design](architecture/dual-api.md) - Express + Fastify architecture
- [Database Schema](architecture/database.md) - Prisma + Drizzle models
- [Authentication Flow](architecture/authentication.md) - JWT security model
- [Frontend Architecture](architecture/frontend.md) - React + Vite + Ant Design

### Development
- [Local Development](development/local-setup.md) - Set up your dev environment
- [npm Commands](development/npm-commands.md) - Common development tasks
- [Database Migrations](development/migrations.md) - Schema changes workflow
- [Testing](development/testing.md) - Test strategy and execution
- [Code Style](development/code-style.md) - Standards and patterns

### Deployment
- [Docker Compose](deployment/docker-compose.md) - Service orchestration
- [Nginx Configuration](deployment/nginx.md) - Reverse proxy setup
- [Environment Variables](deployment/environment-variables.md) - Complete reference
- [Monitoring Stack](deployment/monitoring-stack.md) - Prometheus + Grafana
- [Backup & Restore](deployment/backup-restore.md) - Data protection

### API Reference
- [Authentication API](api-reference/auth.md) - Login, register, refresh
- [Campaigns API](api-reference/campaigns.md) - Campaign CRUD
- [Locations API](api-reference/locations.md) - Location management
- [Media API](api-reference/media.md) - Video library
- [Complete API Index](api-reference/index.md) - All endpoints

### User Guides
- [Admin Guide](user-guides/admin-guide.md) - Platform administration
- [Volunteer Guide](user-guides/volunteer-guide.md) - Canvassing workflows
- [Campaign Manager Guide](user-guides/campaign-manager-guide.md) - Running campaigns
- [Map Organizer Guide](user-guides/map-organizer-guide.md) - Location management
- [Content Editor Guide](user-guides/content-editor-guide.md) - Landing pages

## Technology Stack

### Backend
- **Express.js** - Main API server (TypeScript, port 4000)
- **Fastify** - Media API microservice (TypeScript, port 4100)
- **Prisma ORM** - Database modeling and migrations (27+ models)
- **Drizzle ORM** - Media tables (lightweight schema-first)
- **PostgreSQL 16** - Primary database
- **Redis** - Caching, sessions, rate limiting, BullMQ backend
- **BullMQ** - Job queues (email sending, geocoding)
- **Winston** - Structured logging

### Frontend
- **React 19** - UI library
- **Vite** - Build tool and dev server
- **Ant Design 5** - Component library
- **Zustand** - State management
- **React Router** - Client-side routing
- **Axios** - HTTP client with interceptors
- **Leaflet** - Interactive maps
- **GrapesJS** - WYSIWYG page builder

### Infrastructure
- **Docker Compose** - Service orchestration (20+ containers)
- **Nginx** - Reverse proxy with subdomain routing
- **Prometheus** - Metrics collection
- **Grafana** - Metrics visualization
- **Alertmanager** - Alert routing
- **Listmonk** - Newsletter platform
- **MailHog** - Email testing (development)

## Project Status

### Completed Phases (1-14)
✅ **Phase 1**: Foundation - Database, auth, basic API
✅ **Phase 2**: Auth + User Management - JWT, RBAC, user CRUD
✅ **Phase 3**: Admin GUI Foundation - React admin, routing, layouts
✅ **Phase 4**: Influence (Campaigns) - Campaign CRUD, admin pages
✅ **Phase 5**: Representatives + Postal Codes - API integration, caching
✅ **Phase 6**: Email Sending - BullMQ queue, SMTP, tracking
✅ **Phase 7**: Response Wall + Public Campaign View - Public pages, moderation
✅ **Phase 8**: Map (Locations) - Geocoding, CSV import, map rendering
✅ **Phase 9**: Map (Shifts) - Shift management, public signup
✅ **Phase 10**: Walk Sheets & QR Codes - Printable forms, QR generation
✅ **Phase 11**: Newsletter Integration - Listmonk sync
✅ **Phase 12**: Landing Page Builder - GrapesJS editor, MkDocs export
✅ **Phase 13**: Volunteer Canvassing - GPS tracking, visit recording
✅ **Phase 14**: Monitoring + DevOps - Prometheus, Grafana, backup

### Additional Features
✅ **Security Audit** - 13 findings addressed (Feb 2026)
✅ **NAR 2025 Import** - Canadian electoral data support
✅ **Media Manager** - Dual API video library
✅ **Email Templates** - Template management system
✅ **Data Quality Dashboard** - Geocoding metrics
✅ **Observability Dashboard** - Monitoring integration

### Current Phase
🚧 **Phase 15**: Testing + Polish - Comprehensive testing, documentation

## Migration from V1

If you're migrating from Changemaker Lite V1 (NocoDB-based architecture), see the [Migration Guide](migration/index.md) for:

- Breaking changes (NocoDB → Prisma, sessions → JWT)
- Data migration strategy
- API endpoint mapping
- Feature parity comparison

## Contributing

Changemaker Lite is open source. We welcome contributions! See the [Contributing Guide](contributing/index.md) for:

- Development setup
- Code standards
- Pull request process
- Roadmap (Phase 15+)

## Support

- **Documentation Issues**: [Report on GitHub](https://github.com/anthropics/claude-code/issues)
- **Security Issues**: See [Security Policy](architecture/security.md)
- **General Questions**: Check [Troubleshooting](troubleshooting/index.md) and [FAQ](troubleshooting/faq.md)

---

**Last Updated**: February 2026 | **Version**: 2.0.0 | **Status**: Production Ready