# asliadarsh/pravah architecture

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

- Interactive diagram: https://gitdiagram.com/asliadarsh/pravah
- Repository: https://github.com/asliadarsh/pravah

## Overview

Pravah is a drilling-intelligence application: engineers inspect a live well against nearby offsets, correlated formations and historical events, then review evidence, alerts and mitigation context before making a decision. The backend seeds published well, report and telemetry data; exposes domain analysis through FastAPI; and stores the resulting corpus and engineer actions. The frontend provides the dashboard and specialist screens. Several engine and page implementations were not excerpted, so their capabilities are included from the README, while uncertain internal call paths are omitted.

Main entry points: [`frontend/src/api/client.ts`](https://github.com/asliadarsh/pravah/blob/main/frontend/src/api/client.ts) (API Client), [`backend/app/routers`](https://github.com/asliadarsh/pravah/tree/main/backend/app/routers) (API Routers), [`backend/app/seed_real.py`](https://github.com/asliadarsh/pravah/blob/main/backend/app/seed_real.py) (Corpus Seeding), [`backend/app/main.py`](https://github.com/asliadarsh/pravah/blob/main/backend/app/main.py) (FastAPI Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Engineer Experience"]
  node_frontend["Web Application<br/>[App.tsx]"]
  node_api_client["API Client<br/>[client.ts]"]
  node_dashboard["Well Dashboard<br/>[Dashboard.tsx]"]
  node_offset_views["Offset Map and Replay<br/>[OffsetMap.tsx]"]
  node_timeline["Event Timeline<br/>[Timeline.tsx]"]
  node_alerts_view["Alert Decisions<br/>[DecisionPanel.tsx]"]
  node_evidence_view["Evidence Viewer<br/>[Documents.tsx]"]
  node_search_view["Knowledge Search<br/>[Search.tsx]"]
  node_telemetry_view["Telemetry and Validation"]
end

subgraph group_api["API and Services"]
  node_api_app["FastAPI Application<br/>[main.py]"]
  node_routers["API Routers"]
  node_services["Composite Services<br/>[services.py]"]
end

subgraph group_intelligence["Well Intelligence"]
  node_risk["Risk and Alerts<br/>[risk.py]"]
  node_relevance["Offset Relevance<br/>[relevance.py]"]
  node_ahp["AHP Weighting<br/>[ahp.py]"]
  node_geo["Geospatial Correlation<br/>[geo.py]"]
  node_anomaly["Telemetry Anomaly Engine<br/>[anomaly.py]"]
  node_backtest["Detector Backtest<br/>[backtest.py]"]
  node_graph["Knowledge Graph<br/>[graph.py]"]
  node_graphrag["Graph Retrieval<br/>[graphrag.py]"]
  node_search["Hybrid Search<br/>[search.py]"]
end

subgraph group_evidence["Evidence and Data"]
  node_ingestion["Document Ingestion<br/>[ingestion.py]"]
  node_event_types["Event Type Registry<br/>[event_types.py]"]
  node_datasources["Published Data Sources<br/>[datasources.py]"]
  node_seed["Corpus Seeding<br/>[seed_real.py]"]
  node_llm["Optional Synthesis<br/>[llm.py]"]
end

subgraph group_state["Persistence"]
  node_database[("Database and ORM<br/>[db.py]")]
  node_models["Domain Records<br/>[models.py]"]
end

node_engineer(("Rig Engineer"))
node_public_data["Published Well Data"]
node_llm_provider(("LLM Provider"))

node_engineer -->|"uses"| node_frontend
node_frontend -->|"uses"| node_api_client
node_api_client -.->|"calls API"| node_api_app
node_api_app -->|"mounts"| node_routers
node_api_app -->|"seeds on startup"| node_seed
node_routers -->|"delegates to"| node_services
node_routers -->|"uses risk logic"| node_risk
node_routers -->|"runs search"| node_search
node_services -->|"uses"| node_relevance
node_services -->|"uses"| node_risk
node_risk -->|"checks hazard types"| node_event_types
node_relevance -.->|"uses weighting"| node_ahp
node_relevance -.->|"uses proximity"| node_geo
node_search -->|"synthesizes retrieved records"| node_llm
node_search -->|"uses graph retrieval"| node_graphrag
node_graphrag -->|"queries graph"| node_graph
node_ingestion -->|"classifies events"| node_event_types
node_seed -->|"loads corpus"| node_datasources
node_seed -->|"ingests reports"| node_ingestion
node_public_data -.->|"provides records"| node_seed
node_llm -.->|"optional synthesis"| node_llm_provider
node_database -->|"creates schema"| node_models
node_routers -->|"reads and writes"| node_database
node_dashboard -.->|"loads well context"| node_api_client
node_offset_views -.->|"loads offsets"| node_api_client
node_timeline -.->|"loads events"| node_api_client
node_alerts_view -.->|"reviews alerts"| node_api_client
node_evidence_view -.->|"loads evidence"| node_api_client
node_search_view -.->|"submits queries"| node_api_client
node_telemetry_view -.->|"loads telemetry"| node_api_client
node_anomaly -.->|"evaluated by"| node_backtest

click node_frontend "https://github.com/asliadarsh/pravah/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/asliadarsh/pravah/blob/main/frontend/src/api/client.ts"
click node_dashboard "https://github.com/asliadarsh/pravah/blob/main/frontend/src/pages/Dashboard.tsx"
click node_offset_views "https://github.com/asliadarsh/pravah/blob/main/frontend/src/pages/OffsetMap.tsx"
click node_timeline "https://github.com/asliadarsh/pravah/blob/main/frontend/src/pages/Timeline.tsx"
click node_alerts_view "https://github.com/asliadarsh/pravah/blob/main/frontend/src/components/DecisionPanel.tsx"
click node_evidence_view "https://github.com/asliadarsh/pravah/blob/main/frontend/src/pages/Documents.tsx"
click node_search_view "https://github.com/asliadarsh/pravah/blob/main/frontend/src/pages/Search.tsx"
click node_telemetry_view "https://github.com/asliadarsh/pravah/blob/main/frontend/src/pages/TelemetryMonitor.tsx"
click node_api_app "https://github.com/asliadarsh/pravah/blob/main/backend/app/main.py"
click node_routers "https://github.com/asliadarsh/pravah/tree/main/backend/app/routers"
click node_services "https://github.com/asliadarsh/pravah/blob/main/backend/app/services.py"
click node_risk "https://github.com/asliadarsh/pravah/blob/main/backend/app/risk.py"
click node_relevance "https://github.com/asliadarsh/pravah/blob/main/backend/app/relevance.py"
click node_ahp "https://github.com/asliadarsh/pravah/blob/main/backend/app/ahp.py"
click node_geo "https://github.com/asliadarsh/pravah/blob/main/backend/app/geo.py"
click node_anomaly "https://github.com/asliadarsh/pravah/blob/main/backend/app/anomaly.py"
click node_backtest "https://github.com/asliadarsh/pravah/blob/main/backend/app/backtest.py"
click node_graph "https://github.com/asliadarsh/pravah/blob/main/backend/app/graph.py"
click node_graphrag "https://github.com/asliadarsh/pravah/blob/main/backend/app/graphrag.py"
click node_search "https://github.com/asliadarsh/pravah/blob/main/backend/app/search.py"
click node_ingestion "https://github.com/asliadarsh/pravah/blob/main/backend/app/ingestion.py"
click node_event_types "https://github.com/asliadarsh/pravah/blob/main/backend/app/event_types.py"
click node_datasources "https://github.com/asliadarsh/pravah/blob/main/backend/app/datasources.py"
click node_seed "https://github.com/asliadarsh/pravah/blob/main/backend/app/seed_real.py"
click node_llm "https://github.com/asliadarsh/pravah/blob/main/backend/app/llm.py"
click node_database "https://github.com/asliadarsh/pravah/blob/main/backend/app/db.py"
click node_models "https://github.com/asliadarsh/pravah/blob/main/backend/app/models.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,node_dashboard,node_offset_views,node_timeline,node_alerts_view,node_evidence_view,node_search_view,node_telemetry_view toneBlue
class node_api_app,node_routers,node_services toneAmber
class node_risk,node_relevance,node_ahp,node_geo,node_anomaly,node_backtest,node_graph,node_graphrag,node_search toneMint
class node_ingestion,node_event_types,node_datasources,node_seed,node_llm toneRose
class node_database,node_models,node_engineer,node_public_data,node_llm_provider toneIndigo
```

## Components

### Engineer Experience

- [Web Application](https://github.com/asliadarsh/pravah/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API Client](https://github.com/asliadarsh/pravah/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Well Dashboard](https://github.com/asliadarsh/pravah/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Offset Map and Replay](https://github.com/asliadarsh/pravah/blob/main/frontend/src/pages/OffsetMap.tsx): `frontend/src/pages/OffsetMap.tsx`
- [Event Timeline](https://github.com/asliadarsh/pravah/blob/main/frontend/src/pages/Timeline.tsx): `frontend/src/pages/Timeline.tsx`
- [Alert Decisions](https://github.com/asliadarsh/pravah/blob/main/frontend/src/components/DecisionPanel.tsx): `frontend/src/components/DecisionPanel.tsx`
- [Evidence Viewer](https://github.com/asliadarsh/pravah/blob/main/frontend/src/pages/Documents.tsx): `frontend/src/pages/Documents.tsx`
- [Knowledge Search](https://github.com/asliadarsh/pravah/blob/main/frontend/src/pages/Search.tsx): `frontend/src/pages/Search.tsx`
- [Telemetry and Validation](https://github.com/asliadarsh/pravah/blob/main/frontend/src/pages/TelemetryMonitor.tsx): `frontend/src/pages/TelemetryMonitor.tsx`

### API and Services

- [FastAPI Application](https://github.com/asliadarsh/pravah/blob/main/backend/app/main.py): `backend/app/main.py`
- [API Routers](https://github.com/asliadarsh/pravah/tree/main/backend/app/routers): `backend/app/routers`
- [Composite Services](https://github.com/asliadarsh/pravah/blob/main/backend/app/services.py): `backend/app/services.py`

### Well Intelligence

- [Risk and Alerts](https://github.com/asliadarsh/pravah/blob/main/backend/app/risk.py): `backend/app/risk.py`
- [Offset Relevance](https://github.com/asliadarsh/pravah/blob/main/backend/app/relevance.py): `backend/app/relevance.py`
- [AHP Weighting](https://github.com/asliadarsh/pravah/blob/main/backend/app/ahp.py): `backend/app/ahp.py`
- [Geospatial Correlation](https://github.com/asliadarsh/pravah/blob/main/backend/app/geo.py): `backend/app/geo.py`
- [Telemetry Anomaly Engine](https://github.com/asliadarsh/pravah/blob/main/backend/app/anomaly.py): `backend/app/anomaly.py`
- [Detector Backtest](https://github.com/asliadarsh/pravah/blob/main/backend/app/backtest.py): `backend/app/backtest.py`
- [Knowledge Graph](https://github.com/asliadarsh/pravah/blob/main/backend/app/graph.py): `backend/app/graph.py`
- [Graph Retrieval](https://github.com/asliadarsh/pravah/blob/main/backend/app/graphrag.py): `backend/app/graphrag.py`
- [Hybrid Search](https://github.com/asliadarsh/pravah/blob/main/backend/app/search.py): `backend/app/search.py`

### Evidence and Data

- [Document Ingestion](https://github.com/asliadarsh/pravah/blob/main/backend/app/ingestion.py): `backend/app/ingestion.py`
- [Event Type Registry](https://github.com/asliadarsh/pravah/blob/main/backend/app/event_types.py): `backend/app/event_types.py`
- [Published Data Sources](https://github.com/asliadarsh/pravah/blob/main/backend/app/datasources.py): `backend/app/datasources.py`
- [Corpus Seeding](https://github.com/asliadarsh/pravah/blob/main/backend/app/seed_real.py): `backend/app/seed_real.py`
- [Optional Synthesis](https://github.com/asliadarsh/pravah/blob/main/backend/app/llm.py): `backend/app/llm.py`

### Persistence

- [Database and ORM](https://github.com/asliadarsh/pravah/blob/main/backend/app/db.py): `backend/app/db.py`
- [Domain Records](https://github.com/asliadarsh/pravah/blob/main/backend/app/models.py): `backend/app/models.py`

### Other components

- **Rig Engineer**
- **Published Well Data**
- **LLM Provider**

## Connections

- Rig Engineer → Web Application: uses (evidence: `README.md`)
- Web Application → API Client: uses (evidence: `frontend/src/App.tsx`)
- API Client → FastAPI Application: calls API
- FastAPI Application → API Routers: mounts (evidence: `backend/app/main.py`)
- FastAPI Application → Corpus Seeding: seeds on startup (evidence: `backend/app/main.py`)
- API Routers → Composite Services: delegates to (evidence: `backend/app/routers/alerts.py`)
- API Routers → Risk and Alerts: uses risk logic (evidence: `backend/app/routers/alerts.py`)
- API Routers → Hybrid Search: runs search (evidence: `backend/app/routers/search.py`)
- Composite Services → Offset Relevance: uses (evidence: `backend/app/services.py`)
- Composite Services → Risk and Alerts: uses (evidence: `backend/app/services.py`)
- Risk and Alerts → Event Type Registry: checks hazard types (evidence: `backend/app/risk.py`)
- Offset Relevance → AHP Weighting: uses weighting
- Offset Relevance → Geospatial Correlation: uses proximity
- Hybrid Search → Optional Synthesis: synthesizes retrieved records (evidence: `backend/app/search.py`)
- Hybrid Search → Graph Retrieval: uses graph retrieval (evidence: `backend/app/graphrag.py`)
- Graph Retrieval → Knowledge Graph: queries graph (evidence: `backend/app/graphrag.py`)
- Document Ingestion → Event Type Registry: classifies events (evidence: `backend/app/ingestion.py`)
- Corpus Seeding → Published Data Sources: loads corpus (evidence: `backend/app/seed_real.py`)
- Corpus Seeding → Document Ingestion: ingests reports (evidence: `backend/app/seed_real.py`)
- Published Well Data → Corpus Seeding: provides records
- Optional Synthesis → LLM Provider: optional synthesis (evidence: `backend/app/llm.py`)
- Database and ORM → Domain Records: creates schema (evidence: `backend/app/db.py`)
- API Routers → Database and ORM: reads and writes (evidence: `backend/app/routers/alerts.py`)
- Well Dashboard → API Client: loads well context
- Offset Map and Replay → API Client: loads offsets
- Event Timeline → API Client: loads events
- Alert Decisions → API Client: reviews alerts
- Evidence Viewer → API Client: loads evidence
- Knowledge Search → API Client: submits queries
- Telemetry and Validation → API Client: loads telemetry
- Telemetry Anomaly Engine → Detector Backtest: evaluated by
