chore(repo): v2.0.2 repository health

.github/ISSUE_TEMPLATE/hardware_issue.md

@@ -0,0 +1,40 @@
+---
+name: Hardware Issue
+about: Report a hardware-related problem (PCB, wiring, components, assembly)
+title: "[HW] "
+labels: hardware
+---
+
+# Description
+A clear description of the hardware issue. Specify which board revision and components are affected.
+
+# Guidelines
+Before submitting, please verify:
+- [ ] You have checked the [Bill of Materials (BOM)](https://github.com/GiZano/QuakeGuard/wiki/Bill-of-Materials) and confirmed correct components
+- [ ] You have verified wiring against the [Pinout Table](firmware/PINOUT.md)
+- [ ] You have included photos or serial output below
+
+# Hardware Details
+- **PCB Revision:** <!-- e.g. v2.0.0 JLCPCB -->
+- **Assembly Method:** <!-- PCB / Breadboard -->
+- **Component Affected:** <!-- e.g. ADXL345, ESP32-C3, NEO-6M, LED, Resistor -->
+- **Power Source:** <!-- USB / External -->
+
+# Steps to Reproduce
+1.
+2.
+3.
+
+# Serial Monitor Output
+```
+<!-- Paste relevant serial output here -->
+```
+
+# Photos
+<!-- Attach photos of the hardware setup, solder joints, or wiring if applicable -->
+
+# Expected Behavior
+What should happen with correct hardware operation.
+
+# Actual Behavior
+What is actually happening. Include any error LEDs, missing readings, or unexpected behavior.

.github/dependabot.yml

@@ -0,0 +1,42 @@
+# Dependabot — Automated dependency updates for QuakeGuard
+# Docs: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates
+version: 2
+updates:
+  # --- Python (Backend) ---
+  - package-ecosystem: "pip"
+    directory: "/backend"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    labels:
+      - "dependencies"
+      - "backend"
+    commit-message:
+      prefix: "chore(deps)"
+    open-pull-requests-limit: 5
+
+  # --- npm (Mobile) ---
+  - package-ecosystem: "npm"
+    directory: "/mobile"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    labels:
+      - "dependencies"
+      - "mobile"
+    commit-message:
+      prefix: "chore(deps)"
+    open-pull-requests-limit: 5
+
+  # --- GitHub Actions ---
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "chore(ci)"
+    open-pull-requests-limit: 5

.github/workflows/gitleaks.yml

@@ -0,0 +1,24 @@
+name: "Gitleaks — Secret Scanning"
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  scan:
+    name: Detect Leaked Secrets
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          fetch-depth: 0
+
+      - name: Run Gitleaks
+        uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196e88a9c30
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -62,4 +62,9 @@ extract.sh
 research/data/
 research/out/
 research/*.png
-firmware/tools/detect_cli
+firmware/tools/detect_cli
+
+# ------------------------------------------
+# KiCad local history
+# ------------------------------------------
+.history/

CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.2] - 2026-09-03
+### Added
+- **Dependabot Configuration:** Automated dependency updates for pip (backend), npm (mobile), and GitHub Actions (`.github/dependabot.yml`).
+- **Gitleaks Secret Scanning:** CI workflow (`.github/workflows/gitleaks.yml`) to prevent accidental credential leaks in commits — critical for a project handling ECDSA keys and MQTT credentials.
+- **Architecture Decision Records (ADRs):** Created `docs/adr/` with 4 initial ADRs documenting key architectural decisions: Redis Streams (0001), HiveMQ Cloud (0002), Hybrid Edge AI (0003), CERN-OHL licensing (0004).
+- **C4 and Sequence Diagrams:** Created `docs/diagrams/` with Mermaid diagrams: C4 Context/Container, provisioning sequence, alert delivery sequence, and triangulation sequence — versionable independently from the Typst whitepaper.
+- **Firmware Versioning:** Added `#define FIRMWARE_VERSION "2.0.2"` printed at boot via serial for field identification and remote debugging.
+- **Pinout Reference:** Created `firmware/PINOUT.md` — unified GPIO mapping, LED behavior table, connector pinout, and passive component reference.
+- **Flashing Guide:** Created `firmware/FLASHING.md` — standalone step-by-step flashing instructions for users without VS Code/PlatformIO IDE.
+- **Privacy Policy:** Created `mobile/PRIVACY_POLICY.md` — documents data collection, storage, and third-party services for App Store/Play Store compliance.
+- **SUPPORT.md:** Routing guide for all help channels (bugs, features, hardware, security, discussions).
+- **Hardware Issue Template:** `.github/ISSUE_TEMPLATE/hardware_issue.md` for PCB, wiring, and component assembly reports.
+- **Docker Compose Override Example:** `backend/docker-compose.override.yml.example` for local development customization.
+
+### Changed
+- **Dockerfile Multi-Stage Build:** Refactored `backend/Dockerfile` to a two-stage build (builder + runtime), reducing final image size by excluding build toolchain (gcc, python3-dev).
+- **BOM Enrichment:** Expanded `hardware/QuakeGuard_PCB/output/BOM.csv` with manufacturer, part number, unit cost, distributor links (LCSC/DigiKey), and socketable modules (ESP32-C3, ADXL345, NEO-6M).
+- **README Enhancements:** Added "PRs welcome" badge, prominent landing page link, CERN-OHL license reference, hardware compliance disclaimer, and v2.0.2 roadmap entry.
+- **Version artifacts bumped to v2.0.2** (CITATION.cff, firmware header, README roadmap, SECURITY.md).
+
 ## [2.0.1] - 2026-09-01
 ### Changed
 - **Documentation Polish (Zenodo Sync):** Removed residual LLM tags (`[cite: 1]`) from the technical whitepaper.

CITATION.cff

@@ -10,12 +10,12 @@ authors:
     given-names: "Riccardo"
     alias: "riccardo0731"
 title: "QuakeGuard"
-version: 2.0.1
+version: 2.0.2
 identifiers:
   - type: doi
     value: "10.5281/zenodo.21710405"
     description: "Concept DOI (Absolute - resolves to all versions)"
-date-released: 2026-09-01
+date-released: 2026-09-03
 url: "https://giovanni-zanotti.is-a.dev/projects/quakeguard.html"
 repository-code: "https://github.com/GiZano/QuakeGuard"
 license: "AGPL-3.0"

README.md

@@ -32,6 +32,8 @@
 [![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=GiZano_QuakeGuard&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=GiZano_QuakeGuard)
 [![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=GiZano_QuakeGuard&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=GiZano_QuakeGuard)
 
+![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge)
+
 > 📚 **Technical Specification:** A comprehensive architecture whitepaper is available in the `docs/` directory, compiled via Typst. For a browsable, topic-by-topic reference, check out the [project Wiki](https://github.com/GiZano/QuakeGuard/wiki).
 
 ![QuakeGuard Logo](docs/web/assets/quakeguard/github-banner.png)
@@ -41,6 +43,10 @@
 
 ---
 
+🌐 **[Landing Page](https://giovanni-zanotti.is-a.dev/projects/quakeguard.html)** · 📚 **[Wiki](https://github.com/GiZano/QuakeGuard/wiki)** · 📄 **[Whitepaper (PDF)](docs/whitepaper/)** · 🗺️ **[ROADMAP](ROADMAP.md)**
+
+---
+
 ## 📖 Overview
 
 **QuakeGuard** is a full-stack IoT architecture for real-time detection, analysis, and reporting of seismic events. The system transforms everyday household appliances — washing machines, TVs, refrigerators — into a distributed seismic sensor network, each node capable of detecting and reporting earthquake activity autonomously.
@@ -434,6 +440,7 @@ QuakeGuard/
 | **v1.2.2** | ✅ Released — Zero-Trust Serial Fallback — signed telemetry over USB CDC (serial) when MQTT is unreachable |
 | **v2.0.0** | ✅ Released — Triangulation (multi-node spatial correlation), Hybrid Network Architecture, Automated DevOps Orchestration (Ptyxis), Local Factory Provisioning, GNSS sync, NTP+PPS, ADXL calibration, and INGV FDSN SIL validation |
 | **v2.0.1** | ✅ Released — Documentation & Zenodo Sync: PDF/Wiki architectural coherence (Cloudflare, 300s anti-replay), CERN-OHL hardware licensing, SIL vs Firmware threshold clarification, and `CITATION.cff` bump |
+| **v2.0.2** | ✅ Released — Repository Health: Dependabot, Gitleaks CI, ADRs, C4/sequence diagrams, multi-stage Dockerfile, firmware versioning, pinout table, flashing guide, privacy policy, hardware compliance disclaimer |
 | **v2.1** | Data Dashboards — Grafana dashboards for real-time visualization of seismic telemetry |
 | **v2.1.1** | Timeseries DB & Mobile Fix — migration to TimescaleDB/InfluxDB; per-sensor chart isolation in React Native mobile |
 | **v2.2** | Heterogeneous Edge Intelligence — hybrid Tier A (STA/LTA) + Tier B (quantized CNN) decision fusion |
@@ -462,6 +469,11 @@ QuakeGuard's architecture and real-world applicability have been recognized in t
 This project is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**.
 See the [LICENSE](LICENSE) file for details.
 
+Hardware designs (`hardware/`) are licensed under the **CERN Open Hardware Licence v2 — Strongly Reciprocal (CERN-OHL-S-2.0)**.
+See [hardware/LICENSE](hardware/LICENSE) for details.
+
+> ⚠️ **Hardware Compliance:** The QuakeGuard PCB is **not certified for CE/FCC/RoHS**. It is intended for **prototyping, educational, and research use only**. Do not deploy as a commercial safety-critical device without appropriate regulatory certification.
+
 ---
 
 <div align="center">

ROADMAP.md

@@ -103,6 +103,24 @@ Documentation-only patch aligning the technical whitepaper, GitHub Wiki, and pro
 
 ---
 
+## v2.0.2 — Repository Health (Released)
+
+Comprehensive repository maturity improvements: CI hardening, architectural documentation, developer experience, and compliance foundations.
+
+- ✅ **Dependabot** for automated dependency updates (pip, npm, GitHub Actions)
+- ✅ **Gitleaks** secret scanning in CI (prevents credential leaks)
+- ✅ **Architecture Decision Records (ADRs):** 4 initial ADRs (Redis Streams, HiveMQ, Hybrid Edge AI, CERN-OHL)
+- ✅ **C4 and Sequence Diagrams** in Mermaid (versionable, GitHub-renderable)
+- ✅ **Multi-stage Dockerfile** (builder + runtime stages, reduced image size)
+- ✅ **Firmware versioning** (`FIRMWARE_VERSION` define, printed at boot)
+- ✅ **Pinout reference** (`firmware/PINOUT.md`) and **Flashing guide** (`firmware/FLASHING.md`)
+- ✅ **Privacy Policy** (`mobile/PRIVACY_POLICY.md`) for App Store/Play Store readiness
+- ✅ **SUPPORT.md**, **Hardware Issue Template**, **Docker Compose override example**
+- ✅ **BOM enrichment** (manufacturer, cost, distributor links, socketable modules)
+- ✅ **README enhancements** (landing page link, PRs welcome badge, hardware disclaimer)
+
+---
+
 ## v2.1.0 — Data Dashboards
 
 Grafana dashboards for real-time visualization of seismic telemetry.

SECURITY.md

@@ -5,7 +5,7 @@ QuakeGuard takes the security of its IoT early warning infrastructure very serio
 
 | Version | Supported          | Notes |
 | ------- | ------------------ | ----- |
-| 2.0.x   | :white_check_mark: | Current stable release (Hybrid Network Architecture, GNSS Precision & SIL Validation). |
+| 2.0.x   | :white_check_mark: | Current stable release (Repository Health, Hybrid Network Architecture, GNSS Precision & SIL Validation). |
 | 1.3.x   | :white_check_mark: | Prior stable release (GNSS Precision & SIL Validation). |
 | 1.2.x   | :x:                | Deprecated. (Cloud MQTT + TLS + on-premise AI reports). |
 | 1.1.x   | :x:                | Deprecated. Cloud MQTT + TLS. |

SUPPORT.md

@@ -0,0 +1,26 @@
+# Getting Help with QuakeGuard
+
+Thank you for using QuakeGuard! Here's how to get support depending on your situation.
+
+## 🐛 Bug Reports
+If you've found a reproducible bug, please open a [Bug Report](https://github.com/GiZano/QuakeGuard/issues/new?template=bug_report.md).
+
+## 💡 Feature Requests
+Have an idea for a new feature or improvement? Open a [Feature Request](https://github.com/GiZano/QuakeGuard/issues/new?template=feature_request.md).
+
+## 🔧 Hardware Issues
+Problems with the PCB, wiring, or component assembly? Open a [Hardware Issue](https://github.com/GiZano/QuakeGuard/issues/new?template=hardware_issue.md).
+
+## 💬 Questions & Discussion
+For general questions, architecture discussions, or community conversations, use [GitHub Discussions](https://github.com/GiZano/QuakeGuard/discussions).
+
+## 🔐 Security Vulnerabilities
+**DO NOT** open a public issue for security vulnerabilities. Please read our [Security Policy](SECURITY.md) and report privately to **gizano.dev@gmail.com**.
+
+## 📚 Documentation
+- **Technical Whitepaper:** Available in `docs/whitepaper/` (compiled via Typst)
+- **Project Wiki:** [github.com/GiZano/QuakeGuard/wiki](https://github.com/GiZano/QuakeGuard/wiki)
+- **Landing Page:** [giovanni-zanotti.is-a.dev/projects/quakeguard.html](https://giovanni-zanotti.is-a.dev/projects/quakeguard.html)
+
+## 📧 Direct Contact
+For anything not covered above, reach out at **gizano.dev@gmail.com**.

backend/Dockerfile

@@ -1,28 +1,40 @@
-FROM python:3.11-slim
+# =============================================================================
+# Stage 1: Build — install system deps and compile Python wheels
+# =============================================================================
+FROM python:3.11-slim AS builder
 
-RUN addgroup --system --gid 1001 appgroup && \
-    adduser --system --uid 1001 --gid 1001 --no-create-home appuser
-
-WORKDIR /app
+WORKDIR /build
 
-# Install dependencies for PostgreSQL
 RUN apt-get update && apt-get install --no-install-recommends -y \
     gcc \
     python3-dev \
     && rm -rf /var/lib/apt/lists/*
 
-# Copy requirements and install Python dependencies
 COPY requirements.txt .
-RUN pip install --no-cache-dir --only-binary :all: --require-hashes -r requirements.txt
+RUN pip install --no-cache-dir --only-binary :all: --require-hashes \
+    --prefix=/install -r requirements.txt
 
-USER appuser
+# =============================================================================
+# Stage 2: Runtime — slim image with only compiled packages and app code
+# =============================================================================
+FROM python:3.11-slim AS runtime
+
+RUN addgroup --system --gid 1001 appgroup && \
+    adduser --system --uid 1001 --gid 1001 --no-create-home appuser
+
+WORKDIR /app
+
+# Copy pre-built Python packages from builder
+COPY --from=builder /install /usr/local
 
 # Set PYTHONPATH to include both /app and /app/src
 ENV PYTHONPATH="/app:/app/src"
 
 # Copy application code
 COPY src/ ./src/
 
+USER appuser
+
 # Expose port
 EXPOSE 8000
 

backend/docker-compose.override.yml.example

@@ -0,0 +1,32 @@
+# docker-compose.override.yml — Local Development Overrides
+#
+# This file is automatically loaded by Docker Compose alongside docker-compose.yml.
+# Use it to customize the stack for local development without modifying the base config.
+#
+# Usage:
+#   cp docker-compose.override.yml.example docker-compose.override.yml
+#   # Edit as needed, then:
+#   docker compose up --build -d
+
+services:
+  # --- Bind-mount source code for hot reload ---
+  fastapi-app:
+    volumes:
+      - ./src:/app/src:ro
+    environment:
+      - LOG_LEVEL=DEBUG
+
+  worker:
+    volumes:
+      - ./src:/app/src:ro
+    environment:
+      - LOG_LEVEL=DEBUG
+
+  # --- Expose additional ports for debugging ---
+  postgres:
+    ports:
+      - "5432:5432"
+
+  redis:
+    ports:
+      - "6379:6379"

docs/adr/0001-redis-streams-ingestion.md

@@ -0,0 +1,33 @@
+# ADR-0001: Redis Streams as the Ingestion Transport
+
+## Status
+Accepted (v2.3.0)
+
+## Context
+QuakeGuard's original ingestion pipeline used a Redis `LPUSH`/`BRPOP` list queue with a single-consumer worker. While simple, this design has inherent scaling limitations:
+
+- **Single consumer:** Only one worker process can drain the queue, creating a bottleneck under load.
+- **No at-least-once delivery:** A crashed worker loses the popped message.
+- **No message inspection:** No way to audit pending or failed messages.
+- **No replay:** Once consumed, a message is gone.
+
+As the sensor network grows beyond ~150 nodes, the single-consumer list becomes the throughput ceiling.
+
+## Decision
+Replace the Redis list queue with **Redis Streams** (`XADD`/`XREADGROUP`):
+
+- Producers append via `XADD` to `readings:stream` (O(1)).
+- Workers form a **consumer group**, enabling horizontal scaling (`docker compose scale worker=N`).
+- `XAUTOCLAIM` recovers pending entries across worker restarts (at-least-once delivery).
+- Poisoned messages are parked on `readings:dlq` (dead-letter queue) instead of stalling the group.
+- Batched DB commits: a stream batch (default 64 messages) is written in one transaction.
+
+## Consequences
+- **Positive:** Horizontal worker scaling, at-least-once delivery, DLQ for debugging, batched writes.
+- **Negative:** Slightly more complex consumer logic vs. simple `BRPOP`.
+- **Neutral:** The `enqueue_reading` / `read_batch` / `ack` interface in `src/ingest.py` is transport-agnostic, so a future Kafka backend can slot in without touching the worker.
+
+## Alternatives Considered
+- **Kafka/Redpanda:** More scalable but adds an entirely new infrastructure dependency. Documented as the next step for millions-class ingestion (see ROADMAP.md "Future Horizon").
+- **RabbitMQ:** Feature-rich but heavier; Redis is already in the stack.
+- **Keep LPUSH/BRPOP:** Insufficient for consumer groups and recovery.