WaterAccessOptimizer is an open-source web application for uploading water-access datasets, visualizing mapped records, and running explainable risk assessments.
This release is centered on the current MVP workflow:
- authenticate or use demo mode
- upload hydrological, community, and infrastructure CSV data
- inspect communities and facilities on the map
- create and run risk assessments
- review charts, tables, and exports
- Release version:
1.0.0 - Frontend verification:
npm run lint,npm run test -- --run, andnpm run buildpass infrontend/ - Demo mode: available and useful for screenshots or walkthroughs
- Primary deployment path for this release:
docker-compose.prod.yml
- React frontend in
frontend/ - Auth service in
backend/auth-service/ - Data service currently packaged from
backend/api-gateway/ - PostgreSQL-backed backend services
- Optional AI model service in
ai-model/ - Optional Prometheus and Grafana in
docker-compose.prod.yml
This is the fastest way to review the UI without logging in.
cd frontend
npm install
npm run dev:demoOpen http://localhost:5173. Demo mode seeds an authenticated session and mock application data.
cp .env.example .env
# update secrets in .env
docker-compose -f docker-compose.prod.yml up -dPrimary URLs:
- Frontend: http://localhost
- Auth service: http://localhost:8081
- Data service: http://localhost:8087
- AI model: http://localhost:8000
- Prometheus: http://localhost:9090
- Grafana: http://localhost:3000
cd frontend
npm install
npm run devUseful scripts:
npm run devnpm run dev:demonpm run lintnpm run test -- --runnpm run build
The backend is Java/Spring-based and requires Java 17+ and Maven.
cd backend/auth-service
mvn spring-boot:run
cd ../api-gateway
mvn spring-boot:runCurrent local defaults used by the frontend:
- Auth API:
http://localhost:8081/api/v1/auth - Data API:
http://localhost:8087/api/v1
This repository still contains older modules and planning documents, but the current release surface is:
frontend -> auth-service
frontend -> data-service
auth-service -> postgres
data-service -> postgres
optional: frontend/data-service -> ai-model
Important repo note:
docker-compose.prod.ymlbuilds the release data service frombackend/api-gateway/- there is also a separate
backend/data-service/directory in the repo, but it is not the primary packaged runtime path for this release
Recent release-prep fixes included:
- accurate demo mode with seeded authenticated data
- local Leaflet marker assets instead of remote icon URLs
- safer persisted Zustand storage fallback behavior
- unique notification IDs to avoid accidental multi-removal
- tighter frontend verification surface and passing frontend tests
- documentation updated to match real ports, commands, and runtime paths
- Root release guides:
- GETTING_STARTED.md
- DEPLOYMENT.md
- docs/COMPLIANCE_READINESS.md
- docs/ARCHITECTURE_OVERVIEW.md
- docs/SERVICE_BOUNDARIES_MVP.md
Reference and historical docs in docs/ have been trimmed or marked accordingly so they do not override the release guides above.
This release is being prepared for:
- NIST-aligned secure development readiness
- GDPR-oriented privacy-by-design readiness
- Section 508 and WCAG accessibility readiness
It does not claim formal certification. The current implementation adds practical controls such as stronger secret handling, authentication safeguards, browser security headers, public privacy and accessibility pages, and improved keyboard and screen-reader support in key workflows.
- Demo mode is frontend-only and uses mock data.
- The repo contains legacy pages and service experiments that are not part of the current routed release surface.
- Kubernetes files exist, but Docker Compose is the primary documented release path for this version.
Apache-2.0. See LICENSE.