VoteCatcher ✓

Open Source Campaign Infrastructure

Automate ballot signature recognition and validation. Put powerful organizing tools in the hands of grassroots campaigns.

---

Deploy to the Cloud

Click a button to deploy VoteCatcher with a managed database. You'll need an OCR provider API key (e.g., OpenAI).

	Ephemeral dev DB — upgrade to managed Postgres for production
	Self-hosted — point at this repo's docker-compose.yml

---

Getting Started

The fastest way to run VoteCatcher is with Docker — no Python, Node, or build tools needed. All you need is Docker Desktop installed and running.

1. Download VoteCatcher — clone with git or download the ZIP from the green "Code" button on GitHub, then open a terminal in the folder

2. Run the setup script:

# macOS / Linux
./start.sh

# Windows Command Prompt
start.bat

# Windows PowerShell
.\start.ps1

That's it. The script checks Docker, creates config files, and starts the app. Once ready, open:

What	URL
VoteCatcher app	http://localhost:5173
API docs	http://localhost:8080/docs

To stop: press Ctrl+C, or run docker compose down

Need to configure OCR providers or database? See Configuration Modes.

---

Quick Start (Developers)

Prerequisites

• Python 3.12+
• uv package manager
• Bun runtime
• Docker (for containerized setup)
• just task runner (recommended)
• API key for an LLM provider (optional — simulation mode works without one)

No API key? Run in simulation mode — all features work with mock OCR. See Configuration Modes.

Option 1: Local Development

git clone https://github.com/civictechdc/votecatcher
cd votecatcher

# Install dependencies
just install

# Configure environment
cp backend/.env.example backend/.env.local
cp frontend/.env.example frontend/.env

# Run migrations
just migrate

# Start backend (http://localhost:8080)
just dev-backend

# Start frontend in another terminal (http://localhost:5173)
just dev-frontend

Option 2: Docker Compose

Starts backend, frontend, and PostgreSQL together:

git clone https://github.com/civictechdc/votecatcher
cd votecatcher

cp backend/.env.example backend/.env.local
cp frontend/.env.example frontend/.env

just dev

Option 3: Dev Container (VS Code)

1. Open the repo in VS Code
2. When prompted, click Reopen in Container
3. Wait for the container to build (~5 min first time)
4. Run the setup:

.devcontainer/setup.sh

5. Start services in separate terminals:

# Terminal 1 — Backend
cd backend && uv run python -m app --env local

# Terminal 2 — Frontend
cd frontend && bun run dev

See .devcontainer/README.md for troubleshooting.

Access Points

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:8080
Swagger UI	http://localhost:8080/docs
ReDoc	http://localhost:8080/redoc

Common Commands

All commands use just. Run just to see all recipes.

Command	Description
just install	Install all dependencies
just dev-backend	Start backend dev server
just dev-frontend	Start frontend dev server
just dev	Start all services via Docker Compose
just test	Run all tests
just lint	Run linters
just typecheck	Run type checkers
just migrate	Run database migrations
just security-scan	Run security scans
just ci-sim	Simulate full CI pipeline locally

Configuration

VoteCatcher supports multiple database and OCR configurations:

Database	Use Case	Setup
SQLite	Local development, testing	Zero config (sqlite:///./dev.db)
PostgreSQL	Production, concurrent users	just dev-postgres
Supabase	Managed PostgreSQL + Auth + Storage	Supabase Setup

For full configuration details, see Configuration Modes.

Tech Stack

Layer	Technology
Frontend	SvelteKit 5, Svelte 5, TypeScript, Tailwind CSS v4
Backend	FastAPI, Python 3.12+, SQLModel, Alembic
Database	PostgreSQL / SQLite / Supabase
Auth	Better Auth
AI/ML	OpenAI, Mistral, Gemini API integration
Package Managers	bun (frontend), uv (backend)

Documentation

Document	Description
Running Locally	Detailed local development setup
Configuration Modes	All configuration options
Architecture	C4 model diagrams and ADRs
Project Structure	Directory layout and module overview
Versioning	Release and version management
Docker Deployment	Production deployment guide
User Guide	Application usage guide
Demo Walkthrough	Demo mode walkthrough
API Spec	OpenAPI specification

Contributing

See CONTRIBUTING.md for development setup, code standards, and PR process.

License

This project is open source under the MIT License.