Skip to content

Next Steps

Current State (2026-01-03)

What's Working

  • FastAPI server (port 32406) with comprehensive OpenAPI documentation
  • FastHTML map visualization (port 32405)
  • DuckDB with spatial extension (441 congressional districts)
  • Redis caching with ~200x speedup on cached requests
  • Wikipedia endpoint with file-based 48hr cache
  • Geographic layers system (counties, state legislative districts)
  • Radio station coverage data with FCC contours
  • Systemd services for production deployment

Recent Completions

  • API Documentation Overhaul (2026-01-03): Full OpenAPI/Swagger documentation with:
  • Rich markdown descriptions for all endpoints
  • Operation IDs for SDK generation
  • Response examples and error schemas
  • Code samples (Python, JavaScript, cURL)
  • Field-level documentation with examples

Priority Queue

P0 - Critical

1. Wikipedia Cache Pre-Warm Endpoint

GitHub Issue: #1

Add bulk pre-warm endpoint for Wikipedia data to avoid cold-cache latency.

POST /api/v1/admin/cache/warm-wikipedia
POST /api/v1/admin/cache/warm-wikipedia?state_fips=06

Requirements: - Background execution (return 202 Accepted) - Concurrency control (3-5 parallel requests) - Progress tracking endpoint - Rate limiting for Wikipedia API - Admin authentication

Impact: Eliminates 5-7 sec latency on cache misses

P1 - High Priority

2. Pre-built Asset Bundles

Generate static gzipped bundles served via nginx for instant client loads.

Files to create: - scripts/build_release.py - data/releases/v1.0.0/manifest.json

Impact: Instant load after first client download

3. Background Cache Warmer

Scheduled job to keep Wikipedia cache warm automatically.

Files to create: - api/jobs/cache_warmer.py - systemd/cbdistricts-cache-warmer.timer

Approach: Run nightly to refresh expiring Wikipedia entries

P2 - Medium Priority

4. Expand Test Coverage

Currently only Wikipedia service has tests.

Targets: - District service unit tests - Demographics service tests - API integration tests - Cache decorator tests

5. CI/CD Pipeline

No automated testing on push.

Requirements: - GitHub Actions workflow - Run tests on PR - Lint with ruff - Type check with mypy

6. Admin Authentication

Secure admin endpoints (cache management, data refresh).

Options: - API key in header - Integrate with PIN Gate auth - IP whitelist for localhost only

P3 - Low Priority / Backlog

7. Wikipedia Regex Improvements

Rep/party extraction could be more robust.

8. Isolated Virtualenv

Currently using shared nominates env.

9. Add mypy Type Checking

Config exists but not enforced in CI.

Future Data Classes

The layer architecture supports additional polygon types:

Data Class Source Status
Congressional Districts (119th) Census TIGER ✅ Complete
Michigan Counties Census TIGER ✅ Complete
Michigan State House Census TIGER ✅ Complete
Michigan State Senate Census TIGER ✅ Complete
Radio Coverage Contours FCC ✅ Complete
State Legislative (Other States) Census TIGER 🔜 Planned
County Boundaries (All States) Census TIGER 🔜 Planned
Municipal Boundaries Census TIGER 📋 Backlog

Each class follows the same pattern: - Polygons (GeoJSON/GeoParquet in DuckDB) - Associated metadata - Redis cache + optional pre-built bundles

Documentation Status

Document Status
API /docs ✅ Complete (enhanced 2026-01-03)
README.md ✅ Complete
CLAUDE.md ✅ Complete
MAP-DATA-INGEST.md ✅ Complete
LAYER-ONBOARDING-GUIDE.md ✅ Complete
PERFORMANCE-ARCHITECTURE.md ✅ Complete
systemd-deployment.md ✅ Complete

Quick Commands

# Check service status
sudo systemctl status cbdistricts-api cbdistricts-web

# View logs
sudo journalctl -u cbdistricts-api -f

# Restart services
sudo systemctl restart cbdistricts-api cbdistricts-web

# Check cache status
curl http://localhost:32406/api/v1/cache
curl http://localhost:32406/api/v1/cache/stats

# Test API endpoints
curl http://localhost:32406/api/v1/health
curl http://localhost:32406/api/v1/districts/1903
curl http://localhost:32406/api/v1/districts/1903/wiki

# View API documentation
open https://districts.nominate.ai/docs

Last updated: 2026-01-03 (API documentation overhaul completed)