TerraPulse — Climate Intelligence Dashboard

Starter scaffold for TerraPulse: Flask backend + React frontend, Postgres, Redis, Docker Compose.

Quick start (requires Docker):

1. Copy .env.example to .env and set values.
2. From project root run:

# TerraPulse — Climate Intelligence Dashboard

Flask backend · React frontend · PostGIS · Redis · OpenAI (optional)

License: MIT

Overview
--------
TerraPulse is a starter climate intelligence dashboard that ingests sensor and satellite observations, stores region geometries in PostGIS, simulates policy impacts using OpenAI (optional), and provides a real-time alerts stream via Server-Sent Events (SSE). It ships as a containerized full-stack app (Docker Compose) and includes a lightweight React + Leaflet frontend.

Demo
----
A small static demo map is included in `frontend/public/demo-map.svg` to illustrate the UI. For a live demo, run the stack locally and open the frontend at http://localhost:3000.

Quick start (Docker)
--------------------
1. Copy `.env.example` to `.env` and set values (use `OPENAI_MOCK=1` for local dev).
2. From project root:

```powershell
copy .env.example .env
docker-compose up --build -d

3. Run migrations and seed a sample region (inside backend container):

docker-compose run --rm backend alembic upgrade head
docker-compose run --rm backend python manage.py seed_region

4. Visit the frontend: http://localhost:3000 and the API at http://localhost:5000

Core features

• Ingest API: POST /ingest stores sensor payloads per-region (DB-backed or Redis list fallback).
• Regions API: GET /regions/<region> returns recent ingest items; GET /regions/<region>/geojson returns region geometry as GeoJSON.
• Policy simulator: POST /simulate-policy — optional OpenAI integration with robust fallback and mock mode.
• Alerts: POST /alerts, GET /alerts, and GET /stream/alerts (SSE realtime alerts).
• PostGIS migrations and seeded sample region for polygon rendering.

How it works

1. Ingest
   • Clients POST region data to /ingest. When a database is configured, data is persisted to regions_ingest. Otherwise it is stored in a Redis/in-memory list.
2. Regions & GeoJSON
   • Region geometries live in the regions PostGIS table. The backend exposes GeoJSON via ST_AsGeoJSON or a demo polygon fallback.
3. Simulator
   • The simulator calls OpenAI when OPENAI_API_KEY is present, with retries/timeouts and a mock mode (OPENAI_MOCK=1) for offline use.
4. Alerts & Streaming
   • Alerts are pushed to a Redis list and optionally published to a channel. Clients can subscribe to /stream/alerts to receive SSE events (backlog is sent on connect).

Project structure

docker-compose.yml           # compose services: backend, frontend, db (PostGIS), redis
init_db.sql                  # optional DB init SQL
README.md                    # project README (this file)

backend/                     # Flask backend
	Dockerfile                 # backend image build
	requirements.txt           # Python dependencies
	manage.py                  # small CLI for migrations/seeding
	alembic/                   # alembic migrations and config
	backend/                   # backend app package
		app.py                   # main Flask app and routes
		db.py                    # SQLAlchemy models and DB helpers
		tests/                   # pytest unit tests for backend

frontend/                    # React + Vite frontend
	Dockerfile                 # frontend image build
	package.json               # npm scripts and dependencies
	public/                    # static public assets
		demo-map.svg             # demo map example
	src/                       # React source
		App.jsx                  # main app shell (simulator + map)
		MapView.jsx              # Leaflet map view and GeoJSON rendering
		__tests__/               # frontend unit tests (Jest)

scripts/                     # helper scripts
	verify_end_to_end.py       # small verifier that exercises API + SSE

.github/                     # CI workflows
	workflows/
		ci.yml                   # GitHub Actions: tests, build, e2e, publish

Testing

• Backend unit tests: run in backend/ with pytest.
• Frontend tests: run in frontend/ with npm test (Jest) — a simple MapView test is included.

CI pipeline

A GitHub Actions workflow runs backend tests, builds the frontend, runs an end-to-end verifier that uses docker-compose, and (optionally) builds and publishes Docker images when registry secrets are configured.

Publishing images

To enable CI to publish Docker images, set these repository secrets in GitHub:

• REGISTRY_URL, REGISTRY_USERNAME, REGISTRY_PASSWORD, BACKEND_IMAGE, FRONTEND_IMAGE

Troubleshooting

• If frontend builds fail due to native node_modules, ensure host node_modules is not mounted; the frontend Dockerfile runs npm ci in-image and the repo includes .dockerignore.
• If Alembic migrations fail in CI, check the Postgres health logs and increase wait times.

Contributing

Open a PR with changes against main. Follow the code style and add tests where appropriate.

License

MIT

Want me to also:

• Create a LICENSE file with MIT text and commit it
• Create a feature branch and prepare a PR for these README changes
• Replace the demo SVG with a screenshot you provide (or give commands to capture one)

Which of those should I do next?

# terrapulse