How pavanvish46-tech/petrotwin works
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: main.py API application · twin_service.py Twin service adapter · alerts.py Alerts API · engine.py Recommendation engine
Components 25
Engineer UI
- PetroTwin workspace
frontend/src/App.jsx - API client
frontend/src/api.js
Backend API
- API application
backend/app/main.py - Authentication API
backend/app/api/auth.py - Well data API
backend/app/api/wells.py - Prediction API
backend/app/api/predictions.py - Simulation API
backend/app/api/simulation.py - Optimization API
backend/app/api/optimization.py - Recommendation API
backend/app/api/recommendations.py - Alerts API
backend/app/api/alerts.py - Token security
backend/app/core/security.py
Well Data & Models
- Application database
backend/app/db/session.py - Well history service
backend/app/services/data_service.py - Prediction service
backend/app/services/ml_service.py - Feature engineering
ml/data/processing/feature_engineering.py
Twin & Scenarios
- Twin service adapter
backend/app/services/twin_service.py - Well state
ml/digital_twin/state.py - CSS-SRP twin
ml/digital_twin/twin_engine.py - Scenario simulator
ml/simulation/simulator.py
Optimization & Advice
- Constrained optimizer
ml/optimization/optimizer.py - Recommendation engine
ml/recommendation/engine.py - Strategy labeling
ml/optimization/strategies.py - Recommendation explanation
ml/explainability/recommendation_explainer.py - Alert service
backend/app/services/alert_service.py
Other components
- Engineer
Connections 31
- Engineer → PetroTwin workspace: uses
README.md - PetroTwin workspace → API client: requests via
frontend/src/App.jsx - API client → API application: calls API
- API application → Authentication API: registers
backend/app/main.py - API application → Well data API: registers
backend/app/main.py - API application → Prediction API: registers
backend/app/main.py - API application → Simulation API: registers
backend/app/main.py - API application → Optimization API: registers
backend/app/main.py - API application → Recommendation API: registers
backend/app/main.py - API application → Alerts API: registers
backend/app/main.py - Authentication API → Application database: queries users
backend/app/api/auth.py - Authentication API → Token security: verifies credentials
backend/app/api/auth.py - Well data API → Well history service: serves well data
- Prediction API → Well history service: loads well data
backend/app/api/predictions.py - Prediction API → Prediction service: requests predictions
backend/app/api/predictions.py - Prediction service → Feature engineering: builds features
backend/app/services/ml_service.py - Simulation API → Twin service adapter: requests simulation
- Optimization API → Twin service adapter: requests optimization
backend/app/api/optimization.py - Well history service → Twin service adapter: provides latest state
backend/app/services/twin_service.py - Twin service adapter → Well state: constructs state
backend/app/services/twin_service.py - Twin service adapter → Scenario simulator: runs scenarios
backend/app/services/twin_service.py - Twin service adapter → Recommendation engine: requests recommendations
backend/app/services/twin_service.py - Scenario simulator → CSS-SRP twin: simulates scenario
ml/simulation/simulator.py - Constrained optimizer → CSS-SRP twin: evaluates candidates
ml/optimization/optimizer.py - Recommendation engine → Constrained optimizer: searches scenarios
ml/recommendation/engine.py - Recommendation engine → Strategy labeling: labels results
ml/recommendation/engine.py - Recommendation engine → Recommendation explanation: explains selection
ml/recommendation/engine.py - Alerts API → Well history service: reads well data
backend/app/api/alerts.py - Alerts API → Prediction service: requests risk predictions
backend/app/api/alerts.py - Alerts API → Twin service adapter: requests twin state
backend/app/api/alerts.py - Alerts API → Alert service: delegates alert logic
backend/app/api/alerts.py