# Changemaker Lite

A self-hosted political campaign platform that consolidates advocacy email campaigns, geographic mapping, volunteer canvassing, media management, and administration into a single TypeScript stack. Built for organizers who want to own their data.

## What Is This?

Changemaker Lite gives community organizers the tools they need to:

- **Run advocacy campaigns** — let supporters look up their elected representatives by postal code and send emails in a few clicks
- **Manage canvassing** — map locations, draw canvassing areas, schedule volunteer shifts, and track door-to-door visits with GPS
- **Host media** — upload campaign videos, share them publicly, and track engagement analytics
- **Build landing pages** — drag-and-drop page builder for campaign microsites
- **Send newsletters** — integrated with Listmonk for opt-in mailing lists
- **Monitor everything** — Prometheus + Grafana observability stack included

The entire platform runs on Docker Compose with a single `.env` file for configuration.

## Quick Start

```bash
# Clone and switch to the v2 branch
git clone <repo-url> changemaker.lite
cd changemaker.lite
git checkout v2

# Create your environment file
cp .env.example .env
# Edit .env — at minimum set:
#   V2_POSTGRES_PASSWORD, REDIS_PASSWORD,
#   JWT_ACCESS_SECRET, JWT_REFRESH_SECRET, ENCRYPTION_KEY
#   INITIAL_ADMIN_EMAIL, INITIAL_ADMIN_PASSWORD

# Start core services
docker compose up -d v2-postgres redis api admin

# Run database migrations and seed
docker compose exec api npx prisma migrate deploy
docker compose exec api npx prisma db seed
```

Then open **http://localhost:3000** and log in with the admin credentials from your `.env`.

## Architecture

| Component | Technology | Port |
|-----------|-----------|------|
| **API** | Express.js + Prisma + PostgreSQL | 4000 |
| **Media API** | Fastify + Prisma (shared DB) | 4100 |
| **Admin GUI** | React + Vite + Ant Design + Zustand | 3000 |
| **Reverse Proxy** | Nginx (subdomain routing) | 80 |
| **Database** | PostgreSQL 16 | 5433 |
| **Cache / Queue** | Redis + BullMQ | 6379 |
| **Newsletter** | Listmonk | 9001 |
| **Monitoring** | Prometheus + Grafana + Alertmanager | 9090, 3001 |

See `CLAUDE.md` for comprehensive architecture documentation, module reference, and troubleshooting.

## Feature Flags

Enable optional modules in `.env`:

```bash
ENABLE_MEDIA_FEATURES=true      # Video library + gallery
LISTMONK_SYNC_ENABLED=true      # Newsletter subscriber sync
EMAIL_TEST_MODE=true             # Route emails to MailHog (dev)
```

## Production Deployment

Changemaker Lite uses [Pangolin](https://github.com/fosrl/pangolin) tunnels for production access (Cloudflare alternative). See the Tunnel page in the admin panel (`/app/tunnel`) for setup instructions.

## Documentation

- **`CLAUDE.md`** — Full project reference (architecture, modules, ports, patterns)
- **`V2_PLAN.md`** — Development roadmap (Phases 1-14 complete)
- **`SECURITY_AUDIT_2025-02-11.md`** — Security audit findings and remediations
- **`.env.example`** — All 100+ environment variables with descriptions

## Licensing

This project is licensed under the [Apache License 2.0](https://opensource.org/license/apache-2-0).

## AI Disclaimer

AI tools were used to assist in the creation of this project. All generated code has been reviewed. Users should test all functionality to ensure it meets their requirements.