GeoDistricts

An algorithmic protocol for U.S. Congressional redistricting that eliminates gerrymandering through objective, geography-based district creation.

GeoDistricts creates fair, unbiased congressional districts using an automated algorithm that relies solely on geographic and demographic data from the U.S. Census Bureau. No human intervention, no political bias - just mathematics and geography.

git clone https://github.com/Lacoda-Labs/geodistricts.git
cd geodistricts && ./scripts/quick-start.sh

Visit geodistricts.org for live demos and interactive maps.

GeoDistricts implements a hierarchical, geography-based algorithm that:

• Population Equality: Targets <1% variance between districts
• Contiguity: Maintains geographic continuity where possible
• Objectivity: Deterministic, automated process using census data only
• Two-Phase Approach: County-level grouping → Tract-level refinement

Key Features:

• Recursive geographic division (alternating latitude/longitude)
• Step-by-step visualization and debugging
• Population variance tracking
• Contiguity scoring

→ Complete Algorithm Specification

Implementing the protocol? This repo is the reference implementation of the GeoDistricts Protocol. For the protocol spec (GDIPs) and implementer guide, see → GDIP Index • Implementer Guide

Frontend: Angular 17+, TypeScript, SCSS, Interactive mapping with Leaflet
Backend: Node.js, Express, Census API integration
Data: U.S. Census Bureau TIGER/Line shapefiles, Population data via Census API
Infrastructure: Google Cloud Run, Cloud Storage, Secret Manager
CI/CD: GitHub Actions for automated testing and deployment

Project Structure:

├── frontend/         # Angular web client
├── backend/          # Node.js API server
├── doc/             # Comprehensive documentation
├── scripts/         # Setup and deployment utilities
└── data/            # Census data cache

→ Architecture Details

Prerequisites: Node.js 18+, Angular CLI, Docker (optional)

Quick Setup:

git clone https://github.com/Lacoda-Labs/geodistricts.git
cd geodistricts
./scripts/quick-start.sh  # Installs deps & starts dev servers

Manual Setup:

• Backend: cd backend && npm install && npm run dev
• Frontend: cd frontend && npm install && ng serve
• Census API: Run ./scripts/setup-api-keys.sh for direct API access

→ Detailed Setup Guide

Census Population Data: Demographic statistics from U.S. Census Bureau APIs → Census Population Data Details

TIGER/Line Shapefiles: Geographic boundaries and spatial data → TIGER/Line Shapefiles Details

State Election Data: Voter registration and party affiliation statistics → State Election Data Details

Current Status: 5/50 states configured (AZ, CA, FL, NY, TX)
Priority Need: Voter data sources for remaining 46 states

→ State Data Sources Status • Request Template

Platforms: Google Cloud Run, GitHub Pages
CI/CD: Automated testing, building, and deployment via GitHub Actions
Domains: Custom domain setup with SSL certificates

Quick Deploy:

./scripts/deploy.sh  # Full GCP deployment

→ GCP Setup Guide • Domain Setup

Priority Areas:

1. Data Collection: Find voter registration sources for remaining states
2. Algorithm Enhancement: Improve contiguity scoring, performance optimization
3. UI/UX: Better visualization, accessibility improvements
4. Testing: Unit tests, integration tests, algorithm validation

Getting Started:

1. Fork the repository
2. Create a feature branch
3. Make your changes following our contributing guidelines
4. Submit a pull request

→ Contributing Guide • Issue Templates • Protocol Changes (algorithm/data-model changes require a GDIP in the protocol repo)

License: MIT License - see LICENSE file for details

Privacy & Terms:

• Privacy Policy - Data collection and usage
• Terms of Service - Service terms and conditions