# DigitalTwin - Reliability Block Diagram (be-rbd) API Documentation

This document maps all the API endpoints, router controllers, database models, and external service bindings inside the `be-rbd` (Reliability Block Diagram) microservice. It is a FastAPI-based backend engine managing fleet RBD layouts, simulation workflows via Temporal SDK clients, and Airflow pipeline scheduling handlers.

---

## 📊 Summary of Services

| Service / Module | Purpose | Endpoints Count | Primary Database Tables |
| :--- | :--- | :---: | :--- |
| **Simulation** (`simulation`) | Start, run, and query calculations/plots of Monte Carlo RBD simulation runs. | 15 | `rbd_tr_aeros_simulation`, `rbd_tr_aeros_simulation_calc_result`, `rbd_tr_aeros_simulation_plot_result` |
| **Project File** (`project`) | Import, reset, and configure `.aro` (Aeros RBD) binary layout projects and overhauls. | 7 | `rbd_ms_aeros_project` |
| **Equipment Config** (`equipment`) | Manage equipment tag catalogs, save defaults, and read OREDA parameters limits. | 4 | `rbd_ms_aeros_equipment`, `rbd_ms_equipment_custom_input` |
| **Dashboard Model** (`dashboard_model`) | Query and configure system parameters settings and dashboard constants. | 3 | `rbd_ms_master_data` |
| **EAF Contribution** (`contribution`) | Retrieve system energy availability contribution scores. | 1 | `rbd_ms_eaf_contribution` |
| **Airflow Pipelines** (`airflow`) | Cron-like endpoints used by Airflow pipelines to compute EAF degradation scores in batches. | 1 | `rbd_ms_aeros_equipment`, `rbd_tr_aeros_simulation` |

---

## 🛡️ Microservice Architecture & Middlewares

### 1. Embedded Static File Server
To support real-time schematics viewing, `be-rbd` hosts a direct static files mount on `/model` inside `src/main.py`. This exposes static diagram images mapped out inside the project directory structure under `/images`.

### 2. Temporal Simulation Workflows
Computationally heavy Monte Carlo simulation runs are dispatched asynchronously to an external Temporal Workflow execution queue. The server queries execution states, timeouts, and steps dynamically.

### 3. Dual Databases Connection Pools
Similar to other components in the ecosystem, database sessions inside `be-rbd` leverage Python ContextVars to scope transactions strictly per request context:
* `db` session: RBD specific workspace PostgreSQL database (`default`).
* `aeros_db` session: Master asset management connection pool.

---

## 🛠️ Complete API Endpoints Catalog

```mermaid
graph TD
    FE[Web Front-End App] -->|JWTBearer token| G[be-rbd Gateway Router]
    G -->|Run Simulations| SIM[Simulation Service]
    G -->|Project Files| PROJ[Project Service]
    G -->|Custom Specs| EQ[Equipment Service]
    G -->|System Limits| DB[Dashboard Model Service]
    SIM -->|Asynchronous Worker| TMP[Temporal Workflow Queue]
    AF[Apache Airflow Pipelines] -->|No Auth| AIR[Airflow Worker Router]
```

### 1. ⏱️ Simulations Service (`simulation`)
Prefix: `/aeros/simulation` — Controls starting simulations (default vs. yearly/offset runs), plotting timeline curves, formulation rankings, and downloading detailed performance spreadsheet files.

