264 lines
9.5 KiB
Markdown
264 lines
9.5 KiB
Markdown
# 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
|