"A True Offline-First, On-Device AI Disaster Survival Application"

Live: https://flood-ready.vercel.app

Flood Ready is a hyper-localized, offline-first emergency response PWA built for the Yala region (Thailand). It combines Cognitive Engineering, True On-Device AI (Qwen2.5 1.5B via WebLLM/WebGPU), the GAIA-119 intent-based AI persona, and QR-P2P device-to-device communication to maximize survival rates when cell towers, power, and internet all fail simultaneously.

Flood Ready home screen showing live flood risk, forecast windows, immediate actions, and direct access to GAIA-119.

The live demo shows the core survival flow: risk-aware home dashboard, AI assistance, Quick Assist, map, and offline QR communication.

Every button, color, and interaction is engineered to save lives under extreme cognitive load. The guiding axiom: on-board AI only — no cloud dependency, no remote inference fallback. The entire intelligence stack runs on the user's device.

An intent-based AI persona built on CR-EP and AESE-CrisisShield + ResponseFusion frameworks. Delivers survival-critical instructions in English, Thai, and Malay — auto-detected from raw user input. Streams token-by-token via WebGPU (first token ~2s). Every response is structured JSON: { level, actions[], treeId?, searchQuery }.

SITUATION OVERRIDE: User's explicit emergency signals always override passive sensor/weather context. "Water entering house" → RED, regardless of [WEATHER: Rain 0mm].

treeId Validation: AI-suggested decision tree routes are validated client-side against decisionTreeData.nodes before the CTA button renders — prevents hallucinated dead-ends.

Downloads Qwen3-1.7B-q4f16_1-MLC (~1.1GB) into the browser's IndexedDB via WebGPU. Primary inference runs 100% offline via WebLLM with real-time streaming. Fallback chain: WebLLM → Ollama (dev-optional) → Offline keyword dictionary. Note: WebGPU required — desktop Chrome/Edge recommended. iOS devices fallback to offline dictionary automatically.

A single Open-Meteo API request supplies both current conditions and a 72-entry hourly precipitation array. ThemeContext computes forecastRisk and forecastMaxRain for three windows (12h / 24h / 72h) using WMO + Thai Met Dept peak precipitation thresholds:

Home screen tabs (Now, Next 12h, Next 24h, Next 72h) display real forecast risk sourced live from ThemeContext — no hardcoded values. The Live Alert Ticker shows: "FORECAST NEXT 24H: Yala — Peak rain: 0.1mm/h · No significant rain · GREEN RISK".

True device-to-device data transfer with zero infrastructure — no internet, no Bluetooth, no server. This is not a background mesh daemon. It is a deliberate line-of-sight emergency relay system: one device shows a QR code, another device scans it, then optionally re-broadcasts it onward.

The system is built for the exact failure mode where towers are down, power is unstable, and strangers may still be physically near each other. In that environment, the most reliable transport is often simply screen to camera.

Three payload types:

• SOS Beacon: Encodes situation text + GPS coordinates + household/medical profile into a QR code. Show the screen to anyone with a camera.
• Hub Status: Encodes a registered safe hub (name, coordinates, status, services). Anyone who scans it adds the hub to their local map instantly.
• Relay Chain: After scanning a received QR, one tap re-wraps it as a relay payload (hop+1). Creates a "telephone chain" that propagates data across completely offline phones. Capped at 5 hops.

How it behaves in practice:

• SOS is compact and fast: short message, optional GPS, household tag, medical-needs flag.
• Hub QR is operational data: name, coordinates, status, services, hub type.
• Relay preserves origin: the original SOS or hub payload is kept inside the relay wrapper, with hop count added.
• Age matters: SOS and relay payloads are treated as stale after 2 hours; hub payloads after 6 hours.
• Import is local-first: scanned hub data is written directly into the receiver's local hub map, even if they have no network.
• No extra scanner library: scanning uses the native Web BarcodeDetector API; generation uses qrcode.react SVG output.

Protocol constraints are intentional:

• Payloads are compact JSON for QR density and quick scanning
• Relay hops are capped at 5 to limit stale propagation
• This is an infrastructure-free fallback, not a replacement for a true radio or mesh stack

The value of this system is not "high throughput." The value is that one phone can still move survival-critical data to the next phone when everything else is failing.

Risk-stratified 3-layer guidance system:

• Priority Right Now: 6–8 cards computed from current risk level + household profile. Zero AI required.
• Browse All: 24 categorized cards across 6 domains (Flood & Water, Medical, Supplies, Shelter, Communication, Family & Vulnerable). Routes to decision trees, AI queries, or direct navigation.
• AI Insight Mid-Flow: aiHint cards appear inline at critical decision tree nodes — context-aware survival tips in EN/TH/MS.

