CivicLens
Public-sector data analytics engine — from messy public files to decisions you can defend.
Web app + public REST API that runs the full analytics lifecycle on government data: ingest → profile → guided cleaning → SQL modeling → machine learning → executive dashboard and report. UI in English and Spanish; input data in English, French or Spanish.
🚧 Status: Phase 0 — scaffold. See docs/ROADMAP.md for the 25-day plan.
Why
Public data arrives fragmented, multilingual and dirty, and executive reporting is often manual. CivicLens shows — step by step — how to turn it into reliable KPIs and decision support, and lets agencies repeat the same pipeline every month through an API.
Stack
| Layer | Choice |
|---|
| Web | Next.js 14 · TypeScript · Tailwind · next-intl (EN/ES) · Vercel |
| API | FastAPI · Python 3.11 · Docker · Render |
| Analytics | DuckDB + Parquet · pandas |
| App data | PostgreSQL (Neon) |
| ML | scikit-learn · statsmodels · SHAP |
| CI/CD | GitHub Actions |
Run locally
cp .env.example .env
docker compose up --build
# web → http://localhost:3000 (redirects to /en or /es)
# api → http://localhost:8000/health docs → http://localhost:8000/docs
Without Docker:
# API
cd apps/api && python -m venv .venv && . .venv/bin/activate && pip install -e ".[dev]"
uvicorn app.main:app --reload
# Web
cd apps/web && npm install && npm run dev
Repository layout
apps/web Next.js app (UI, i18n catalogs in messages/en.json and messages/es.json)
apps/api FastAPI service (analytics engine + public API)
data/seed Frozen public datasets + dataset cards
docs/ Spec, roadmap, ADRs, glossary
scripts/ Tooling (i18n catalog check, seed loading)
Quality gates (CI)
Ruff + pytest with coverage (API) · ESLint + typecheck + build (web) · EN/ES catalog parity · gitleaks secret scan · Docker build.
Resumen en español
CivicLens es un motor de analítica para datos públicos: carga archivos en inglés, francés o español, enseña a limpiarlos, los modela en SQL, aplica modelos de machine learning explicables y genera el reporte ejecutivo. La interfaz está disponible en inglés y español, y todo el proceso se puede automatizar mediante una API para entidades públicas.
Author
María Alejandra Boada Rodríguez — Data Analyst · Software Engineer
License
MIT. Dataset licenses and attribution are listed in data/seed/README.md.
