vigia-eew 0.3.1__tar.gz

vigia_eew-0.3.1/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.spec.bak
+
+# Entornos
+.venv/
+venv/
+env/
+
+# Herramientas
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# uv
+uv.lock
+
+# IDE
+.idea/
+.vscode/
+
+# Runtime
+*.log
+state.json
+config.toml

vigia_eew-0.3.1/ARCHITECTURE.md

@@ -0,0 +1,187 @@
+# ARCHITECTURE — Vigía-eew
+
+| Field | Value |
+|---|---|
+| Document | System architecture and diagrams |
+| Version | 1.0 (draft for review) |
+| Status | 🟡 Pending approval |
+| Related | `docs/PRD.md`, `docs/API-SPEC.md`, `docs/TECHNICAL-DESIGN.md`, `docs/DATA-MODEL.md`, `docs/IMPLEMENTATION-PLAN.md` |
+
+> Diagrams are in **Mermaid** (renderable text on GitHub and most Markdown viewers).
+
+---
+
+## 1. Overview
+
+Vigía is a **single asyncio process per machine** with no single point of failure (RNF-02). It
+receives earthquakes via **push** (WebSocket EMSC, primary channel) and reconciles them with a
+**low-frequency backup** (USGS polling every 60 s). A *pipeline* normalizes, filters by zone, and
+deduplicates them; new and relevant events trigger an **undismissable desktop alert** (overlay
+window + toast + sound). Critical state is **persisted** to survive restarts.
+
+## 2. Components
+
+| Component | Role | RF |
+|---|---|---|
+| **WSIngestor (EMSC)** | WebSocket connection, 15 s keepalive, backoff reconnection, emits raw messages | RF-01..RF-04 |
+| **RESTReconciler (USGS)** | 60 s polling with persisted cursor; safety net | RF-05, RF-06 |
+| **Normalizer** | Raw→`SeismicEvent`; haversine; severity | RF-07, RF-08, RF-13 |
+| **GeoFilter** | Discards events outside radius or below minimum magnitude | RF-12 |
+| **Deduplicator** | Inter-source heuristic; persisted ids; handles `update` | RF-09..RF-11 |
+| **Notifier (toast)** | Native informational toast (`desktop-notifier`) | RF-14 |
+| **AlertWindow (overlay)** | Topmost Tkinter window, with focus, undismissable | RF-15..RF-19 |
+| **AlertQueue + bridge** | Event queue; asyncio↔Tk bridge | RF-20 |
+| **Sound** | Audio by severity | RF-17 |
+| **StateStore** | Atomic JSON persistence (ids, cursor) | RF-06, RF-10 |
+| **Settings** | Loads/validates `config.toml` (pydantic) | RF-24 |
+| **Supervisor** | Orchestrates asyncio tasks; restarts on failure | RNF-03, RNF-04 |
+| **Autostart** | systemd / LaunchAgent / scheduled task | RF-22, RF-23 |
+| **CLI (`vigia-eew`)** | Startup, `--simulate`, autostart | RF-21, RF-26 |
+
+## 3. Architecture diagram — data flow
+
+```mermaid
+flowchart LR
+    subgraph Fuentes["External sources"]
+        EMSC["EMSC WebSocket<br/>(primary push)"]
+        USGS["USGS FDSN REST<br/>(60 s backup)"]
+    end
+
+    subgraph Ingesta["Ingestion layer (asyncio)"]
+        WS["WSIngestor<br/>keepalive + reconnection"]
+        REST["RESTReconciler<br/>persisted cursor"]
+    end
+
+    Q(["raw_queue<br/>(asyncio.Queue)"])
+
+    subgraph Pipeline["Pipeline"]
+        NORM["Normalizer<br/>haversine + severity"]
+        FILT["GeoFilter<br/>radius + min magnitude"]
+        DEDUP["Deduplicator<br/>heuristic + ids"]
+    end
+
+    subgraph Estado["Persistence"]
+        STATE[("StateStore<br/>state.json<br/>ids + cursor")]
+    end
+
+    subgraph Notif["Notification"]
+        AQ(["AlertQueue<br/>+ Tk bridge"])
+        TOAST["Notifier (toast)"]
+        WIN["AlertWindow<br/>topmost · sound · ACKNOWLEDGED"]
+    end
+
+    CFG["Settings<br/>config.toml"]
+
+    EMSC -->|create/update| WS
+    USGS -->|GeoJSON| REST
+    WS --> Q
+    REST --> Q
+    Q --> NORM --> FILT --> DEDUP
+    DEDUP -->|new + relevant| AQ
+    AQ --> TOAST
+    AQ --> WIN
+    DEDUP <-->|alerted ids| STATE
+    REST <-->|cursor| STATE
+    CFG -.config.-> NORM
+    CFG -.config.-> FILT
+    CFG -.config.-> DEDUP
+    CFG -.config.-> WIN
+```
+
+## 4. Sequence diagram — from EMSC to the alert window
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant EMSC as EMSC WebSocket
+    participant WS as WSIngestor
+    participant PIPE as Pipeline (normalize/filter/dedup)
+    participant ST as StateStore
+    participant UI as AlertQueue + AlertWindow
+    participant USR as User
+
+    EMSC->>WS: message {action:"create", data: Feature}
+    WS->>PIPE: raw message (raw_queue)
+    PIPE->>PIPE: normalizes (haversine, severity)
+    PIPE->>PIPE: filters (radius, min magnitude)
+    PIPE->>ST: id already alerted? duplicate?
+    ST-->>PIPE: no (new event)
+    PIPE->>ST: registers alerted id
+    PIPE->>UI: enqueues SeismicEvent
+    UI->>UI: shows topmost window + takes focus + sound
+    UI-->>USR: MAGNITUDE, place, distance, depth, local time, source
+    Note over EMSC,UI: If an {action:"update"} arrives for the same unid,<br/>the displayed event is updated WITHOUT a new alert (RF-11)
+    USR->>UI: presses "ACKNOWLEDGED"
+    UI->>ST: registers acknowledgment (audit)
+    UI->>UI: closes window and shows the next one in the queue
+```
+
+## 5. State diagram — WebSocket connection
+
+```mermaid
+stateDiagram-v2
+    [*] --> Connecting
+    Connecting --> Connected: handshake OK
+    Connecting --> Backoff: connection error
+
+    Connected --> Ping: every ~15 s
+    Ping --> Connected: pong received
+    Ping --> Down: ping_timeout (no pong)
+
+    Connected --> Receiving: incoming message
+    Receiving --> Connected: processed
+
+    Connected --> Down: socket close/EOF
+    Down --> Backoff: schedule retry
+
+    Backoff --> Connecting: exponential wait + jitter (max backoff_max_s)
+
+    Connected --> Closing: SIGINT/SIGTERM
+    Closing --> [*]
+```
+
+## 6. What happens if… (resilience scenarios)
+
+| Scenario | Expected behavior | Mechanism / RF |
+|---|---|---|
+| **The WS goes down** | Close/ping_timeout is detected → `Down` state → exponential `Backoff` with jitter → perpetual reconnection. The process **does not die**. | RF-03, RNF-03; §5 |
+| **The WS silently stops receiving** | The **keepalive (15 s ping)** detects the loss via `ping_timeout` and forces reconnection. | RF-02 |
+| **REST fails (429/5xx/timeout)** | `Retry-After` is honored (429); the cycle is skipped and retried after 60 s; the **cursor is kept**; no abort. | RF-05; Technical Design §8 |
+| **An `update` arrives** | Same `unid` already seen → the displayed/queued event is **updated** (e.g. magnitude) **without** triggering a new alert. | RF-11, CU-3 |
+| **Two sources report the same earthquake** | The heuristic (≤100 km, ≤90 s, ≤0.5 mag) recognizes it as a duplicate → **a single** alert. | RF-09, CU-4 |
+| **The agent restarts with pending alerts** | `StateStore` remembers `alerted_ids` → already-acknowledged ones **are not re-alerted**; `usgs_cursor` avoids reprocessing history. | RF-06, RF-10, CU-10 |
+| **Invalid JSON / unexpected schema** | pydantic validation discards the item and logs it; the flow continues. | RNF-03 |
+| **Total network loss** | Both ingestion paths keep retrying; once the network returns, USGS **reconciles** what was missed during the outage. | RF-05, OBJ-3 |
+| **OS "do not disturb"** | The toast may be silenced, but the **topmost, focused overlay window** guarantees the alert. | RF-15, RF-16, RNF-05 |
+| **UI fails** | Isolated from the pipeline (decoupled bridge); ingestion keeps running; showing the alert is retried. | ADR-006 |
+
+## 7. Deployment
+
+Each machine runs its own agent (no SPOF). OS-specific autostart (systemd `--user`, LaunchAgent,
+scheduled task) keeps the process alive after login.
+
+```mermaid
+flowchart TB
+    subgraph PCs["N independent machines (no single point of failure)"]
+        A["Vigía Agent<br/>(Linux · systemd --user)"]
+        B["Vigía Agent<br/>(Windows · scheduled task)"]
+        C["Vigía Agent<br/>(macOS · LaunchAgent)"]
+    end
+    EMSC["EMSC WS"] --> A & B & C
+    USGS["USGS FDSN"] --> A & B & C
+```
+
+## 8. Future evolution — central relay (not v1)
+
+ADR-008 documents the migration to a **FastAPI relay** that consumes EMSC/USGS once and does
+*fan-out* over WebSocket to many Vigía clients, **reusing the internal contract** (`SeismicEvent`)
+as the payload so as not to break the data model.
+
+```mermaid
+flowchart LR
+    EMSC["EMSC WS"] --> RELAY["FastAPI Relay<br/>(central dedup)"]
+    USGS["USGS FDSN"] --> RELAY
+    RELAY -->|fan-out WS<br/>SeismicEvent| C1["Vigía client 1"]
+    RELAY -->|fan-out WS| C2["Vigía client 2"]
+    RELAY -->|fan-out WS| C3["Vigía client N"]
+```