# pallavi-a11y/ertmac-nwis architecture

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

- Interactive diagram: https://gitdiagram.com/pallavi-a11y/ertmac-nwis
- Repository: https://github.com/pallavi-a11y/ertmac-nwis

## Overview

eRTMAC-NWIS turns uploaded scanned drilling reports into a searchable, structured corpus, then exposes dashboard, review, map, risk and grounded-chat workflows. The documented ingestion stages run from PDF rasterization through two-pass VLM extraction, figure detection, table reconstruction and persistence. README evidence supports the broad pipeline and capabilities; sampled source confirms the DrillMind route/retrieval flow and correction persistence, but several router and parser implementations were not sampled, so their internal wiring is shown only where documented.

Main entry points: [`ertmac-nwis/src/api/client.js`](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/api/client.js) (HTTP client), [`ertmac-nwis/src/App.jsx`](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/App.jsx) (Web app), [`backend/src/database.py`](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/database.py) (Structured corpus), [`backend/src/unified_parser.py`](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/unified_parser.py) (VLM extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_webapp["Web app<br/>[App.jsx]"]
  node_upload_ui["Upload<br/>[Upload.jsx]"]
  node_corpus_ui["Corpus review<br/>[Corpus.jsx]"]
  node_dashboard_ui["Dashboard<br/>[Dashboard.jsx]"]
  node_map_ui["Well map<br/>[MapVisualise.jsx]"]
  node_risk_ui["Risk monitor<br/>[RiskMonitor.jsx]"]
  node_chat_ui["DrillMind chat<br/>[DrillMind.jsx]"]
  node_http_client["HTTP client<br/>[client.js]"]
end

subgraph group_api["API workflows"]
  node_upload_api["Upload API<br/>[upload.py]"]
  node_corpus_api["Corpus API<br/>[corpus.py]"]
  node_review_api["Review API<br/>[review.py]"]
  node_dashboard_api["Dashboard API<br/>[dashboard.py]"]
  node_map_api["Wells API<br/>[wells_map.py]"]
  node_risk_api["Risk API<br/>[risk.py]"]
  node_chat_api["Chat API<br/>[drillmind.py]"]
end

subgraph group_ingestion["Ingestion pipeline"]
  node_pdf_pages["PDF rasterizer<br/>[pdf_processor.py]"]
  node_extractor["VLM extraction<br/>[unified_parser.py]"]
  node_figures["Figure detector"]
  node_tables["Table reconstruction<br/>[table_parser.py]"]
end

subgraph group_intelligence["Search and risk"]
  node_rag["Grounded chat<br/>[rag_engine.py]"]
  node_hazard_monitor["Hazard proximity<br/>[hazard_monitor.py]"]
end

subgraph group_storage["Corpus storage"]
  node_vector_store[("Vector index<br/>[vector_store.py]")]
  node_sqlite[("Structured corpus<br/>[database.py]")]
end

node_engineer(("Engineer"))
node_ollama{{"Local Ollama"}}

node_engineer -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_upload_ui
node_webapp -->|"routes to"| node_corpus_ui
node_webapp -->|"routes to"| node_dashboard_ui
node_webapp -->|"routes to"| node_map_ui
node_webapp -->|"routes to"| node_risk_ui
node_webapp -->|"routes to"| node_chat_ui
node_upload_ui -->|"submits PDF"| node_http_client
node_corpus_ui -->|"requests records"| node_http_client
node_dashboard_ui -->|"requests summary"| node_http_client
node_map_ui -->|"requests wells"| node_http_client
node_risk_ui -->|"checks risk"| node_http_client
node_chat_ui -->|"sends question"| node_http_client
node_http_client -->|"HTTP requests"| node_upload_api
node_http_client -->|"HTTP requests"| node_corpus_api
node_http_client -->|"HTTP requests"| node_dashboard_api
node_http_client -->|"HTTP requests"| node_map_api
node_http_client -->|"HTTP requests"| node_risk_api
node_http_client -->|"HTTP requests"| node_chat_api
node_upload_api -->|"starts ingestion"| node_pdf_pages
node_pdf_pages -->|"provides page images"| node_extractor
node_extractor -->|"requests extraction"| node_ollama
node_extractor -->|"detects figures"| node_figures
node_extractor -->|"stores extracted data"| node_sqlite
node_extractor -->|"indexes page text"| node_vector_store
node_corpus_api -->|"reads corpus"| node_sqlite
node_review_api -->|"reads and saves corrections"| node_sqlite
node_review_api -->|"formats page tables"| node_tables
node_dashboard_api -->|"reads totals"| node_sqlite
node_map_api -->|"reads well locations"| node_sqlite
node_risk_api -->|"checks proximity"| node_hazard_monitor
node_hazard_monitor -->|"queries hazards"| node_sqlite
node_chat_api -->|"asks question"| node_rag
node_rag -->|"retrieves passages"| node_vector_store
node_rag -->|"looks up well names"| node_sqlite
node_rag -->|"generates grounded answer"| node_ollama
node_chat_ui -.->|"loads file choices"| node_corpus_api

click node_webapp "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/App.jsx"
click node_upload_ui "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/pages/Upload.jsx"
click node_corpus_ui "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/pages/Corpus.jsx"
click node_dashboard_ui "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/pages/Dashboard.jsx"
click node_map_ui "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/pages/MapVisualise.jsx"
click node_risk_ui "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/pages/RiskMonitor.jsx"
click node_chat_ui "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/pages/DrillMind.jsx"
click node_http_client "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/api/client.js"
click node_upload_api "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/upload.py"
click node_corpus_api "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/corpus.py"
click node_review_api "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/review.py"
click node_dashboard_api "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/dashboard.py"
click node_map_api "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/wells_map.py"
click node_risk_api "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/risk.py"
click node_chat_api "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/drillmind.py"
click node_pdf_pages "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/pdf_processor.py"
click node_extractor "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/unified_parser.py"
click node_figures "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/figure_extractor.py"
click node_tables "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/table_parser.py"
click node_rag "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/rag_engine.py"
click node_hazard_monitor "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/hazard_monitor.py"
click node_vector_store "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/vector_store.py"
click node_sqlite "https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/database.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_webapp,node_upload_ui,node_corpus_ui,node_dashboard_ui,node_map_ui,node_risk_ui,node_chat_ui,node_http_client toneBlue
class node_upload_api,node_corpus_api,node_review_api,node_dashboard_api,node_map_api,node_risk_api,node_chat_api toneAmber
class node_pdf_pages,node_extractor,node_figures,node_tables toneMint
class node_rag,node_hazard_monitor toneRose
class node_vector_store,node_sqlite,node_engineer,node_ollama toneIndigo
```

## Components

### User interface

- [Web app](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/App.jsx): `ertmac-nwis/src/App.jsx`
- [Upload](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/pages/Upload.jsx): `ertmac-nwis/src/pages/Upload.jsx`
- [Corpus review](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/pages/Corpus.jsx): `ertmac-nwis/src/pages/Corpus.jsx`
- [Dashboard](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/pages/Dashboard.jsx): `ertmac-nwis/src/pages/Dashboard.jsx`
- [Well map](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/pages/MapVisualise.jsx): `ertmac-nwis/src/pages/MapVisualise.jsx`
- [Risk monitor](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/pages/RiskMonitor.jsx): `ertmac-nwis/src/pages/RiskMonitor.jsx`
- [DrillMind chat](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/pages/DrillMind.jsx): `ertmac-nwis/src/pages/DrillMind.jsx`
- [HTTP client](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/ertmac-nwis/src/api/client.js): `ertmac-nwis/src/api/client.js`

### API workflows

- [Upload API](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/upload.py): `backend/routers/upload.py`
- [Corpus API](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/corpus.py): `backend/routers/corpus.py`
- [Review API](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/review.py): `backend/routers/review.py`
- [Dashboard API](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/dashboard.py): `backend/routers/dashboard.py`
- [Wells API](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/wells_map.py): `backend/routers/wells_map.py`
- [Risk API](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/risk.py): `backend/routers/risk.py`
- [Chat API](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/routers/drillmind.py): `backend/routers/drillmind.py`

### Ingestion pipeline

- [PDF rasterizer](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/pdf_processor.py): `backend/src/pdf_processor.py`
- [VLM extraction](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/unified_parser.py): `backend/src/unified_parser.py`
- [Figure detector](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/figure_extractor.py): `backend/src/figure_extractor.py`
- [Table reconstruction](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/table_parser.py): `backend/src/table_parser.py`

### Search and risk

- [Grounded chat](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/rag_engine.py): `backend/src/rag_engine.py`
- [Hazard proximity](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/hazard_monitor.py): `backend/src/hazard_monitor.py`

### Corpus storage

- [Vector index](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/vector_store.py): `backend/src/vector_store.py`
- [Structured corpus](https://github.com/pallavi-a11y/ertmac-nwis/blob/main/backend/src/database.py): `backend/src/database.py`

### Other components

- **Engineer**
- **Local Ollama**

## Connections

- Engineer → Web app: uses
- Web app → Upload: routes to
- Web app → Corpus review: routes to
- Web app → Dashboard: routes to
- Web app → Well map: routes to
- Web app → Risk monitor: routes to
- Web app → DrillMind chat: routes to
- Upload → HTTP client: submits PDF
- Corpus review → HTTP client: requests records
- Dashboard → HTTP client: requests summary
- Well map → HTTP client: requests wells
- Risk monitor → HTTP client: checks risk
- DrillMind chat → HTTP client: sends question
- HTTP client → Upload API: HTTP requests
- HTTP client → Corpus API: HTTP requests
- HTTP client → Dashboard API: HTTP requests
- HTTP client → Wells API: HTTP requests
- HTTP client → Risk API: HTTP requests
- HTTP client → Chat API: HTTP requests
- Upload API → PDF rasterizer: starts ingestion
- PDF rasterizer → VLM extraction: provides page images
- VLM extraction → Local Ollama: requests extraction
- VLM extraction → Figure detector: detects figures
- VLM extraction → Structured corpus: stores extracted data
- VLM extraction → Vector index: indexes page text
- Corpus API → Structured corpus: reads corpus
- Review API → Structured corpus: reads and saves corrections
- Review API → Table reconstruction: formats page tables
- Dashboard API → Structured corpus: reads totals
- Wells API → Structured corpus: reads well locations
- Risk API → Hazard proximity: checks proximity
- Hazard proximity → Structured corpus: queries hazards
- Chat API → Grounded chat: asks question
- Grounded chat → Vector index: retrieves passages
- Grounded chat → Structured corpus: looks up well names
- Grounded chat → Local Ollama: generates grounded answer
- DrillMind chat → Corpus API: loads file choices