# douglas-moore-engineering/velaqua-water-intelligence-platform architecture

> Architecture diagram of the GitHub repository douglas-moore-engineering/velaqua-water-intelligence-platform, 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/douglas-moore-engineering/velaqua-water-intelligence-platform
- Repository: https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform

## Overview

Velaqua turns water-network telemetry into validated datasets, leak-risk predictions, prioritized incidents, and evidence-backed operational guidance subject to human approval. The documented workflow spans batch and streaming acquisition, Databricks bronze/silver/gold processing, Azure ML training and serving, FastAPI decisioning, and optional RAG and operational integrations. Source excerpts confirm several transformations and service behaviors; broader links follow the README’s architecture where code was not sampled.

Main entry points: [`services/decision_api/app/main.py`](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/services/decision_api/app/main.py) (Decision API), [`platform/databricks/jobs/bronze_ingest.py`](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/platform/databricks/jobs/bronze_ingest.py) (Bronze ingestion), [`services/rag_service/app/main.py`](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/services/rag_service/app/main.py) (RAG service), [`ml/deployment`](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/tree/main/ml/deployment) (AML endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Telemetry data"]
  node_adf["ADF ingestion"]
  node_eventhub["Event Hub consumer"]
  node_raw[("ADLS raw data")]
  node_bronze["Bronze ingestion<br/>[bronze_ingest.py]"]
  node_quality["Quality validation"]
  node_silver["Silver transforms"]
  node_gold[("Gold dataset<br/>[gold_build.py]")]
end

subgraph group_ml["ML lifecycle"]
  node_training["Model training"]
  node_candidate["Candidate selection"]
  node_aml["AML endpoints"]
  node_scoring["Inference scoring<br/>[score.py]"]
end

subgraph group_decision["Decision services"]
  node_api["Decision API<br/>[main.py]"]
  node_engine["Decision engine<br/>[decision_engine.py]"]
  node_contracts["Shared contracts<br/>[models.py]"]
end

subgraph group_evidence["Evidence and operations"]
  node_rag["RAG service<br/>[main.py]"]
  node_search[("Azure AI Search")]
  node_openai["Azure OpenAI"]
  node_integrations["Field and CMMS workflows<br/>[main.py]"]
  node_monitoring["Monitoring and governance"]
end

node_sensors(("Sensors / SCADA"))
node_operator(("Human operator"))

node_sensors -->|"batch ingest"| node_adf
node_sensors -->|"stream events"| node_eventhub
node_adf -->|"write raw"| node_raw
node_eventhub -->|"write events"| node_raw
node_raw -->|"read telemetry"| node_bronze
node_bronze -->|"validate data"| node_quality
node_bronze -->|"transform data"| node_silver
node_silver -->|"build dataset"| node_gold
node_gold -->|"train from"| node_training
node_training -->|"evaluate candidates"| node_candidate
node_candidate -->|"register candidate"| node_aml
node_aml -->|"serve model"| node_scoring
node_api -->|"request predictions"| node_aml
node_api -->|"compute decision"| node_engine
node_engine -->|"return decision"| node_contracts
node_api -->|"request evidence"| node_rag
node_rag -.->|"retrieve documents"| node_search
node_rag -.->|"synthesize evidence"| node_openai
node_api -->|"request approval"| node_operator
node_operator -->|"record approval"| node_api
node_api -->|"dispatch actions"| node_integrations
node_api -->|"track outcomes"| node_monitoring

click node_adf "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/tree/main/platform/ingestion/adf"
click node_eventhub "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/platform/streaming/eventhub_consumer.py"
click node_bronze "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/platform/databricks/jobs/bronze_ingest.py"
click node_quality "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/platform/databricks/jobs/data_quality_validate.py"
click node_silver "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/platform/databricks/jobs/silver_transform.py"
click node_gold "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/platform/databricks/jobs/gold_build.py"
click node_training "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/ml/training/src/train_model_suite.py"
click node_candidate "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/ml/training/src/select_production_candidate.py"
click node_aml "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/tree/main/ml/deployment"
click node_scoring "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/ml/deployment/score.py"
click node_api "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/services/decision_api/app/main.py"
click node_engine "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/services/decision_api/app/decision_engine.py"
click node_contracts "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/services/shared/models.py"
click node_rag "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/services/rag_service/app/main.py"
click node_integrations "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/services/decision_api/app/main.py"
click node_monitoring "https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/tree/main/governance"

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_adf,node_eventhub,node_raw,node_bronze,node_quality,node_silver,node_gold toneBlue
class node_training,node_candidate,node_aml,node_scoring toneAmber
class node_api,node_engine,node_contracts toneMint
class node_rag,node_search,node_openai,node_integrations,node_monitoring toneRose
class node_sensors,node_operator toneIndigo
```

## Components

### Telemetry data

- [ADF ingestion](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/tree/main/platform/ingestion/adf): `platform/ingestion/adf`
- [Event Hub consumer](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/platform/streaming/eventhub_consumer.py): `platform/streaming/eventhub_consumer.py`
- **ADLS raw data**
- [Bronze ingestion](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/platform/databricks/jobs/bronze_ingest.py): `platform/databricks/jobs/bronze_ingest.py`
- [Quality validation](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/platform/databricks/jobs/data_quality_validate.py): `platform/databricks/jobs/data_quality_validate.py`
- [Silver transforms](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/platform/databricks/jobs/silver_transform.py): `platform/databricks/jobs/silver_transform.py`
- [Gold dataset](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/platform/databricks/jobs/gold_build.py): `platform/databricks/jobs/gold_build.py`

### ML lifecycle

- [Model training](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/ml/training/src/train_model_suite.py): `ml/training/src/train_model_suite.py`
- [Candidate selection](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/ml/training/src/select_production_candidate.py): `ml/training/src/select_production_candidate.py`
- [AML endpoints](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/tree/main/ml/deployment): `ml/deployment`
- [Inference scoring](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/ml/deployment/score.py): `ml/deployment/score.py`

### Decision services

- [Decision API](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/services/decision_api/app/main.py): `services/decision_api/app/main.py`
- [Decision engine](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/services/decision_api/app/decision_engine.py): `services/decision_api/app/decision_engine.py`
- [Shared contracts](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/services/shared/models.py): `services/shared/models.py`

### Evidence and operations

- [RAG service](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/services/rag_service/app/main.py): `services/rag_service/app/main.py`
- **Azure AI Search**
- **Azure OpenAI**
- [Field and CMMS workflows](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/blob/main/services/decision_api/app/main.py): `services/decision_api/app/main.py`
- [Monitoring and governance](https://github.com/douglas-moore-engineering/velaqua-water-intelligence-platform/tree/main/governance): `governance`

### Other components

- **Sensors / SCADA**
- **Human operator**

## Connections

- Sensors / SCADA → ADF ingestion: batch ingest
- Sensors / SCADA → Event Hub consumer: stream events
- ADF ingestion → ADLS raw data: write raw
- Event Hub consumer → ADLS raw data: write events
- ADLS raw data → Bronze ingestion: read telemetry
- Bronze ingestion → Quality validation: validate data
- Bronze ingestion → Silver transforms: transform data
- Silver transforms → Gold dataset: build dataset
- Gold dataset → Model training: train from
- Model training → Candidate selection: evaluate candidates
- Candidate selection → AML endpoints: register candidate
- AML endpoints → Inference scoring: serve model
- Decision API → AML endpoints: request predictions
- Decision API → Decision engine: compute decision
- Decision engine → Shared contracts: return decision
- Decision API → RAG service: request evidence
- RAG service → Azure AI Search: retrieve documents
- RAG service → Azure OpenAI: synthesize evidence
- Decision API → Human operator: request approval
- Human operator → Decision API: record approval
- Decision API → Field and CMMS workflows: dispatch actions
- Decision API → Monitoring and governance: track outcomes