# falexsun/neftekod2026 architecture

> Architecture diagram of the GitHub repository falexsun/neftekod2026, 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/falexsun/neftekod2026
- Repository: https://github.com/falexsun/neftekod2026

## Overview

Q21 Shadow Pipeline is a shadow-mode diesel-sulfur forecasting and operator-advisory system; it does not send setpoints to plant control. The documented workflow runs from plant and laboratory inputs through feature preparation and multi-agent evaluation to forecasts, scenario checks, and operator review. The graph preserves the README’s timeline, anomaly, optimization, notification, monitoring, and model-lifecycle capabilities. Several subsystems are represented from README and tree descriptions rather than inspected implementation, so their links are documented flows, not claims of source-level call tracing.

Main entry points: [`project/src/api/app.py`](https://github.com/falexsun/neftekod2026/blob/main/project/src/api/app.py) (FastAPI gateway), [`project/frontend/src/App.tsx`](https://github.com/falexsun/neftekod2026/blob/main/project/frontend/src/App.tsx) (React operator console), [`project/src/agents/quality/agent.py`](https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/quality/agent.py) (Quality agent), [`project/src/agents/data_quality/agent.py`](https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/data_quality/agent.py) (Data quality agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data and features"]
  node_loaders["Data loaders<br/>[loaders.py]"]
  node_stream["Q21 stream<br/>[q21_stream.py]"]
  node_features["Feature engineering<br/>[features.py]"]
  node_state["Process state<br/>[process_state.py]"]
end

subgraph group_decision["Forecast and decisions"]
  node_dq["Data quality agent<br/>[agent.py]"]
  node_quality["Quality agent<br/>[agent.py]"]
  node_q21["Multi-horizon advisory<br/>[advisory_system.py]"]
  node_anomaly["Anomaly detection<br/>[detector.py]"]
  node_reliability["Reliability agent<br/>[agent.py]"]
  node_surrogate["Surrogate model<br/>[model.py]"]
  node_optimization["Optimization agent<br/>[agent.py]"]
  node_safety["Safety agent<br/>[agent.py]"]
  node_orchestrator["Decision orchestrator<br/>[agent.py]"]
end

subgraph group_runtime["API and runtime"]
  node_gateway["FastAPI gateway<br/>[app.py]"]
  node_runtime_store[("Decision journal<br/>[runtime_store.py]")]
  node_timeline["Timeline events<br/>[tracker.py]"]
  node_websocket["Live broadcaster<br/>[manager.py]"]
  node_telegram["Telegram adapter<br/>[telegram.py]"]
end

subgraph group_operator["Operator console"]
  node_console["React operator console<br/>[App.tsx]"]
  node_shift["Shift and forecast views<br/>[ShiftView.tsx]"]
  node_scenario["What-if scenarios<br/>[ScenarioView.tsx]"]
  node_journal_view["Decision journal view<br/>[JournalView.tsx]"]
  node_ws_hook["Live Q21 hook<br/>[useQ21WebSocket.ts]"]
end

subgraph group_lifecycle["Monitoring and ML"]
  node_monitoring["Prometheus and Grafana"]
  node_trainer["Model training<br/>[models.py]"]
  node_registry["MLflow registry"]
  node_promotion["Champion promotion<br/>[hotswap_manager.py]"]
end

node_operator(("Shift operator"))
node_plant(("Plant telemetry"))
node_lims_pak(("LIMS and PAK"))

node_plant -->|"provides telemetry"| node_loaders
node_lims_pak -->|"provides measurements"| node_loaders
node_loaders -->|"loads and normalizes"| node_features
node_features -->|"builds process state"| node_state
node_state -->|"validates state"| node_dq
node_dq -->|"screens data"| node_quality
node_dq -->|"screens data"| node_reliability
node_quality -->|"provides prediction"| node_orchestrator
node_reliability -->|"provides envelope"| node_optimization
node_surrogate -->|"scores scenarios"| node_optimization
node_optimization -->|"proposes changes"| node_safety
node_safety -->|"checks constraints"| node_orchestrator
node_orchestrator -.->|"serves decisions"| node_gateway
node_quality -.->|"forecasts horizons"| node_q21
node_plant -.->|"streams Q21"| node_stream
node_stream -.->|"feeds live updates"| node_websocket
node_gateway -->|"writes audit"| node_runtime_store
node_gateway -->|"records events"| node_timeline
node_gateway -->|"exports metrics"| node_monitoring
node_gateway -.->|"sends alerts"| node_telegram
node_operator -->|"uses"| node_console
node_console -->|"requests operator data"| node_gateway
node_console -->|"renders shift view"| node_shift
node_console -->|"renders scenarios"| node_scenario
node_console -->|"renders journal"| node_journal_view
node_shift -.->|"uses live feed"| node_ws_hook
node_ws_hook -->|"receives WebSocket feed"| node_websocket
node_gateway -->|"runs advisory"| node_q21
node_quality -->|"supports retraining"| node_trainer
node_trainer -->|"registers models"| node_registry
node_registry -->|"promotes candidate"| node_promotion
node_gateway -.->|"exposes anomaly capability"| node_anomaly

click node_loaders "https://github.com/falexsun/neftekod2026/blob/main/project/src/ingestion/loaders.py"
click node_stream "https://github.com/falexsun/neftekod2026/blob/main/project/src/ingestion/q21_stream.py"
click node_features "https://github.com/falexsun/neftekod2026/blob/main/project/src/feature_service/features.py"
click node_state "https://github.com/falexsun/neftekod2026/blob/main/project/src/shared/schemas/process_state.py"
click node_dq "https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/data_quality/agent.py"
click node_quality "https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/quality/agent.py"
click node_q21 "https://github.com/falexsun/neftekod2026/blob/main/project/src/inference/advisory_system.py"
click node_anomaly "https://github.com/falexsun/neftekod2026/blob/main/project/src/inference/anomaly/detector.py"
click node_reliability "https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/reliability/agent.py"
click node_surrogate "https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/surrogate/model.py"
click node_optimization "https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/optimization/agent.py"
click node_safety "https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/safety/agent.py"
click node_orchestrator "https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/orchestrator/agent.py"
click node_gateway "https://github.com/falexsun/neftekod2026/blob/main/project/src/api/app.py"
click node_runtime_store "https://github.com/falexsun/neftekod2026/blob/main/project/src/api/runtime_store.py"
click node_timeline "https://github.com/falexsun/neftekod2026/blob/main/project/src/api/timeline/tracker.py"
click node_websocket "https://github.com/falexsun/neftekod2026/blob/main/project/src/api/websocket/manager.py"
click node_console "https://github.com/falexsun/neftekod2026/blob/main/project/frontend/src/App.tsx"
click node_shift "https://github.com/falexsun/neftekod2026/blob/main/project/frontend/src/views/ShiftView.tsx"
click node_scenario "https://github.com/falexsun/neftekod2026/blob/main/project/frontend/src/views/ScenarioView.tsx"
click node_journal_view "https://github.com/falexsun/neftekod2026/blob/main/project/frontend/src/views/JournalView.tsx"
click node_ws_hook "https://github.com/falexsun/neftekod2026/blob/main/project/frontend/src/hooks/useQ21WebSocket.ts"
click node_telegram "https://github.com/falexsun/neftekod2026/blob/main/project/src/api/notifications/telegram.py"
click node_monitoring "https://github.com/falexsun/neftekod2026/tree/main/project/src/api"
click node_trainer "https://github.com/falexsun/neftekod2026/blob/main/project/src/training/models.py"
click node_promotion "https://github.com/falexsun/neftekod2026/blob/main/project/src/training/hotswap_manager.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_loaders,node_stream,node_features,node_state toneBlue
class node_dq,node_quality,node_q21,node_anomaly,node_reliability,node_surrogate,node_optimization,node_safety,node_orchestrator toneAmber
class node_gateway,node_runtime_store,node_timeline,node_websocket,node_telegram toneMint
class node_console,node_shift,node_scenario,node_journal_view,node_ws_hook toneRose
class node_monitoring,node_trainer,node_registry,node_promotion,node_operator,node_plant,node_lims_pak toneIndigo
```

## Components

### Data and features

- [Data loaders](https://github.com/falexsun/neftekod2026/blob/main/project/src/ingestion/loaders.py): `project/src/ingestion/loaders.py`
- [Q21 stream](https://github.com/falexsun/neftekod2026/blob/main/project/src/ingestion/q21_stream.py): `project/src/ingestion/q21_stream.py`
- [Feature engineering](https://github.com/falexsun/neftekod2026/blob/main/project/src/feature_service/features.py): `project/src/feature_service/features.py`
- [Process state](https://github.com/falexsun/neftekod2026/blob/main/project/src/shared/schemas/process_state.py): `project/src/shared/schemas/process_state.py`

### Forecast and decisions

- [Data quality agent](https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/data_quality/agent.py): `project/src/agents/data_quality/agent.py`
- [Quality agent](https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/quality/agent.py): `project/src/agents/quality/agent.py`
- [Multi-horizon advisory](https://github.com/falexsun/neftekod2026/blob/main/project/src/inference/advisory_system.py): `project/src/inference/advisory_system.py`
- [Anomaly detection](https://github.com/falexsun/neftekod2026/blob/main/project/src/inference/anomaly/detector.py): `project/src/inference/anomaly/detector.py`
- [Reliability agent](https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/reliability/agent.py): `project/src/agents/reliability/agent.py`
- [Surrogate model](https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/surrogate/model.py): `project/src/agents/surrogate/model.py`
- [Optimization agent](https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/optimization/agent.py): `project/src/agents/optimization/agent.py`
- [Safety agent](https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/safety/agent.py): `project/src/agents/safety/agent.py`
- [Decision orchestrator](https://github.com/falexsun/neftekod2026/blob/main/project/src/agents/orchestrator/agent.py): `project/src/agents/orchestrator/agent.py`

### API and runtime

- [FastAPI gateway](https://github.com/falexsun/neftekod2026/blob/main/project/src/api/app.py): `project/src/api/app.py`
- [Decision journal](https://github.com/falexsun/neftekod2026/blob/main/project/src/api/runtime_store.py): `project/src/api/runtime_store.py`
- [Timeline events](https://github.com/falexsun/neftekod2026/blob/main/project/src/api/timeline/tracker.py): `project/src/api/timeline/tracker.py`
- [Live broadcaster](https://github.com/falexsun/neftekod2026/blob/main/project/src/api/websocket/manager.py): `project/src/api/websocket/manager.py`
- [Telegram adapter](https://github.com/falexsun/neftekod2026/blob/main/project/src/api/notifications/telegram.py): `project/src/api/notifications/telegram.py`

### Operator console

- [React operator console](https://github.com/falexsun/neftekod2026/blob/main/project/frontend/src/App.tsx): `project/frontend/src/App.tsx`
- [Shift and forecast views](https://github.com/falexsun/neftekod2026/blob/main/project/frontend/src/views/ShiftView.tsx): `project/frontend/src/views/ShiftView.tsx`
- [What-if scenarios](https://github.com/falexsun/neftekod2026/blob/main/project/frontend/src/views/ScenarioView.tsx): `project/frontend/src/views/ScenarioView.tsx`
- [Decision journal view](https://github.com/falexsun/neftekod2026/blob/main/project/frontend/src/views/JournalView.tsx): `project/frontend/src/views/JournalView.tsx`
- [Live Q21 hook](https://github.com/falexsun/neftekod2026/blob/main/project/frontend/src/hooks/useQ21WebSocket.ts): `project/frontend/src/hooks/useQ21WebSocket.ts`

### Monitoring and ML

- [Prometheus and Grafana](https://github.com/falexsun/neftekod2026/tree/main/project/src/api): `project/src/api`
- [Model training](https://github.com/falexsun/neftekod2026/blob/main/project/src/training/models.py): `project/src/training/models.py`
- **MLflow registry**
- [Champion promotion](https://github.com/falexsun/neftekod2026/blob/main/project/src/training/hotswap_manager.py): `project/src/training/hotswap_manager.py`

### Other components

- **Shift operator**
- **Plant telemetry**
- **LIMS and PAK**

## Connections

- Plant telemetry → Data loaders: provides telemetry
- LIMS and PAK → Data loaders: provides measurements
- Data loaders → Feature engineering: loads and normalizes
- Feature engineering → Process state: builds process state
- Process state → Data quality agent: validates state (evidence: `project/src/agents/data_quality/agent.py`)
- Data quality agent → Quality agent: screens data
- Data quality agent → Reliability agent: screens data
- Quality agent → Decision orchestrator: provides prediction (evidence: `project/src/agents/orchestrator/agent.py`)
- Reliability agent → Optimization agent: provides envelope
- Surrogate model → Optimization agent: scores scenarios (evidence: `project/src/agents/optimization/agent.py`)
- Optimization agent → Safety agent: proposes changes
- Safety agent → Decision orchestrator: checks constraints (evidence: `project/src/agents/orchestrator/agent.py`)
- Decision orchestrator → FastAPI gateway: serves decisions (evidence: `project/src/api/app.py`)
- Quality agent → Multi-horizon advisory: forecasts horizons
- Plant telemetry → Q21 stream: streams Q21
- Q21 stream → Live broadcaster: feeds live updates
- FastAPI gateway → Decision journal: writes audit (evidence: `project/src/api/app.py`)
- FastAPI gateway → Timeline events: records events
- FastAPI gateway → Prometheus and Grafana: exports metrics (evidence: `project/src/api/app.py`)
- FastAPI gateway → Telegram adapter: sends alerts
- Shift operator → React operator console: uses
- React operator console → FastAPI gateway: requests operator data
- React operator console → Shift and forecast views: renders shift view (evidence: `project/frontend/src/App.tsx`)
- React operator console → What-if scenarios: renders scenarios (evidence: `project/frontend/src/App.tsx`)
- React operator console → Decision journal view: renders journal (evidence: `project/frontend/src/App.tsx`)
- Shift and forecast views → Live Q21 hook: uses live feed
- Live Q21 hook → Live broadcaster: receives WebSocket feed (evidence: `project/frontend/src/hooks/useQ21WebSocket.ts`)
- FastAPI gateway → Multi-horizon advisory: runs advisory (evidence: `project/src/api/app.py`)
- Quality agent → Model training: supports retraining (evidence: `project/src/agents/quality/agent.py`)
- Model training → MLflow registry: registers models
- MLflow registry → Champion promotion: promotes candidate
- FastAPI gateway → Anomaly detection: exposes anomaly capability
