# pavanvish46-tech/petrotwin architecture

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

- Interactive diagram: https://gitdiagram.com/pavanvish46-tech/petrotwin
- Repository: https://github.com/pavanvish46-tech/petrotwin

## Overview

PetroTwin AI is a prototype well-to-surface decision-support system for cyclic steam stimulation (CSS) and sucker rod pump (SRP) operations. Engineers sign in, select a well, inspect its state and predictions, run what-if scenarios, and request constrained recommendations with explanations for review; the software does not control equipment. The diagram emphasizes API-to-service ownership and the documented workflow. Several route implementations and ML subsystems are unsampled, so those documented capabilities appear without speculative internal call links.

Main entry points: [`backend/app/main.py`](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/main.py) (API application), [`backend/app/services/twin_service.py`](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/services/twin_service.py) (Twin service adapter), [`backend/app/api/alerts.py`](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/alerts.py) (Alerts API), [`ml/recommendation/engine.py`](https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/recommendation/engine.py) (Recommendation engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Engineer UI"]
  node_frontend["PetroTwin workspace<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["Backend API"]
  node_app_server["API application<br/>[main.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_well_api["Well data API<br/>[wells.py]"]
  node_prediction_api["Prediction API<br/>[predictions.py]"]
  node_simulation_api["Simulation API<br/>[simulation.py]"]
  node_optimization_api["Optimization API<br/>[optimization.py]"]
  node_recommendation_api["Recommendation API<br/>[recommendations.py]"]
  node_alerts_api["Alerts API<br/>[alerts.py]"]
  node_auth_security["Token security<br/>[security.py]"]
end

subgraph group_data["Well Data &amp; Models"]
  node_database[("Application database<br/>[session.py]")]
  node_well_data["Well history service<br/>[data_service.py]"]
  node_ml_service["Prediction service<br/>[ml_service.py]"]
  node_features["Feature engineering"]
end

subgraph group_twin["Twin &amp; Scenarios"]
  node_twin_adapter["Twin service adapter<br/>[twin_service.py]"]
  node_twin_state["Well state<br/>[state.py]"]
  node_twin_engine["CSS-SRP twin<br/>[twin_engine.py]"]
  node_simulator["Scenario simulator<br/>[simulator.py]"]
end

subgraph group_decision["Optimization &amp; Advice"]
  node_optimizer["Constrained optimizer<br/>[optimizer.py]"]
  node_recommender["Recommendation engine<br/>[engine.py]"]
  node_strategies["Strategy labeling<br/>[strategies.py]"]
  node_explainer["Recommendation explanation"]
  node_alerts_service["Alert service<br/>[alert_service.py]"]
end

node_engineer(("Engineer"))

node_engineer -->|"uses"| node_frontend
node_frontend -->|"requests via"| node_api_client
node_api_client -.->|"calls API"| node_app_server
node_app_server -->|"registers"| node_auth_api
node_app_server -->|"registers"| node_well_api
node_app_server -->|"registers"| node_prediction_api
node_app_server -->|"registers"| node_simulation_api
node_app_server -->|"registers"| node_optimization_api
node_app_server -->|"registers"| node_recommendation_api
node_app_server -->|"registers"| node_alerts_api
node_auth_api -->|"queries users"| node_database
node_auth_api -->|"verifies credentials"| node_auth_security
node_well_api -.->|"serves well data"| node_well_data
node_prediction_api -->|"loads well data"| node_well_data
node_prediction_api -->|"requests predictions"| node_ml_service
node_ml_service -->|"builds features"| node_features
node_simulation_api -.->|"requests simulation"| node_twin_adapter
node_optimization_api -->|"requests optimization"| node_twin_adapter
node_well_data -->|"provides latest state"| node_twin_adapter
node_twin_adapter -->|"constructs state"| node_twin_state
node_twin_adapter -->|"runs scenarios"| node_simulator
node_twin_adapter -->|"requests recommendations"| node_recommender
node_simulator -->|"simulates scenario"| node_twin_engine
node_optimizer -->|"evaluates candidates"| node_twin_engine
node_recommender -->|"searches scenarios"| node_optimizer
node_recommender -->|"labels results"| node_strategies
node_recommender -->|"explains selection"| node_explainer
node_alerts_api -->|"reads well data"| node_well_data
node_alerts_api -->|"requests risk predictions"| node_ml_service
node_alerts_api -->|"requests twin state"| node_twin_adapter
node_alerts_api -->|"delegates alert logic"| node_alerts_service

click node_frontend "https://github.com/pavanvish46-tech/petrotwin/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/pavanvish46-tech/petrotwin/blob/main/frontend/src/api.js"
click node_app_server "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/main.py"
click node_auth_api "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/auth.py"
click node_well_api "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/wells.py"
click node_prediction_api "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/predictions.py"
click node_simulation_api "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/simulation.py"
click node_optimization_api "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/optimization.py"
click node_recommendation_api "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/recommendations.py"
click node_alerts_api "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/alerts.py"
click node_auth_security "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/core/security.py"
click node_database "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/db/session.py"
click node_well_data "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/services/data_service.py"
click node_ml_service "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/services/ml_service.py"
click node_features "https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/data/processing/feature_engineering.py"
click node_twin_adapter "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/services/twin_service.py"
click node_twin_state "https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/digital_twin/state.py"
click node_twin_engine "https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/digital_twin/twin_engine.py"
click node_simulator "https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/simulation/simulator.py"
click node_optimizer "https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/optimization/optimizer.py"
click node_recommender "https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/recommendation/engine.py"
click node_strategies "https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/optimization/strategies.py"
click node_explainer "https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/explainability/recommendation_explainer.py"
click node_alerts_service "https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/services/alert_service.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_frontend,node_api_client toneBlue
class node_app_server,node_auth_api,node_well_api,node_prediction_api,node_simulation_api,node_optimization_api,node_recommendation_api,node_alerts_api,node_auth_security toneAmber
class node_database,node_well_data,node_ml_service,node_features toneMint
class node_twin_adapter,node_twin_state,node_twin_engine,node_simulator toneRose
class node_optimizer,node_recommender,node_strategies,node_explainer,node_alerts_service,node_engineer toneIndigo
```

## Components

### Engineer UI

- [PetroTwin workspace](https://github.com/pavanvish46-tech/petrotwin/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/pavanvish46-tech/petrotwin/blob/main/frontend/src/api.js): `frontend/src/api.js`

### Backend API

- [API application](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication API](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Well data API](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/wells.py): `backend/app/api/wells.py`
- [Prediction API](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/predictions.py): `backend/app/api/predictions.py`
- [Simulation API](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/simulation.py): `backend/app/api/simulation.py`
- [Optimization API](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/optimization.py): `backend/app/api/optimization.py`
- [Recommendation API](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/recommendations.py): `backend/app/api/recommendations.py`
- [Alerts API](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/api/alerts.py): `backend/app/api/alerts.py`
- [Token security](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### Well Data & Models

- [Application database](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Well history service](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/services/data_service.py): `backend/app/services/data_service.py`
- [Prediction service](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/services/ml_service.py): `backend/app/services/ml_service.py`
- [Feature engineering](https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/data/processing/feature_engineering.py): `ml/data/processing/feature_engineering.py`

### Twin & Scenarios

- [Twin service adapter](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/services/twin_service.py): `backend/app/services/twin_service.py`
- [Well state](https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/digital_twin/state.py): `ml/digital_twin/state.py`
- [CSS-SRP twin](https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/digital_twin/twin_engine.py): `ml/digital_twin/twin_engine.py`
- [Scenario simulator](https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/simulation/simulator.py): `ml/simulation/simulator.py`

### Optimization & Advice

- [Constrained optimizer](https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/optimization/optimizer.py): `ml/optimization/optimizer.py`
- [Recommendation engine](https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/recommendation/engine.py): `ml/recommendation/engine.py`
- [Strategy labeling](https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/optimization/strategies.py): `ml/optimization/strategies.py`
- [Recommendation explanation](https://github.com/pavanvish46-tech/petrotwin/blob/main/ml/explainability/recommendation_explainer.py): `ml/explainability/recommendation_explainer.py`
- [Alert service](https://github.com/pavanvish46-tech/petrotwin/blob/main/backend/app/services/alert_service.py): `backend/app/services/alert_service.py`

### Other components

- **Engineer**

## Connections

- Engineer → PetroTwin workspace: uses (evidence: `README.md`)
- PetroTwin workspace → API client: requests via (evidence: `frontend/src/App.jsx`)
- API client → API application: calls API
- API application → Authentication API: registers (evidence: `backend/app/main.py`)
- API application → Well data API: registers (evidence: `backend/app/main.py`)
- API application → Prediction API: registers (evidence: `backend/app/main.py`)
- API application → Simulation API: registers (evidence: `backend/app/main.py`)
- API application → Optimization API: registers (evidence: `backend/app/main.py`)
- API application → Recommendation API: registers (evidence: `backend/app/main.py`)
- API application → Alerts API: registers (evidence: `backend/app/main.py`)
- Authentication API → Application database: queries users (evidence: `backend/app/api/auth.py`)
- Authentication API → Token security: verifies credentials (evidence: `backend/app/api/auth.py`)
- Well data API → Well history service: serves well data
- Prediction API → Well history service: loads well data (evidence: `backend/app/api/predictions.py`)
- Prediction API → Prediction service: requests predictions (evidence: `backend/app/api/predictions.py`)
- Prediction service → Feature engineering: builds features (evidence: `backend/app/services/ml_service.py`)
- Simulation API → Twin service adapter: requests simulation
- Optimization API → Twin service adapter: requests optimization (evidence: `backend/app/api/optimization.py`)
- Well history service → Twin service adapter: provides latest state (evidence: `backend/app/services/twin_service.py`)
- Twin service adapter → Well state: constructs state (evidence: `backend/app/services/twin_service.py`)
- Twin service adapter → Scenario simulator: runs scenarios (evidence: `backend/app/services/twin_service.py`)
- Twin service adapter → Recommendation engine: requests recommendations (evidence: `backend/app/services/twin_service.py`)
- Scenario simulator → CSS-SRP twin: simulates scenario (evidence: `ml/simulation/simulator.py`)
- Constrained optimizer → CSS-SRP twin: evaluates candidates (evidence: `ml/optimization/optimizer.py`)
- Recommendation engine → Constrained optimizer: searches scenarios (evidence: `ml/recommendation/engine.py`)
- Recommendation engine → Strategy labeling: labels results (evidence: `ml/recommendation/engine.py`)
- Recommendation engine → Recommendation explanation: explains selection (evidence: `ml/recommendation/engine.py`)
- Alerts API → Well history service: reads well data (evidence: `backend/app/api/alerts.py`)
- Alerts API → Prediction service: requests risk predictions (evidence: `backend/app/api/alerts.py`)
- Alerts API → Twin service adapter: requests twin state (evidence: `backend/app/api/alerts.py`)
- Alerts API → Alert service: delegates alert logic (evidence: `backend/app/api/alerts.py`)