Offline-First-Maternal-Health-Referral-Assistant

Offline-First Maternal Health Referral Assistant (HT-02 MVP)

A lightweight web app that helps a community health worker (CHW) record a maternal health visit, see rule-based warning flags with reasons, and produce a printable referral summary. It keeps working with no internet and can be installed on an Android phone as a PWA.

Live demo: add your GitHub Pages link here (see “Deploy” below)

Demo only. Uses fictional data. The warning rules are placeholders and are not clinical guidance until verified (see “Limitations”).

OpenHack’26 submission details

Features

Tech

HTML, CSS and JavaScript frontend with a small FastAPI backend for the optional online chat.

.
├── main.py
├── requirements.txt
├── .env.example
├── model/
│   ├── README.md
│   └── assistant_instructions.txt
└── src/
    ├── index.html
    ├── app.js
    ├── i18n.js
    ├── rules.js
    └── style.css
File Purpose
main.py FastAPI server and server-side Groq proxy
requirements.txt Python runtime dependencies
src/ Browser app, local rules, translations, facilities and PWA assets
model/ Online assistant safety instructions; no model weights are downloaded

Run locally

Create a virtual environment and install the pinned-range dependencies:

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe main.py

The app opens at http://localhost:8000. The service worker only registers on https:// or localhost; load the app once while connected so its shell is available offline. The first load cannot happen offline unless the project files are already on the device.

To enable online chat, revoke any key previously pasted into a chat or committed anywhere, create a new Groq key, and store it only in a local .env file:

if (!(Test-Path .env)) { Copy-Item .env.example .env }
notepad .env
# In Notepad set GROQ_API_KEY=your-new-key, save the file, then close the running server.
.\.venv\Scripts\python.exe main.py

Install updated dependencies with .\.venv\Scripts\python.exe -m pip install -r requirements.txt if this is an existing setup. The server reads .env at startup; restart it after changing the key. .env is ignored by Git. Never paste keys into source code, browser files, screenshots, or chat. Optional GROQ_MODEL, HOST and PORT environment variables select the model and bind address. If no key is configured, Online AI mode explains that chat is unavailable; Offline guidance still works without calling the model.

The default Groq model is llama-3.3-70b-versatile (production Llama 3.3 70B). The server status and chat page show the active model. If Groq rejects the key, model, or account quota, the chat displays a specific next step instead of a generic failure.

Deploy (GitHub Pages) and install on Android

Deploy main.py to a host that supports Python/FastAPI and HTTPS, with GROQ_API_KEY set as a server-side secret. GitHub Pages can host the static/offline app but cannot run this API; deploy the FastAPI app for the combined Online AI and Offline guidance modes. On Android, open the HTTPS app URL in Chrome and load it once while connected, then use Install app / Add to Home screen. It will keep local guidance available offline.

Design decisions

Limitations (honest scope)

Challenges we faced

AI and open-source disclosure

Roadmap

Authenticated visit sync, professional review, native-speaker/clinical review of all translations, and optional local AI for installations that need chat without internet. The current Groq chat needs internet; local deterministic guidance remains the offline fallback. Add deployment-level authentication and per-user quotas before exposing the chat server publicly.