Interactive hub map with region-aware sorting, status indicators (Open/Full/Closed/Unknown), service icons, and Google Maps deep-link integration. Community-submitted hubs (via QR-P2P or in-app registration) are visually distinguished from admin-verified data.

Swipe-to-action (mobile): Swipe left on any hub card to reveal action buttons:

• Bookmark — pins the hub; bookmarked hubs surface first in the Home screen Safe Hub Locator
• Edit — update hub status and available services (crowdsourced community report)
• Delete — remove the hub (community-registered hubs only)

Hover-to-action (desktop): Hover over any hub card to reveal the same three action buttons at the bottom of the card.

Entire application shell (HTML/JS/CSS) cached via Service Worker. App boots instantly at 0 bytes/sec. WebGPU model cached in IndexedDB after first download.

GAIA-119 is the AI persona powering the Ask AI (GAIA-119) feature. Not a generic chatbot — engineered as a Thai National Disaster Response AI (AESE-CrisisShield) with a fixed mission: deliver survival-critical action orders in under 5 seconds.

Design principles:

• CR-EP Why Framework: Every output constraint is anchored to a measurable survival goal (≤12 words/action, decision < 5 seconds)
• 5-Module AESE Pipeline: EmergencySignalScanner → UrgencyClassifier → CalmToneInfuser → CognitiveFocusRedirector → ContactProtocolRecommender
• ResponseFusion Dual-Pipeline: Calm-sounding inputs scanned for hidden crisis signals before urgency classification
• SITUATION OVERRIDE: Explicit user situation always overrides passive sensor context
• Zero-drift multilingual output: 3-language few-shot examples (EN/TH/MS) ensure consistent JSON structure

See docs/gaia-119.md for the full technical specification.

1. Core Technology — WebLLM, Vite PWA, Streaming Architecture, Offline Fallback Chain, Real-Time Weather Intelligence
2. GAIA-119 AI Persona Spec — Intent-based persona ontology, AESE pipeline, context injection, rain threshold calibration
3. Usability & Cognitive Engineering — ISO Safety Colors, Haptic design, Dynamic UI, Rain Mode accessibility
4. Usage Guide — Onboarding, WebLLM initialization, Quick Assist flows, Forecast Tabs, Hub registration
5. AI Engine Field Notes — Qwen3 rollback rationale, WebLLM hard limits, /no_think pitfalls, token budget analysis, paths to fine-tuning
6. dev.to Article — Technical deep-dive: WebGPU streaming, GAIA-119 architecture, QR-P2P protocol, lessons learned
7. Bundle Optimization Roadmap — Planned Vite chunk reduction strategy without changing product behavior

• Node.js >= 20 (required for Vite 7)
• Browser: Chrome 113+ or Edge 113+ (required for WebGPU on-device AI). Firefox not supported. Safari has experimental WebGPU support.
• (Optional Dev): Ollama on port 11434 with qwen3:1.7b pulled

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

1. npm run build — generates /dist
2. Deploy /dist to any static edge host: Vercel, Netlify, Cloudflare Pages
3. HTTPS required — WebGPU and Service Workers only function over secure contexts

Live deployment: https://flood-ready.vercel.app

The current roadmap for bundle-size reduction and Vite chunk optimization is now tracked in the Flamehaven-ONDEVICE-AI project:

• flood-ready-bundle-optimization.md

This roadmap is explicitly scoped to performance delivery improvements. It does not propose removing on-device AI, changing GAIA-119 behavior, or weakening the offline-first emergency model.

• AI Response Time: WebGPU inference takes 15–30 seconds per response. Streaming delivers first tokens in ~2 seconds. Users are informed upfront.
• WebGPU Requirement: Chrome 113+ or Edge 113+ required. Fallback chain (Ollama → keyword dictionary) activates automatically on unsupported browsers.
• Model Pre-download: The ~1.1GB Qwen2.5-1.5B model must be downloaded before first use. Users who skip receive keyword-based fallback responses.
• PWA Icons: The PWA manifest uses a placeholder vite.svg. Replace with production icons (192×192, 512×512 PNG) before public release.
• QR-P2P Relay: Each relay hop requires physical camera scanning. Not a replacement for a full mesh protocol (e.g., libp2p, gun.js) — designed as an infrastructure-free fallback.

AI Engine Notes: For detailed findings on WebLLM limitations, Qwen3 rollback rationale, token budget analysis, and paths to fine-tuning, see docs/ai-engine-lessons.md.