kestrel

Early warning that proves it was understood.

Comment

Inspiration

IGAD's own brief for this hackathon names four steps in a functioning early-warning system: generate information, communicate it, ensure it is understood, and turn it into action. Most existing tools stop at step two. A warning is issued, an SMS blast goes out, and nobody on the sending end knows whether anyone actually read it, understood it, or changed their behavior because of it. The gap between "sent" and "understood" is where lives are lost.

We wanted to build the system that closes that gap.

The name comes from the kestrel, a bird of prey that hunts by hovering perfectly still in the air, scanning the ground below for the smallest signal of movement, then acting precisely at the moment it matters. That is the behavior we wanted the product to replicate: watch, detect, warn, and verify that the warning landed.

What it does

Kestrel is a four-step loop:

  1. Pull live hazard data. Real weather readings from Open-Meteo for eight locations across all IGAD member states. A transparent, rule-based classifier (not a black-box model) evaluates each reading and flags flood, drought, or extreme heat hazards at WATCH, WARNING, or EMERGENCY severity.

  2. AI drafts a plain-language warning. Groq (llama-3.3-70b-versatile) converts the raw hazard signal into a short, action-first message a farmer or community leader can act on immediately. Not a meteorological bulletin.

  3. Human review, then dispatch. An officer reviews, edits, and approves every warning before it goes out. Nothing dispatches automatically. Approved warnings go to a real Telegram bot (with tap-to-confirm buttons) and a clearly labeled SMS/USSD simulation.

  4. Verify comprehension, then escalate. Recipients confirm understanding with a single tap. A live dashboard tracks delivery and confirmation rates per location in real time. When any location drops below 50% confirmation, a second AI pass reads the actual numbers and recommends a specific fallback: switch to community radio, re-send in a local language, deploy a field team.

Generate. Communicate. Confirm. Escalate. The full loop IGAD asked for.

How we built it

  • Frontend: Next.js 14 (App Router, TypeScript) with a fully custom editorial design system. Warm paper background, ink-black type, a single ochre accent. No default Tailwind look. Real documentary-style photography sourced from Unsplash with full attribution.
  • Maps: MapLibre GL JS with OpenFreeMap tiles, restyled to match the paper/ink/ochre palette. Custom severity-colored markers for all eight IGAD-region locations.
  • Charts: D3.js for the verification dashboard: a per-location confirmation-rate comparison chart and a cumulative confirmation curve.
  • AI: Groq API (llama-3.3-70b-versatile) for two distinct tasks: warning generation (hazard data to plain language) and escalation analysis (confirmation gap to recommended fallback action).
  • Weather data: Open-Meteo (free, no API key required) for current conditions and 3-day forecasts for all seeded locations.
  • Hazard classification: Rule-based thresholds documented in the codebase. Deterministic and auditable, not an AI guess.
  • Real delivery channel: Telegram Bot API with inline keyboard buttons and a webhook for real-time confirmation callbacks.
  • Database: PostgreSQL via Prisma, modeling the full chain: Location > HazardSignal > Warning > Dispatch > Confirmation > EscalationSuggestion.
  • Deployment: Vercel.

Challenges we faced

  • Telegram MarkdownV2 escaping. Warnings containing periods, hyphens, or parentheses broke outbound messages silently because Telegram's MarkdownV2 mode requires escaping nearly every special character. Took real debugging with live sends to isolate.
  • Webhook reliability. The Telegram webhook would 500 on expired button-tap callbacks even after the confirmation was already recorded, causing Telegram to retry the same update in an infinite loop. Had to isolate the non-critical toast acknowledgment so it could never affect the durable database write.
  • N+1 query performance. The initial dispatch and simulation routes did one sequential database round-trip per recipient (20+ seconds for 20 recipients against hosted Postgres). Batched into bulk operations, brought it under 2 seconds.
  • Prompt quality. The first-pass AI warnings were too generic ("Find water now"). Iterated the prompt with real hazard data until outputs were specific and location-aware ("Ration water for children and animals first, the next rain forecast for Lodwar is more than 5 days away").
  • Honest scope. Resisted the temptation to fake a live SMS gateway. Labeled the SMS/USSD channel as a simulation throughout the UI, and focused on making the one real channel (Telegram) provably functional end to end.

What we learned

The hardest part of building an early-warning system is not the AI or the data. It is the verification step: proving that a specific person in a specific place actually understood what to do. Building that loop, even in prototype form, revealed why almost no existing system does it. It requires a confirmation mechanism usable by someone with low digital literacy, an aggregation layer fast enough to be useful in real time, and an escalation logic that actually recommends something concrete instead of just flagging red. Each of those is a separate engineering problem, and skipping any one of them breaks the value of the whole loop.

What's next

  • Wire Africa's Talking SMS gateway for real SMS/USSD delivery across IGAD-region mobile networks
  • Local-language translation layer (Swahili, Amharic, Somali, Arabic) using the same Groq pipeline
  • Multi-organization support so different national disaster agencies can operate their own warning pipelines on the same platform
  • Historical trend analysis: which locations consistently lag in comprehension, and why

Built With

Share this project:

Updates