ClimateReady

ClimateReady is a mobile-first climate resilience companion. The Expo and React Native app equips households and communities with personalised preparedness guidance, SOS coordination, and practical learning tools. The project also contains a Node/Express backend for community content and a Vite web dashboard that lets emergency contacts follow live SOS sessions.

---

Highlights

• Preparedness hub with weather-aware alerts, household checklists, and education modules that work offline-first.
• SOS activation pipeline that shares live GPS tracks, manages emergency contacts, and records follow-up history.
• Safe zone discovery powered by Google Places and curated Firestore data, rendered on interactive native maps.
• Community collaboration via moderated discussion boards, live chat, and notification feeds backed by MongoDB.
• Training simulations including mini games for floods, hurricanes, medical emergencies, and more.

Architecture at a Glance

• Mobile app (app/) – Expo SDK 54, React Native 0.81, Expo Router navigation, TypeScript throughout.
• Backend server (server/) – Express + MongoDB Atlas servicing community posts, moderation, and sockets.
• SOS tracker (sos-live-tracker-map/) – Vite + React web client consuming Firestore for real-time maps. The source lives in a companion repository at R-Tharanka/sos-live-tracker-map and is vendored here for local development.
• Shared libraries – Firebase Auth + Firestore, Socket.io, Expo Notifications, Google Maps/Places SDKs.

Tech Stack

• Expo SDK 54, React Native 0.81, Expo Router, Reanimated, Expo Location & Task Manager.
• TypeScript + ESLint with Expo config; Gradle-managed Android project for custom permissions and build variants.
• Firebase Authentication, Firestore, Cloud Messaging, Functions (via REST helpers).
• Express, Socket.io, Mongoose, and Hugging Face moderation on the server.
• Vite, React Router, Firebase Web SDK, Google Maps JavaScript API for the SOS tracker.

Repository Layout

• app/ – mobile screens, tab stacks, and feature flows (SOS, community, toolkit, safe zones).
• components/ – reusable UI (notifications bell, toolkit cards, game UIs).
• context/ – providers for authentication, localisation, SOS state.
• features/ – domain-specific modules such as safe-zones/ with maps, hooks, and services.
• utils/ & services/ – cross-cutting helpers (push registration, Firestore access, weather thresholds, API client).
• android/ – Gradle project generated by Expo prebuild and customised for location/background permissions.
• server/ – Express API, socket gateway, moderation services, Mongoose models, and .env driven config.
• sos-live-tracker-map/ – web dashboard codebase with its own build tooling and Firebase setup.
• docs/ – developer documentation including command-reference.md.

Prerequisites

• Node.js 18 LTS or newer and npm (ships with Node).
• JDK 17 with JAVA_HOME configured (Gradle builds).
• Android Studio with SDK 36, NDK 27.1.12297006, an emulator or USB-debuggable Android device.
• MongoDB Atlas connection string (see server/.env) for backend services.
• Optional: Expo Dev Client, EAS CLI, Vercel CLI.

Setup

git clone https://github.com/R-Tharanka/ClimateReady.git
cd ClimateReady
npm install

Environment Variables

Create a root .env for Expo/React Native variables consumed by app.config.js and runtime helpers:

EXPO_PUBLIC_PROJECT_ID=<eas-project-id>
EXPO_PUBLIC_API_BASE=<mobile-api-base-url>
OPENWEATHER_API_KEY=<openweather-key>
SOS_WEB_APP_URL=<https://your-sos-tracker.example>
GEMINI_API_KEY=<optional-google-gemini-key>

Server-specific variables live in server/.env (example file committed):

PORT=4000
MONGODB_URI=<mongodb-atlas-connection-string>
CLIENT_ORIGIN=http://localhost:8081
HUGGINGFACE_API_KEY=<optional-hf-token>
HF_MODERATION_MODEL=unitary/toxic-bert

The SOS tracker web app reads from sos-live-tracker-map/.env (see .env.example for the full list) covering Firebase web credentials and Google Maps API keys.

ℹ️ When experimenting locally, export EXPO_PUBLIC_PROJECT_ID in your PowerShell session ($env:EXPO_PUBLIC_PROJECT_ID = "...") before running native builds so push registration succeeds.

Running the Mobile App

1. Build/install the development client (first run or after native changes):

   npx expo run:android --variant development

2. Launch Metro in dev-client mode and scan the QR code in Expo Go or use USB debugging:

   npx expo start --dev-client

3. Review additional maintenance commands (ADB, Gradle clean, logcat filters) in docs/command-reference.md.
4. Lint the project before committing:

   npm run lint

Key Mobile Modules

• SOS Flow: app/tabs/sos.tsx, utils/sos/ services, Expo background location tasks for continual tracking.
• Safe Zones: features/safe-zones/ for Google Places fetchers, Firestore fallbacks, and map rendering.
• Community: app/community/, services/api.ts, socket listeners, and push notification hooks.
• Toolkit & Games: components/game/ and app/toolKit/ provide educational simulations and progress tracking.

Running the Backend Server

cd server
npm install
npm run dev

• Serves REST endpoints for posts, comments, notifications (/api/posts, /api/community-notifications).
• Maintains a Socket.io gateway (/socket.io) for real-time chat and SOS broadcasts.
• Applies rule-based and Hugging Face powered moderation prior to persisting community content.
• Uses the service account JSON in server/climateready-40665-firebase-adminsdk-*.json for Firebase Admin operations.

Running the SOS Tracker Web App

cd sos-live-tracker-map
npm install
npm run dev

• Consumes Firestore documents keyed by SOS session IDs with token validation (src/utils/TokenValidator).
• Provides debugging tools (TokenDebugHelper, SosDebugDashboard) to verify emergency access links.
• Built with Vite; production builds (npm run build) output to sos-live-tracker-map/dist and deploy cleanly to Vercel (see vercel.json).
• Source of truth: https://github.com/R-Tharanka/sos-live-tracker-map. Keep this submodule clone in sync with upstream for the latest fixes.

Testing & Quality

• npm run lint – ESLint with Expo configuration for TypeScript.
• Manual QA: run adb logcat -s ReactNativeJS ReactNative Expo AndroidRuntime to watch native crashes, and use npm run dev within server/ while exercising community flows.
• There are no automated unit tests yet; contributions adding Jest or Detox coverage are welcome.

Deployment Notes

• Mobile builds: Use EAS Build or local Gradle (npx expo run:android --variant release) after updating environment variables and Firebase config files (google-services.json).
• Backend: Deploy the Express server to a Node-friendly host (Render, Railway, Fly.io). Ensure environment variables and Firebase service account secrets are provided.
• SOS tracker: Deploy the Vite build to Vercel (default config supplied) or any static hosting with HTTPS and correct Firebase/Maps domains allowed.

Contributing

1. Fork & clone the repo; create a feature branch from main or the active working branch.
2. Follow the setup steps above and keep documentation/screenshots in sync with UI changes.
3. Run npm run lint for the mobile app and npm run lint (if added) for subprojects before opening a PR.
4. Describe testing steps and include any necessary .env.example updates when submitting changes.

License

ClimateReady is released under the MIT License.