| Service | Endpoint | Method | Type | DB Tables Touched | Called By | LOC | Protect? (Y/N) | Dependencies |
| :--- | :--- | :---: | :--- | :--- | :--- | :---: | :---: | :--- |
| **Simulation** | `/aeros/simulation` | `GET` | CRUD | `rbd_tr_aeros_simulation` | Frontend | ~10 | **Y** | JWTBearer, pagination models |
| **Simulation** | `/aeros/simulation/{simulation_id}` | `GET` | CRUD | `rbd_tr_aeros_simulation` | Frontend | ~9 | **Y** | JWTBearer |
| **Simulation** | `/aeros/simulation/run` | `POST` | Integration | `rbd_tr_aeros_simulation`, `rbd_ms_aeros_project` | Frontend | ~34 | **Y** | Temporal Client start workflow |
| **Simulation** | `/aeros/simulation/run/yearly` | `POST` | Integration | `rbd_tr_aeros_simulation`, `oh_ms_overhaul` | Frontend | ~106 | **Y** | Temporal Client, temporal offsets |
| **Simulation** | `/aeros/simulation/result/calc/{simulation_id}` | `GET` | Algorithm | `rbd_tr_aeros_simulation_calc_result` | Frontend | ~17 | **Y** | Schematic filtration controls |
| **Simulation** | `/aeros/simulation/result/calc/{simulation_id}/plant` | `GET` | Algorithm | `rbd_tr_aeros_simulation_calc_result` | Frontend | ~15 | **Y** | Fleet metrics parser |
| **Simulation** | `/aeros/simulation/result/plot/{simulation_id}` | `GET` | Algorithm | `rbd_tr_aeros_simulation_plot_result` | Frontend | ~15 | **Y** | Hourly plot charts |
| **Simulation** | `/aeros/simulation/result/plot/{simulation_id}/{node_id}` | `GET` | Algorithm | `rbd_tr_aeros_simulation_plot_result` | Frontend | ~17 | **Y** | Component-specific plot charts |
| **Simulation** | `/aeros/simulation/result/ranking/{simulation_id}` | `GET` | Algorithm | `rbd_tr_aeros_simulation_calc_result` | Frontend | ~15 | **Y** | Rank order calculators |
| **Simulation** | `/aeros/simulation/result/critical/{simulation_id}`| `GET` | Algorithm | `rbd_tr_aeros_simulation_plot_result` | Frontend | ~76 | **Y** | Out-of-service timeline maps |
| **Simulation** | `/aeros/simulation/report/{simulation_id}` | `GET` | CRUD / Int | `rbd_tr_aeros_simulation_calc_result` | Frontend | ~76 | **Y** | Excel export stream (`xlsxwriter`) |
| **Simulation** | `/aeros/simulation/forecast/eaf` | `GET` | Integration | `rbd_tr_aeros_simulation`, `rbd_ms_master_data` | Frontend | ~83 | **Y** | Temporal Client trigger, EAF timeline |
| **Simulation** | `/aeros/simulation/custom_parameters` | `GET` | CRUD | `rbd_tr_aeros_simulation_calc_result` | Frontend | ~17 | **Y** | JWTBearer |
| **Simulation** | `/aeros/simulation/metrics/{simulation_id}` | `GET` | Algorithm | `rbd_tr_aeros_simulation` | Frontend | ~12 | **Y** | Plant indicators calculators |
| **Simulation** | `/aeros/simulation/ahm_metrics` | `POST` | Algorithm | `rbd_tr_aeros_simulation_calc_result` | Frontend | ~26 | **Y** | Baseline delta comparison calculations |

---

### 2. 📁 Project Service (`project`)
Prefix: `/aeros/project` — Manages binary `.aro` schematic layouts, resets, metadata, and overhaul tasks mapping.

| Service | Endpoint | Method | Type | DB Tables Touched | Called By | LOC | Protect? (Y/N) | Dependencies |
| :--- | :--- | :---: | :--- | :--- | :--- | :---: | :---: | :--- |
| **Project** | `/aeros/project` | `POST` | CRUD | `rbd_ms_aeros_project` | Admin / Frontend | ~22 | **Y** | Form UploadFile parser, Admin role |
| **Project** | `/aeros/project/download` | `GET` | Integration | `rbd_ms_aeros_project` | Admin / Frontend | ~43 | **Y** | Outbound httpx proxy downloader |
| **Project** | `/aeros/project/metadata` | `GET` | CRUD | `rbd_ms_aeros_project` | Frontend | ~6 | **Y** | JWTBearer |
| **Project** | `/aeros/project/reset` | `GET` | CRUD | `rbd_ms_aeros_project` | Admin / Frontend | ~9 | **Y** | Project cleanup scripts |
| **Project** | `/aeros/project/overhaul_job` | `POST` | CRUD | `rbd_ms_aeros_project` | Frontend | ~13 | **Y** | JWTBearer |
| **Project** | `/aeros/project/update/{overhaul_job_id}` | `POST` | CRUD | `rbd_ms_aeros_project` | Frontend | ~9 | **Y** | JWTBearer |
| **Project** | `/aeros/project/delete/{overhaul_job_id}` | `POST` | CRUD | `rbd_ms_aeros_project` | Frontend | ~8 | **Y** | JWTBearer |

