# upstairs-aura/drill_rig_backend architecture

> Architecture diagram of the GitHub repository upstairs-aura/drill_rig_backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/upstairs-aura/drill_rig_backend
- Repository: https://github.com/upstairs-aura/drill_rig_backend

## Overview

This is a FastAPI backend for drill-rig predictive maintenance. Sensor feature batches enter through the ingest API and are persisted; asset dashboard endpoints expose current metrics, threshold alerts, health history, and system status. Prediction requests load the latest reading, run available forest-based inference, and record results for history. Separate training scripts build supervised forest, unsupervised isolation-forest, and sequence-based LSTM models. The README is empty, so capability coverage is based on the source index and excerpts; the LSTM trainer is not shown wired into runtime inference.

Main entry points: [`app/database.py`](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/database.py) (DB sessions), [`app/routes/dashboard.py`](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/dashboard.py) (Asset dashboard), [`app/routes/ingest.py`](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/ingest.py) (Sensor ingestion), [`app/ml/features.py`](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/ml/features.py) (Feature conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and dashboard"]
  node_app["FastAPI application<br/>[main.py]"]
  node_ingest["Sensor ingestion<br/>[ingest.py]"]
  node_schemas["Ingest validation<br/>[schemas.py]"]
  node_dashboard["Asset dashboard<br/>[dashboard.py]"]
  node_metrics["Metrics and alerts<br/>[dashboard.py]"]
  node_health["Health and status<br/>[dashboard.py]"]
  node_prediction_api["Prediction endpoints<br/>[dashboard.py]"]
  node_prediction_history["Prediction history<br/>[dashboard.py]"]
end

subgraph group_data["Persistence"]
  node_db_session["DB sessions<br/>[database.py]"]
  node_entities["Maintenance records<br/>[models.py]"]
  node_database[("Relational database")]
end

subgraph group_inference["Inference"]
  node_predict["Model inference<br/>[predict.py]"]
  node_features["Feature conversion<br/>[features.py]"]
end

subgraph group_training["Model training"]
  node_forest_train["Random forest training<br/>[train_forest.py]"]
  node_isolation_train["Isolation forest training<br/>[train_isolation.py]"]
  node_lstm_train["LSTM training<br/>[train_lstm.py]"]
end

node_client(("API client"))

node_client -->|"calls API"| node_app
node_app -->|"mounts router"| node_ingest
node_app -->|"mounts router"| node_dashboard
node_client -->|"submits batch"| node_ingest
node_ingest -->|"validates payload"| node_schemas
node_ingest -->|"creates records"| node_entities
node_ingest -->|"gets session"| node_db_session
node_dashboard -->|"serves metrics"| node_metrics
node_dashboard -->|"serves health"| node_health
node_dashboard -->|"serves predictions"| node_prediction_api
node_dashboard -->|"serves history"| node_prediction_history
node_metrics -->|"queries readings"| node_db_session
node_health -->|"queries readings"| node_db_session
node_prediction_api -->|"loads latest"| node_db_session
node_prediction_api -->|"runs inference"| node_predict
node_prediction_api -->|"saves result"| node_db_session
node_prediction_history -->|"queries results"| node_db_session
node_entities -->|"uses metadata"| node_db_session
node_db_session -.->|"connects sessions"| node_database
node_predict -->|"converts record"| node_features
node_forest_train -->|"loads training data"| node_db_session
node_forest_train -->|"builds features"| node_features
node_isolation_train -->|"loads records"| node_db_session
node_isolation_train -->|"builds features"| node_features
node_lstm_train -->|"loads records"| node_db_session
node_lstm_train -->|"uses feature columns"| node_features

click node_app "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/main.py"
click node_ingest "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/ingest.py"
click node_schemas "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/schemas.py"
click node_dashboard "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/dashboard.py"
click node_metrics "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/dashboard.py"
click node_health "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/dashboard.py"
click node_prediction_api "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/dashboard.py"
click node_prediction_history "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/dashboard.py"
click node_db_session "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/database.py"
click node_entities "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/models.py"
click node_predict "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/ml/predict.py"
click node_features "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/ml/features.py"
click node_forest_train "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/ml/train_forest.py"
click node_isolation_train "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/ml/train_isolation.py"
click node_lstm_train "https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/ml/train_lstm.py"

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_app,node_ingest,node_schemas,node_dashboard,node_metrics,node_health,node_prediction_api,node_prediction_history,node_client toneBlue
class node_db_session,node_entities,node_database toneAmber
class node_predict,node_features toneMint
class node_forest_train,node_isolation_train,node_lstm_train toneRose
```

## Components

### API and dashboard

- [FastAPI application](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/main.py): `app/main.py`
- [Sensor ingestion](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/ingest.py): `app/routes/ingest.py`
- [Ingest validation](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/schemas.py): `app/schemas.py`
- [Asset dashboard](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/dashboard.py): `app/routes/dashboard.py`
- [Metrics and alerts](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/dashboard.py): `app/routes/dashboard.py`
- [Health and status](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/dashboard.py): `app/routes/dashboard.py`
- [Prediction endpoints](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/dashboard.py): `app/routes/dashboard.py`
- [Prediction history](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/routes/dashboard.py): `app/routes/dashboard.py`

### Persistence

- [DB sessions](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/database.py): `app/database.py`
- [Maintenance records](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/models.py): `app/models.py`
- **Relational database**

### Inference

- [Model inference](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/ml/predict.py): `app/ml/predict.py`
- [Feature conversion](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/ml/features.py): `app/ml/features.py`

### Model training

- [Random forest training](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/ml/train_forest.py): `app/ml/train_forest.py`
- [Isolation forest training](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/ml/train_isolation.py): `app/ml/train_isolation.py`
- [LSTM training](https://github.com/upstairs-aura/drill_rig_backend/blob/secondary/app/ml/train_lstm.py): `app/ml/train_lstm.py`

### Other components

- **API client**

## Connections

- API client → FastAPI application: calls API
- FastAPI application → Sensor ingestion: mounts router (evidence: `app/main.py`)
- FastAPI application → Asset dashboard: mounts router (evidence: `app/main.py`)
- API client → Sensor ingestion: submits batch (evidence: `app/routes/ingest.py`)
- Sensor ingestion → Ingest validation: validates payload (evidence: `app/routes/ingest.py`)
- Sensor ingestion → Maintenance records: creates records (evidence: `app/routes/ingest.py`)
- Sensor ingestion → DB sessions: gets session (evidence: `app/routes/ingest.py`)
- Asset dashboard → Metrics and alerts: serves metrics (evidence: `app/routes/dashboard.py`)
- Asset dashboard → Health and status: serves health (evidence: `app/routes/dashboard.py`)
- Asset dashboard → Prediction endpoints: serves predictions (evidence: `app/routes/dashboard.py`)
- Asset dashboard → Prediction history: serves history (evidence: `app/routes/dashboard.py`)
- Metrics and alerts → DB sessions: queries readings (evidence: `app/routes/dashboard.py`)
- Health and status → DB sessions: queries readings (evidence: `app/routes/dashboard.py`)
- Prediction endpoints → DB sessions: loads latest (evidence: `app/routes/dashboard.py`)
- Prediction endpoints → Model inference: runs inference (evidence: `app/routes/dashboard.py`)
- Prediction endpoints → DB sessions: saves result (evidence: `app/routes/dashboard.py`)
- Prediction history → DB sessions: queries results (evidence: `app/routes/dashboard.py`)
- Maintenance records → DB sessions: uses metadata (evidence: `app/models.py`)
- DB sessions → Relational database: connects sessions
- Model inference → Feature conversion: converts record (evidence: `app/ml/predict.py`)
- Random forest training → DB sessions: loads training data (evidence: `app/ml/train_forest.py`)
- Random forest training → Feature conversion: builds features (evidence: `app/ml/train_forest.py`)
- Isolation forest training → DB sessions: loads records (evidence: `app/ml/train_isolation.py`)
- Isolation forest training → Feature conversion: builds features (evidence: `app/ml/train_isolation.py`)
- LSTM training → DB sessions: loads records (evidence: `app/ml/train_lstm.py`)
- LSTM training → Feature conversion: uses feature columns (evidence: `app/ml/train_lstm.py`)
