Humanitarian Health Platform

Open-source humanitarian health platform designed for low-connectivity environments, with three applications:

• Patient mobile app — Triage, advice, referrals, case records
• Community health worker (CHW) mobile app — Protocols, referrals, case management
• NGO dashboard (web) — Configuration, analytics, protocol/knowledge updates

Features

• Android-first mobile apps (Kotlin + Jetpack Compose)
• Offline-first architecture with SQLite and sync service
• Knowledge library and configurable clinical protocols stored locally
• Configurable language packs and localization with a personalization layer
• Agent runtime: Triage, Advice, Knowledge, Integration, Safety Guard agents
• Referral management, patient case records, protocol rule engine
• Update bundles for knowledge and protocol updates
• FHIR-compatible health data
• IntelliGraph FAQs (NGO dashboard) — semantic FAQ knowledge graph for NGO coordinators and healthcare workers only: TF–IDF-weighted hashed embeddings, similarity graph, semantic search, and optional constrained Qwen/Ollama summarization over curated evidence (POST /knowledge/intelligraph/summarize with staff JWT)

Monorepo structure

apps/           — patient-mobile, chw-mobile, ngo-dashboard, api
packages/       — core, sync, agents, protocols, knowledge, fhir, i18n, updates
tooling/        — shared ESLint, TypeScript configs
docs/           — ARCHITECTURE.md and design docs

See docs/ARCHITECTURE.md for the full architecture.

NGO dashboard — operational zones & scrape UX

• Search: type any place — geocoding uses OpenStreetMap Nominatim via GET /geocode/search on the API (Vite proxies /geocode in dev; run the API so search works).
• Scrape: builds a demo facility + vulnerability layer for the chosen anchor; MHU recommendation = weighted geometric median of vulnerability hotspots, with mean distance to static facilities as a care-gap signal.
• Animation: optional stepped UI — VITE_SCRAPE_ANIMATION=false or VITE_SCRAPE_MS_PER_STEP=0 for instant.
• Production data: VITE_ZONES_API_URL POST { anchor, scrapeSeed } → { facilities, hotspots }.

---

Prerequisites (macOS & Windows)

Tool	Version	Notes
Node.js	18+ (20 LTS recommended)	Same on both OSes — use nodejs.org or a version manager.
pnpm	9.x	Use Corepack (below) so everyone uses the same version.
Git	recent	Windows: avoid paths > 260 chars if you hit odd errors — clone to a short path like C:\dev\PocketSage.

Enable pnpm via Corepack (recommended)

Works on macOS and Windows (Node 16.13+):

corepack enable
corepack prepare pnpm@9.0.0 --activate

Then pnpm -v should report 9.x.

Windows-only tips

• Use PowerShell or Windows Terminal for the commands below (not legacy cmd unless you know the differences).
• **sqlite3** (used by the API) builds native addons. If pnpm install fails on sqlite3, install Visual Studio Build Tools (“Desktop development with C++”) or use Windows 11 + current Node and retry.
• OneDrive / cloud-synced folders can lock files and break node_modules or SQLite. Prefer a local folder (e.g. C:\dev\... or ~/Projects/...).

macOS-only tips

• Xcode Command Line Tools help if any native module fails: xcode-select --install.
• Apple Silicon (M1/M2/M3): use the arm64 Node installer; pnpm installs are the same as on Intel.

---

Quick start — web dashboard + API

The dashboard (Vite, port 3000) proxies API routes to the backend (Express, default 4000). For full features (auth, geocode, cases), run both.

1. Install dependencies (repo root)

pnpm install

2. Environment files

Copy examples and adjust if needed:

# macOS / Linux / Git Bash on Windows
cp apps/api/.env.example apps/api/.env
cp apps/ngo-dashboard/.env.example apps/ngo-dashboard/.env

Windows (PowerShell) — same idea:

Copy-Item apps\api\.env.example apps\api\.env
Copy-Item apps\ngo-dashboard\.env.example apps\ngo-dashboard\.env

• **apps/api/.env** — at minimum PORT=4000 (default). See apps/api/.env.example for CORS and proxy notes.
• **apps/ngo-dashboard/.env** — usually empty for local dev; the Vite dev server proxies to http://127.0.0.1:4000. If your API uses another port, set VITE_API_PROXY_TARGET there.

3. Run two processes

Terminal A — API

pnpm api:dev

Terminal B — NGO dashboard

pnpm dashboard:dev

Then open http://localhost:3000 in your browser.

Service	URL	Script
Dashboard	http://localhost:3000	pnpm dashboard:dev
API	http://127.0.0.1:4000 (proxied from dashboard)	pnpm api:dev

4. Useful root scripts

pnpm dev              # alias → dashboard:dev (UI only)
pnpm dashboard:dev    # NGO dashboard (Vite)
pnpm dashboard:build  # production build of dashboard
pnpm api:dev          # API with hot reload
pnpm build            # build all workspaces that define `build`
pnpm lint             # lint all packages
pnpm test             # test all packages
pnpm test:dashboard   # dashboard tests only

---

Production / preview build (dashboard)

pnpm dashboard:build
pnpm --filter ngo-dashboard preview   # serves dist/ locally

Point VITE_API_URL at your deployed API when not using the dev proxy (see apps/ngo-dashboard/.env.example).

---

Mobile apps

Open apps/patient-mobile or apps/chw-mobile in Android Studio and run on a device or emulator.

• JDK 17+ and Android Studio are required (same on Mac and Windows).

---

Troubleshooting

Issue	What to try
Geocode / search fails in Zones	Ensure API is running (pnpm api:dev) and PORT matches VITE_API_PROXY_TARGET (default 4000).
**EADDRINUSE on 4000**	Another app uses the port — change PORT in apps/api/.env and set VITE_API_PROXY_TARGET in the dashboard .env.
**pnpm not found**	Run corepack enable then corepack prepare pnpm@9.0.0 --activate.
SQLite / native module errors on install	Windows: install VS Build Tools (C++). macOS: xcode-select --install.
CORS or “Failed to fetch”	Use the Vite dev server (pnpm dashboard:dev) so /auth, /geocode, etc. are proxied; avoid opening only file:// or a static server without proxy unless VITE_API_URL is set.
Strange file locks / install errors	Move the repo out of OneDrive/iCloud/Dropbox-synced folders.

---

License

TBD (intended open-source)