# shivamkumarmehta64-sketch/metshield-ai architecture

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

- Interactive diagram: https://gitdiagram.com/shivamkumarmehta64-sketch/metshield-ai
- Repository: https://github.com/shivamkumarmehta64-sketch/metshield-ai

## Overview

Metshield AI is a weather-station telemetry quality-management system. Its central workflow accepts station readings, checks them for sensor faults and weather anomalies, and exposes monitoring and maintenance information to operators. The sampled telemetry handler explicitly invokes anomaly processing, persistence, and work-order resolution; the district engine invokes fault checks and fetches live weather. The README documents additional imputation, mobile sensing, audit, and heatwave capabilities, but their internal wiring was not sampled.

Main entry points: [`app/api/telemetry/route.ts`](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/api/telemetry/route.ts) (Telemetry API), [`lib/districtEngine.ts`](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/districtEngine.ts) (District Engine), [`app/api/weather/route.ts`](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/api/weather/route.ts) (Weather API), [`app/mobile/page.tsx`](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/mobile/page.tsx) (Mobile Sensor Node)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Telemetry and QC"]
  node_telemetry["Telemetry API<br/>[route.ts]"]
  node_anomaly["Anomaly Rules<br/>[anomalyLogic.ts]"]
  node_faults["Sensor Fault Checks"]
  node_imputation["Observation Imputation<br/>[anomalyLogic.ts]"]
end

subgraph group_insights["Weather Intelligence"]
  node_district["District Engine<br/>[districtEngine.ts]"]
  node_weather["Weather API<br/>[route.ts]"]
  node_liveweather["Live Weather Service"]
  node_heatwave["Heatwave Assessment<br/>[heatwaveEngine.ts]"]
end

subgraph group_operations["Operator Workflows"]
  node_dashboard["Station Dashboard<br/>[page.tsx]"]
  node_incidents["Incident Review<br/>[page.tsx]"]
  node_analytics["QC Analytics<br/>[page.tsx]"]
  node_audit["Audit Report<br/>[page.tsx]"]
  node_mobile["Mobile Sensor Node<br/>[page.tsx]"]
  node_maintenance["Maintenance Work Orders<br/>[d1Adapter.ts]"]
end

subgraph group_services["Assistant Services"]
  node_copilot["AI Copilot API<br/>[route.ts]"]
  node_tools["AI Tools API<br/>[route.ts]"]
  node_assistant["Assistant API<br/>[route.ts]"]
end

subgraph group_persistence["State and Audit"]
  node_storage[("Telemetry Persistence<br/>[d1Adapter.ts]")]
  node_offline[("Offline Buffer<br/>[offlineStorage.ts]")]
end

node_operator(("Operator"))
node_fieldtech(("Field Technician"))
node_openmeteo["Open-Meteo"]
node_openai["OpenAI"]

node_fieldtech -->|"submits readings"| node_telemetry
node_telemetry -->|"checks telemetry"| node_anomaly
node_telemetry -->|"persists telemetry"| node_storage
node_telemetry -->|"resolves work orders"| node_maintenance
node_district -->|"runs fault checks"| node_faults
node_district -->|"fetches weather"| node_openmeteo
node_weather -->|"requests observations"| node_liveweather
node_weather -.->|"fetches provider data"| node_openmeteo
node_operator -->|"monitors stations"| node_dashboard
node_operator -->|"reviews incidents"| node_incidents
node_operator -->|"checks QC metrics"| node_analytics
node_operator -->|"views audit"| node_audit
node_fieldtech -->|"records field data"| node_mobile
node_mobile -->|"buffers offline"| node_offline
node_operator -->|"asks questions"| node_copilot
node_copilot -.->|"generates replies"| node_openai
node_operator -->|"runs AI tools"| node_tools
node_tools -.->|"generates results"| node_openai
node_operator -->|"asks questions"| node_assistant