---

### 3. 🔩 Equipment Config Service (`equipment`)
Prefix: `/aeros/equipment` — Manages equipment data definitions and oreda parameter limit catalogs.

| Service | Endpoint | Method | Type | DB Tables Touched | Called By | LOC | Protect? (Y/N) | Dependencies |
| :--- | :--- | :---: | :--- | :--- | :--- | :---: | :---: | :--- |
| **Equipment** | `/aeros/equipment` | `GET` | CRUD | `rbd_ms_aeros_equipment` | Frontend | ~8 | **Y** | JWTBearer |
| **Equipment** | `/aeros/equipment/save_default` | `GET` | CRUD | `rbd_ms_aeros_equipment` | Admin / Frontend | ~7 | **Y** | Seed data loaders |
| **Equipment** | `/aeros/equipment/parameter-oreda/{location_tag}`| `GET` | CRUD | `rbd_ms_equipment_custom_input` | Frontend | ~17 | **Y** | JWTBearer |
| **Equipment** | `/aeros/equipment/test-asset-batch` | `POST` | Algorithm | `ms_equipment_master`, `rp_non_repairable_results` | Frontend | ~11 | **Y** | Batch array mapper and validator |

---

### 4. 📈 Dashboard Model Service (`dashboard_model`)
Prefix: `/dashboard_model` — Administers overall dashboard master parameters.

| Service | Endpoint | Method | Type | DB Tables Touched | Called By | LOC | Protect? (Y/N) | Dependencies |
| :--- | :--- | :---: | :--- | :--- | :--- | :---: | :---: | :--- |
| **Dashboard** | `/dashboard_model` | `GET` | CRUD | `rbd_ms_master_data` | Frontend | ~12 | **Y** | JWTBearer |
| **Dashboard** | `/dashboard_model/master-data` | `GET` | CRUD | `rbd_ms_master_data` | Frontend | ~12 | **Y** | JWTBearer |
| **Dashboard** | `/dashboard_model/master-data/{md_id}/update`| `POST` | CRUD | `rbd_ms_master_data` | Frontend | ~12 | **Y** | Payload schema validator |

---

### 5. 🥇 EAF Contribution Service (`contribution`)
Prefix: `/aeros/contribution` — Resolves fleet contribution metrics.

| Service | Endpoint | Method | Type | DB Tables Touched | Called By | LOC | Protect? (Y/N) | Dependencies |
| :--- | :--- | :---: | :--- | :--- | :--- | :---: | :---: | :--- |
| **Contribution**| `/aeros/contribution` | `GET` | Algorithm | `rbd_ms_eaf_contribution` | Frontend | ~13 | **Y** | Metric calculations |

---

### 6. 🌪️ Airflow Pipelines Service (`airflow`)
Prefix: `/airflow` — Unprotected service endpoints configured to execute high-weight degradation tasks scheduled via Apache Airflow pipelines in batches.

| Service | Endpoint | Method | Type | DB Tables Touched | Called By | LOC | Protect? (Y/N) | Dependencies |
| :--- | :--- | :---: | :--- | :--- | :--- | :---: | :---: | :--- |
| **Airflow** | `/airflow/calculate_eaf_contribution` | `POST` | Algorithm / Int | `rbd_ms_aeros_equipment`, `rbd_tr_aeros_simulation` | Apache Airflow pipeline scheduler | ~117 | **N** | Batch queue calculations loops, EAF formula parameters |