Detection for everyone
We want to make earthquake detection available all around the world, with zero cost for the people and low cost for the enterprises. By embedding miniature IoT sensors inside the objects we already live with, we can grant P-wave detection without anyone even knowing — and give people time to evacuate or reach a safe location before it is too late.
Trigger an earthquake
A faithful, client-only echo of the backend's POST /demo/trigger-earthquake flow:
pick one of the 8 geographic zones, set a magnitude ≥ 4.5 and watch the pipeline run from edge
to mobile alert + AI report.
Historically the backend bypasses the IoT pipeline and
pushes to the
Redis quake_alerts channel — the mobile app vibrates and fires a push
notification within milliseconds.
Ingestion → Alert pipeline
Recent critical events (last 10)
AI Emergency Report v1.2.1
Moderate-strong event detected by 12 sensors in Sicily. Shaking intensity IV-V MMI; recommend staying away from windows and tall furniture, and monitoring aftershocks over the next 2 hours.
System Architecture
ADXL345 at 100 Hz → HPF removes gravity → STA/LTA ratio > 1.8 flags an event.
Firmware signs the payload with ECDSA NIST P-256 — the private key never leaves the device’s NVS.
MQTT publish to
quakeguard/telemetry on local Eclipse Mosquitto (port
1883).Bridge →
POST /readings/. API key, sensor status,
anti-replay (300 s) and signature are all validated.Rate limit (50 req/s per IP) passes → event appended to Redis Streams (
readings:stream); API replies 202 Accepted instantly.Worker estimates
M = log10(PGA / 1.6) + 3.0; if M ≥ 4.5 an Alert
is triggered.Atomically saved to TimescaleDB (hypertable) + PostGIS; a per-area Redis cooldown (geohash region or zone) prevents alert storms (outbox pattern).
WebSocket broadcast → mobile SOS haptic vibration + high-priority push notification, sub-second delivery.
ai_report_queue in Redis → worker → Ollama
generates the emergency report on-premise; persisted and pushed on the ai_reports WebSocket channel.IoT Edge Sensors
ESP32-C3 (RISC-V) + ADXL345 accelerometer. Runs a FreeRTOS DSP pipeline with O(1) ring-buffer STA/LTA, ECDSA signing on every payload and an optional GNSS subsystem (NEO-6M/M8N) with NVS last-known-fix.
ESP32-C3STA/LTA100 Hz
FastAPI Cloud
Fully async Python 3.11 gateway. Sliding-window rate limiting, API-key auth, ECDSA verification and anti-replay — designed to sustain the Thundering Herd.
AsyncRate limitUvicorn
Redis Streams + Pub/Sub
Decouples ingestion from processing (producer-consumer). Redis
Streams offloading, per-area dedup locks, a Dead Letter Queue on failure — plus a
dedicated ai_report_queue for the ai_report_worker.py, decoupled from the alert engine.
MQTT Data Plane
Eclipse Mosquitto broker. A dedicated bridge microservice forwards telemetry to the secure HTTP pipeline, injecting the API key.
Port 1883PahoBridge
PostgreSQL + TimescaleDB + PostGIS
Time-series + spatial persistence. Sensor data lands in a
TimescaleDB hypertable; zones resolve through a geohash fast-path Redis index, with
PostGIS ST_Contains as the authoritative fallback.
React Native App
Three-tab app (Monitor, Sensor Map, Settings). Per-zone live
seismograph with a horizontal zone strip, GPS "Detect my zone" via GET /zones/locate, WebSocket alerts with SOS haptics
& push, siren audio (expo-audio), MIC/RESEARCH
dual theme, offline mode, OTA in-app updater, last-10 alert history and AI report cards.
The Thundering Herd
Earthquakes don’t knock on one door. When hundreds of sensors in the same zone detect the same event at once, the backend is hit by a massive, synchronous traffic spike.
QuakeGuard is engineered for exactly that moment: ingestion is decoupled from processing,
requests return
202 Accepted in milliseconds, connection pooling absorbs
the load, and a
per-area Redis cooldown guarantees the network fires one clean
alert — not a storm of duplicates.
How the spike is absorbed
Ingestion never waits on the database; events offload to Redis Streams instantly.
50 req/s per IP, backs off buggy or malicious nodes early.
Aggressive SQLAlchemy pool configured for high concurrency, no queue exhaustion.
Dedup lock per geohash region or zone; only the winning worker publishes the Alert (outbox pattern).
Cryptographic Security
Data integrity is paramount in an emergency system. Every telemetry packet is cryptographically secured end-to-end against spoofing, replay and tampering.
The 4 validation gates
Checked on every request using a constant-time comparison to resist timing attacks.
Confirms the sensor exists and is marked active in the database.
Timestamps older than the 300 s window are rejected
outright with 403 Forbidden.
Payload verified against the device public key — both DER and raw r||s forms supported.
Identity & threat coverage
On first boot each ESP32-C3 generates its own NIST P-256 ECDSA
keypair (mbedTLS).
The private key is sealed in Non-Volatile Storage and never leaves the
device; the public key becomes the
unforgeable identity used during the automated /devices/register provisioning handshake.
Geographic Zones
8 global macro-regions are pre-seeded. Zone resolution uses a geohash Redis fast path, with
PostGIS
ST_Contains as the authoritative fallback — plus an Unknown Region
fallback for unmapped coordinates. The mobile app can detect your zone with one tap via GET /zones/locate.
Roadmap
Development
Edge seismic detection on ESP32-C3 and local alerts.
Eclipse Mosquitto MQTT, Cloudflare HTTPS tunnel, security hardening.
On-Premise AI Reports — Ollama generates emergency reports on-premise, pushed over WebSocket.
Geo-Zoning & Cooldown Fragmentation
(GNSS-ready) — geohash Redis fast-path zone resolution,
per-area cooldown locks, PostGIS ST_Contains as source of truth.
Zero-Trust Serial Fallback — ECDSA-signed telemetry over USB CDC when MQTT/WiFi is unreachable, with host-aware retention and automatic first-boot provisioning.
Triangulation, Hybrid Cloud Architecture, DevOps deployment scripts, GNSS NTP + PPS timestamps, ADXL345 calibration, and SIL integration testing.
Documentation & Zenodo Sync — PDF/Wiki architectural coherence (Cloudflare, 300s anti-replay), CERN-OHL licensing, SIL threshold clarification.
Data Dashboards & Observability — Grafana live visualization of system telemetry, End-to-End Latency tracking, and true Local Mosquitto resilience.
Demo Calibration & Repository Fixes — dynamic GIS epicenter calculation, precise ADXL345 mock calibration, and Pisa Hollywood simulator.
Research
SIL STA/LTA cross-validation — pure C++ core, host orchestrator, metrics and trigger calibration on the synthetic fallback. Real ESM ground-truth validation remains.
AI benchmarking — P50/P99 latency of the local Ollama worker, hallucination rate, privacy/latency vs cloud baseline.
Dissemination — open validation dataset (Zenodo DOI) + technical paper / preprint.
R1 is the blocking prerequisite for the v2.2.0 Edge AI tier and runs in parallel with v1.3 (GNSS).
Project Health
Mission Control Dashboard
Automated Grafana provisioning provides complete network observability. The dashboard features real-time aggregated seismographs, IoT telemetry (RSSI, active nodes, free heap), backend latency metrics.
CI/CD
Five automated pipelines gate every change:
backend-ci— Bandit, Safety, stress testfrontend-ci— ESLint, npm auditiot-ci— PlatformIO compilationpr-lint+devops-ci- Dedicated
geo/timescale/zoneCI jobs - ✔️ 104 backend tests + 23 mobile tests
Stress test
Validates the full ingestion → Redis → worker → PostGIS → WebSocket pipeline against a simulated massive seismic event.
- 🔥 150 concurrent sensors — rate limiter
- ⚔️ Bad signature (401) + replay (403)
- 🤖 AI dedup stress test — 50 raw alerts → 1 report
- 🔍 DB persistence verified end-to-end
Deep documentation
A Typst-compiled whitepaper walks through architecture, hardware, security, the broker, backend, mobile and deployment.
Open source under AGPL-3.0, with a DOI, contributing guide and security policy.
Mentorship & Recognition
Developed as a school-contest project for Hackersgen by Sorint.lab and the GF Marilli competition — in collaboration with riccardo0731.
We were honored to work with Francesco Finazzi — UniBG professor and founder of Earthquake Network, the largest community seismic network in the world. Our collaboration following the conference was the true genesis of this project.
Sorint.lab — Hackersgen
University of Bergamo
The experience
Watch the demo with captions available in English and Italian.
Trailer
Explanation
Contribute or collaborate
QuakeGuard is open source and community-driven. Ideas, issues and pull requests are always welcome — pull in, and let’s build a safer world together.