click node_telemetry "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/api/telemetry/route.ts"
click node_anomaly "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/anomalyLogic.ts"
click node_faults "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/sensorFaultEngine.ts"
click node_district "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/districtEngine.ts"
click node_weather "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/api/weather/route.ts"
click node_liveweather "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/liveWeatherService.ts"
click node_heatwave "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/heatwaveEngine.ts"
click node_dashboard "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/dashboard/page.tsx"
click node_incidents "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/incidents/page.tsx"
click node_analytics "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/analytics/page.tsx"
click node_audit "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/audit-report/page.tsx"
click node_mobile "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/mobile/page.tsx"
click node_imputation "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/anomalyLogic.ts"
click node_maintenance "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/d1Adapter.ts"
click node_storage "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/d1Adapter.ts"
click node_offline "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/offlineStorage.ts"
click node_copilot "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/api/ai/copilot/route.ts"
click node_tools "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/api/ai/tools/route.ts"
click node_assistant "https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/api/assistant/route.ts"

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_telemetry,node_anomaly,node_faults,node_imputation toneBlue
class node_district,node_weather,node_liveweather,node_heatwave toneAmber
class node_dashboard,node_incidents,node_analytics,node_audit,node_mobile,node_maintenance toneMint
class node_copilot,node_tools,node_assistant toneRose
class node_storage,node_offline,node_operator,node_fieldtech,node_openmeteo,node_openai toneIndigo
```

## Components

### Telemetry and QC

- [Telemetry API](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/api/telemetry/route.ts): `app/api/telemetry/route.ts`
- [Anomaly Rules](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/anomalyLogic.ts): `lib/anomalyLogic.ts`
- [Sensor Fault Checks](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/sensorFaultEngine.ts): `lib/sensorFaultEngine.ts`
- [Observation Imputation](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/anomalyLogic.ts): `lib/anomalyLogic.ts`

### Weather Intelligence

- [District Engine](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/districtEngine.ts): `lib/districtEngine.ts`
- [Weather API](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/api/weather/route.ts): `app/api/weather/route.ts`
- [Live Weather Service](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/liveWeatherService.ts): `lib/liveWeatherService.ts`
- [Heatwave Assessment](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/heatwaveEngine.ts): `lib/heatwaveEngine.ts`

### Operator Workflows

- [Station Dashboard](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/dashboard/page.tsx): `app/dashboard/page.tsx`
- [Incident Review](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/incidents/page.tsx): `app/incidents/page.tsx`
- [QC Analytics](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/analytics/page.tsx): `app/analytics/page.tsx`
- [Audit Report](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/audit-report/page.tsx): `app/audit-report/page.tsx`
- [Mobile Sensor Node](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/mobile/page.tsx): `app/mobile/page.tsx`
- [Maintenance Work Orders](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/d1Adapter.ts): `lib/d1Adapter.ts`

### Assistant Services

- [AI Copilot API](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/api/ai/copilot/route.ts): `app/api/ai/copilot/route.ts`
- [AI Tools API](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/api/ai/tools/route.ts): `app/api/ai/tools/route.ts`
- [Assistant API](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/app/api/assistant/route.ts): `app/api/assistant/route.ts`

### State and Audit

- [Telemetry Persistence](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/d1Adapter.ts): `lib/d1Adapter.ts`
- [Offline Buffer](https://github.com/shivamkumarmehta64-sketch/metshield-ai/blob/main/lib/offlineStorage.ts): `lib/offlineStorage.ts`

### Other components

- **Operator**
- **Field Technician**
- **Open-Meteo**
- **OpenAI**

## Connections

- Field Technician → Telemetry API: submits readings
- Telemetry API → Anomaly Rules: checks telemetry
- Telemetry API → Telemetry Persistence: persists telemetry
- Telemetry API → Maintenance Work Orders: resolves work orders
- District Engine → Sensor Fault Checks: runs fault checks
- District Engine → Open-Meteo: fetches weather
- Weather API → Live Weather Service: requests observations
- Weather API → Open-Meteo: fetches provider data
- Operator → Station Dashboard: monitors stations
- Operator → Incident Review: reviews incidents
- Operator → QC Analytics: checks QC metrics
- Operator → Audit Report: views audit
- Field Technician → Mobile Sensor Node: records field data
- Mobile Sensor Node → Offline Buffer: buffers offline
- Operator → AI Copilot API: asks questions
- AI Copilot API → OpenAI: generates replies
- Operator → AI Tools API: runs AI tools
- AI Tools API → OpenAI: generates results
- Operator → Assistant API: asks questions