How satcherinstitute/health-equity-tracker works
Project type and purpose
• This is a full-stack, data-centric web application built around a microservice pipeline. Its goal is to ingest, process, store, and expose health equity data by demographic groups and geographies, then render interactive visualizations in a React frontend.
File structure
• Top-level services:
• frontend – React/Vite application
• frontend_server – Node.js server that hosts the built React app and proxies API calls
• data_server – Python microservice serving exported JSON data files
• exporter – Python microservice that reads from BigQuery and writes JSON files to Cloud Storage
• run_gcs_to_bq – Python microservice ingesting/caching raw source data to GCS and loading it into BigQuery
• run_ingestion – older Python microservice for legacy datasources
• Shared code and pipeline orchestration:
• python/ – ingestion modules and datasources
• config/ – Terraform scripts provisioning GCP resources (Cloud Run, Pub/Sub, buckets, BigQuery)
• .github/workflows/ – GitHub Actions DAGs that trigger ingestion/load/export pipelines
• Data assets:
• data/ – manually managed “landing” data files
• e2e_tests/, frontend/playwright-tests – end-to-end test suites
• exporter, data_server, run_* have Dockerfiles and requirements specifying microservice dependencies.
README for insights
• The README outlines a 4-layer architecture:
1) Data ingestion (run_ingestion & run_gcs_to_bq) → BigQuery
2) Exporter → JSON in GCS buckets
3) Data API (data_server) → serves those JSON files
4) Frontend (frontend + frontend_server) → React UI
• It highlights Terraform for infra provisioning, GitHub Actions for CI/CD, and Netlify for PR previews.
Essential architectural elements
• How code changes trigger CI/CD and infra updates
• Data transform and storage boundaries (GCS, BigQuery)
• Clearly demarcate frontend vs backend, and data plane vs control plane.