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.0
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 HiveMQ Cloud (TLS, port 8883).Bridge →
POST /readings/. API key, sensor status, anti-replay (60 s) and signature are all validated.Rate limit (50 req/s per IP) passes → event pushed to the Redis list; 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 PostgreSQL + PostGIS; a 60 s Redis cooldown per 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 and ECDSA signing on every payload.
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 Queue + Pub/Sub
Decouples ingestion from processing (producer-consumer). Queue offloading, 60 s per-zone dedup locks and 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
HiveMQ Cloud broker over TLS. A dedicated bridge microservice forwards telemetry to the secure HTTP pipeline, injecting the API key.
TLS 8883PahoBridge
PostgreSQL + PostGIS
Spatial persistence. Sensors auto-assigned to the smallest containing macro-region via ST_Contains, ordered by area.
React Native App
Three-tab app (Monitor, Sensor Map, Settings). WebSocket alerts with SOS haptics & push, live seismograph, offline mode, last-10 alert history, plus a new AI Report UI: banner for the latest alert, feed cards with summary + recommendations, and a "AI Report Unavailable" badge on FAILED.
ExpoZustandTanStack Query
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-zone 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 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 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 60 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. Sensors are auto-assigned to the smallest containing polygon via a PostGIS spatial query — with an Unknown Region fallback for unmapped coordinates.
Roadmap
Edge seismic detection on ESP32-C3 and local alerts.
HiveMQ Cloud MQTT (TLS), ngrok HTTPS tunnel, security hardening.
LLM backend for automatic emergency-report generation from MQTT telemetry.
Accurate node timestamps, GPS coordinate resolution and ADXL345 calibration.
Multi-node spatial correlation + AI reports for epicenter calculation.
Grafana live visualization of seismic telemetry.
Project Health
CI/CD
Five automated pipelines gate every change:
backend-ci— Bandit, Safety, stress testfrontend-ci— ESLint, npm auditiot-ci— PlatformIO compilationpr-lint+devops-ci- ✔️ 85 backend tests + 17 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. After the conference, our collaboration with him is exactly where the project’s story began.
Sorint.lab — Hackersgen
University of Bergamo
The experience
Watch the demo with captions available in English and Italian.
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.