How kamrul28890/indot-solar-suitability-map-2 works
1. Repository purpose
- This repo builds the INDOT Solar Suitability Map for SPR 4862 / Indiana Solar Roadmap.
- The active product is website/: a static, browser-delivered React + Vite application with a maintainer-facing Map Builder.
2. Primary runtime boundary
- The public site is static at runtime; it does not depend on a live application server for normal use.
- It reads website/data/processed/manifest.json plus the referenced GeoJSON files from the deployed site assets.
3. Core public application
- The user-facing app lives under website/src/ and is organized by route:
- Home, Map, Insights, Criteria, Data, Faq, About, Contact, and legal pages.
- website/src/components/ contains shared UI shells, headers, cards, charts, map controls, and layout primitives.
4. Map subsystem
- The map experience is centered in website/src/map/ and backed by Leaflet-style map components and styling.
- It includes filtering, legends, detail panels, score bars, and criterion tables, indicating a data-rich GIS-style interaction model.
- Map behavior is driven by shared utilities such as filtering, selection, search, stats, and distance calculations.
5. Data-loading and app-state flow
- website/src/utils/useAppData.js is the main bridge from deployed data files into the React app.
- The flow is: processed manifest → referenced GeoJSON layers → UI routes/components.
- This keeps the site decoupled from backend services and makes the deployed bundle portable.
6. Insights and analytics layer
- website/src/components/charts/ and website/src/routes/Insights/ implement the reporting/analysis side of the site.
- These views consume the same processed datasets to render summary metrics, distributions, and comparison visuals alongside the map.
7. Browser-based Map Builder
- The builder lives in website/src/builder/ and is a separate workflow within the same app.
- Its step flow is Upload → Edit → Preview, and it accepts the three INDOT shapefile datasets for maintainer updates.
- Builder logic includes shapefile parsing, geometry repair, normalization, validation, package creation, and schema rules.
8. Data update package model
- The builder exports a drop-in ZIP update package containing:
- data/processed/manifest.json
- all_candidate_sites.geojson
- facility_scored.geojson
- row_scored.geojson
- This package is meant to be applied to a local checkout or release artifact, then rebuilt for publication.
9. Processing and validation utilities
- website/src/builder/lib/ contains the critical data pipeline pieces for converting source shapefiles into publishable map assets.
- Tests alongside these modules show the repo treats data transformation correctness as a first-class concern.
10. Build, release, and deployment
- The site is built with Vite and published from website/dist/.
- GitHub Actions in .github/workflows/ deploy the public site, with deploy-public-site.yml targeting the public website repository using a deploy token.
- The static build is parameterized by environment variables such as VITE_DATA_MODE and VITE_PUBLIC_BASE.
11. Platform and packaging support
- There are helper scripts for release prep, Windows packaging, and verification under website/scripts/ and website/packaging/.
- A Dockerfile and docker-compose.yml exist, but the core architecture remains static-site-first rather than containerized backend service-first.
12. Testing and quality boundaries
- The repo includes unit tests for builder logic, map utilities, chart/data helpers, and API/export helpers.
- This separates concerns into:
- data transformation correctness,
- map/UI behavior,
- export/package generation,
- and deployment readiness checks.
13. Legacy/archive boundary
- archive/ contains retired prototypes, previous editor implementations, and reference material.
- These folders are not part of the active architecture, but they show earlier iterations that split frontend/backend more explicitly than the current static site.
14. Operational summary for a diagram
- The clearest architecture diagram is:
- Source shapefiles / processed GeoJSON assets feeding
- static React/Vite site with two major user paths:
- public map/insights browsing,
- maintainer Map Builder export flow.
- Publishing is a separate CI/CD path that packages the built static site to GitHub Pages/public hosting.
Main entry points: lib Builder core · App.jsx Site shell · routes Public pages · map Map experience
Components 17
Active website
Primary static React/Vite application and its data flow.
- Processed data · Deployed manifest and referenced GeoJSON layers consumed by the public site.
website/data/processed/manifest.json - Data hook · Main bridge from deployed assets into the React app.
website/src/utils/useAppData.js - Site shell · Top-level React entry and shared layout for the public site.
website/src/App.jsx - Public pages · Home, map, insights, criteria, data, FAQ, about, contact, and legal pages.
website/src/routes - Shared UI · Reusable headers, cards, layout primitives, and site chrome.
website/src/components - Map experience · Interactive map, filters, legends, detail panels, and score presentation.
website/src/map - Insights views · Charts and summary pages for distributions, comparisons, and reporting.
website/src/routes/Insights - Charts · Reusable chart primitives used by insights and summary screens.
website/src/components/charts - Map state · Filtering, selection, search, statistics, and distance helpers for map interactions.
website/src/utils
Map Builder
Maintainer workflow for importing shapefiles and exporting update packages.
- Builder flow · Upload, edit, and preview flow for updating site data.
website/src/builder/steps - Builder core · Parsing, geometry repair, normalization, validation, and package creation.
website/src/builder/lib - Schema rules · Rules and shape expectations used by the builder validation layer.
website/src/builder/config/schema.js - Update ZIP · Drop-in package containing refreshed manifest and processed GeoJSON assets.
website/src/builder/lib/buildPackage.js
Build & deploy
Static build, release packaging, and GitHub Actions deployment.
- Build pipeline · Static site build, release preparation, and packaging scripts.
website/vite.config.js - Deploy actions · GitHub Actions workflows that publish the public site.
.github/workflows/deploy-public-site.yml - Public hosting · Built site output and public pages deployment target.
website/public_site
Archive
Retired prototypes and legacy editor implementations.
- Legacy editor · Older backend/frontend editor implementations kept for reference.
archive/phase2_editor
Connections 16
- Processed data → Data hook: loads · The hook reads the deployed manifest and layer assets.
- Data hook → Site shell: feeds · Loaded data becomes application state for the site shell.
- Site shell → Public pages: renders · Top-level navigation and routing mount the public pages.
- Site shell → Shared UI: composes · Shared chrome and layout primitives are reused across pages.
- Public pages → Map experience: hosts · The map route is the central public browsing experience.
- Public pages → Insights views: hosts · Insights pages present analysis built from the same data set.
- Insights views → Charts: uses · Insights screens rely on reusable chart components.
- Map experience → Map state: depends on · Interactive map behavior is driven by shared state and utility functions.
- Map experience → Shared UI: uses · Map screens reuse site-level UI primitives and panels.
- Builder flow → Builder core: drives · The maintainer workflow is powered by the builder pipeline.
- Builder core → Schema rules: validates against · Normalization and export are constrained by schema rules.
- Builder core → Update ZIP: creates · The pipeline assembles the drop-in ZIP update package.
- Update ZIP → Processed data: replaces · Exported package updates the processed data assets consumed by the site.
- Build pipeline → Public hosting: produces · Vite and release scripts generate the deployable static site.
- Deploy actions → Public hosting: publishes · GitHub Actions deploy the built site to the public hosting target.
- Legacy editor → Builder core: precedes · Archived editor implementations show the earlier more serverful workflow.