# jnbalaji-jb/rigpulse-telemetry-lab architecture

> Architecture diagram of the GitHub repository jnbalaji-jb/rigpulse-telemetry-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jnbalaji-jb/rigpulse-telemetry-lab
- Repository: https://github.com/jnbalaji-jb/rigpulse-telemetry-lab

## Overview

RigPulse is a local industrial-telemetry reliability lab. Its main workflow is to generate reproducible telemetry (or ingest CSV), validate and persist readings, score them with interpretable detectors, then inspect alerts and evaluate results. Separate analysis branches report distribution drift and compare alerts with synthetic ground truth. The CLI orchestrates batch workflows; a FastAPI read API serves the browser dashboard. The graph reflects implemented capabilities; planned streaming, multivariate ML, and incident management are not runtime components. Relationships are limited to README statements and the sampled source; unsampled implementation details are omitted.

Main entry points: [`src/rigpulse/cli.py`](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/cli.py) (CLI commands), [`src/rigpulse/storage.py`](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/storage.py) (SQLite readings & alerts), [`src/rigpulse/api.py`](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/api.py) (FastAPI read API), [`src/rigpulse/ingest.py`](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/ingest.py) (CSV ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Batch Workflow"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_simulator["Telemetry simulator<br/>[simulate.py]"]
  node_csv_ingest["CSV ingestion<br/>[ingest.py]"]
  node_truth["Synthetic labels<br/>[simulate.py]"]
end

subgraph group_analysis["Reliability Analysis"]
  node_detector["Alert detection<br/>[detection.py]"]
  node_drift["PSI drift report<br/>[drift.py]"]
  node_evaluation["Label evaluation<br/>[evaluation.py]"]
end

subgraph group_serving["Read API &amp; Dashboard"]
  node_api["FastAPI read API<br/>[api.py]"]
  node_dashboard["Telemetry dashboard<br/>[app.js]"]
end

subgraph group_domain["Domain &amp; Persistence"]
  node_validation["Reading validation<br/>[models.py]"]
  node_sqlite[("SQLite readings &amp; alerts<br/>[storage.py]")]
end

node_operator(("Local operator"))
node_browser_user(("Dashboard user"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"generates data"| node_simulator
node_cli -->|"ingests CSV"| node_csv_ingest
node_cli -->|"runs detection"| node_detector
node_cli -->|"requests report"| node_drift
node_cli -->|"evaluates alerts"| node_evaluation
node_cli -->|"reads summary"| node_sqlite
node_cli -->|"starts server"| node_api
node_csv_ingest -->|"parses readings"| node_validation
node_csv_ingest -->|"inserts readings"| node_sqlite
node_detector -->|"reads readings; replaces alerts"| node_sqlite
node_drift -->|"reads readings"| node_sqlite
node_evaluation -->|"reads readings and alerts"| node_sqlite
node_evaluation -->|"compares labels"| node_truth
node_browser_user -->|"views telemetry"| node_dashboard
node_dashboard -->|"fetches API data"| node_api
node_api -->|"queries summaries and series"| node_sqlite
node_api -->|"serves page"| node_dashboard

click node_cli "https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/cli.py"
click node_simulator "https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/simulate.py"
click node_csv_ingest "https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/ingest.py"
click node_validation "https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/models.py"
click node_sqlite "https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/storage.py"
click node_detector "https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/detection.py"
click node_drift "https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/drift.py"
click node_evaluation "https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/evaluation.py"
click node_truth "https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/simulate.py"
click node_api "https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/api.py"
click node_dashboard "https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/web/app.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_simulator,node_csv_ingest,node_truth,node_browser_user toneBlue
class node_detector,node_drift,node_evaluation toneAmber
class node_api,node_dashboard toneMint
class node_validation,node_sqlite toneRose
class node_operator toneIndigo
```

## Components

### Batch Workflow

- [CLI commands](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/cli.py): `src/rigpulse/cli.py`
- [Telemetry simulator](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/simulate.py): `src/rigpulse/simulate.py`
- [CSV ingestion](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/ingest.py): `src/rigpulse/ingest.py`
- [Synthetic labels](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/simulate.py): `src/rigpulse/simulate.py`

### Reliability Analysis

- [Alert detection](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/detection.py): `src/rigpulse/detection.py`
- [PSI drift report](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/drift.py): `src/rigpulse/drift.py`
- [Label evaluation](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/evaluation.py): `src/rigpulse/evaluation.py`

### Read API & Dashboard

- [FastAPI read API](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/api.py): `src/rigpulse/api.py`
- [Telemetry dashboard](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/web/app.js): `src/rigpulse/web/app.js`

### Domain & Persistence

- [Reading validation](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/models.py): `src/rigpulse/models.py`
- [SQLite readings & alerts](https://github.com/jnbalaji-jb/rigpulse-telemetry-lab/blob/main/src/rigpulse/storage.py): `src/rigpulse/storage.py`

### Other components

- **Local operator**
- **Dashboard user**

## Connections

- Local operator → CLI commands: runs commands (evidence: `src/rigpulse/cli.py`)
- CLI commands → Telemetry simulator: generates data (evidence: `src/rigpulse/cli.py`)
- CLI commands → CSV ingestion: ingests CSV (evidence: `src/rigpulse/cli.py`)
- CLI commands → Alert detection: runs detection (evidence: `src/rigpulse/cli.py`)
- CLI commands → PSI drift report: requests report (evidence: `src/rigpulse/cli.py`)
- CLI commands → Label evaluation: evaluates alerts (evidence: `src/rigpulse/cli.py`)
- CLI commands → SQLite readings & alerts: reads summary (evidence: `src/rigpulse/cli.py`)
- CLI commands → FastAPI read API: starts server (evidence: `src/rigpulse/cli.py`)
- CSV ingestion → Reading validation: parses readings (evidence: `src/rigpulse/ingest.py`)
- CSV ingestion → SQLite readings & alerts: inserts readings (evidence: `src/rigpulse/ingest.py`)
- Alert detection → SQLite readings & alerts: reads readings; replaces alerts (evidence: `src/rigpulse/detection.py`)
- PSI drift report → SQLite readings & alerts: reads readings (evidence: `src/rigpulse/drift.py`)
- Label evaluation → SQLite readings & alerts: reads readings and alerts (evidence: `src/rigpulse/evaluation.py`)
- Label evaluation → Synthetic labels: compares labels (evidence: `src/rigpulse/cli.py`)
- Dashboard user → Telemetry dashboard: views telemetry (evidence: `README.md`)
- Telemetry dashboard → FastAPI read API: fetches API data (evidence: `src/rigpulse/web/app.js`)
- FastAPI read API → SQLite readings & alerts: queries summaries and series (evidence: `src/rigpulse/api.py`)
- FastAPI read API → Telemetry dashboard: serves page (evidence: `src/rigpulse/api.py`)