# arslan-kokane/hydrowise architecture

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

- Interactive diagram: https://gitdiagram.com/arslan-kokane/hydrowise
- Repository: https://github.com/arslan-kokane/hydrowise

## Overview

Hydro-Wise is an irrigation decision-support prototype: its documented workflow checks six-hour rain probability before using sensor conditions to produce a recommendation, which a dashboard can present. The current API implements mock weather, sensor, and decision endpoints; the web client has an API wrapper, while the sampled dashboard excerpt uses local scenarios. ML training, live weather and ESP32 integrations, and pump actuation are roadmap capabilities, not demonstrated runtime subsystems. The README and tree support those future branches, but sampled source does not establish their wiring.

Main entry points: [`services/api/app/routes.py`](https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/routes.py) (API routes), [`services/api/app/mock/data_generator.py`](https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/mock/data_generator.py) (Decision evaluation), [`services/api/app/main.py`](https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/main.py) (FastAPI app), [`ml`](https://github.com/arslan-kokane/hydrowise/tree/main/ml) (ML model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Dashboard"]
  node_web_entry["Web entry<br/>[main.tsx]"]
  node_dashboard["Dashboard UI<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_web_contracts["Web contracts<br/>[contracts.ts]"]
end

subgraph group_api["API service"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_decision["Decision inputs"]
  node_mock_data["Mock data logic<br/>[data_generator.py]"]
  node_weather["Weather snapshot<br/>[data_generator.py]"]
  node_sensors["Sensor readings<br/>[data_generator.py]"]
  node_evaluation["Decision evaluation<br/>[data_generator.py]"]
  node_sensor_contract["Sensor schema"]
  node_weather_contract["Weather schema"]
  node_decision_contract["Decision schema"]
end

subgraph group_future["Planned integrations"]
  node_esp32["ESP32 sensors"]
  node_ml["ML model"]
end

node_farmer(("Field user"))
node_weather_service["Weather API"]
node_pump["Pump relay"]

node_farmer -->|"uses"| node_dashboard
node_web_entry -->|"renders"| node_dashboard
node_api_client -->|"requests"| node_api_app
node_api_app -->|"registers"| node_routes
node_routes -->|"gets snapshot"| node_weather
node_routes -->|"gets readings"| node_sensors
node_routes -->|"gets history"| node_mock_data
node_routes -->|"evaluates"| node_evaluation
node_routes -->|"validates"| node_schemas
node_weather -->|"produces"| node_mock_data
node_sensors -->|"produces"| node_mock_data
node_evaluation -->|"produces"| node_mock_data
node_weather_service -.->|"planned input"| node_weather
node_esp32 -.->|"planned telemetry"| node_routes
node_evaluation -.->|"planned inference"| node_ml
node_ml -.->|"planned result"| node_evaluation
node_pump -.->|"future actuation"| node_evaluation

click node_web_entry "https://github.com/arslan-kokane/hydrowise/blob/main/apps/web/src/main.tsx"
click node_dashboard "https://github.com/arslan-kokane/hydrowise/blob/main/apps/web/src/App.tsx"
click node_api_client "https://github.com/arslan-kokane/hydrowise/blob/main/apps/web/src/api/client.ts"
click node_web_contracts "https://github.com/arslan-kokane/hydrowise/blob/main/apps/web/src/types/contracts.ts"
click node_api_app "https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/main.py"
click node_routes "https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/routes.py"
click node_schemas "https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/models/schemas.py"
click node_mock_data "https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/mock/data_generator.py"
click node_weather "https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/mock/data_generator.py"
click node_sensors "https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/mock/data_generator.py"
click node_evaluation "https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/mock/data_generator.py"
click node_sensor_contract "https://github.com/arslan-kokane/hydrowise/blob/main/packages/contracts/schemas/sensor-reading.schema.json"
click node_weather_contract "https://github.com/arslan-kokane/hydrowise/blob/main/packages/contracts/schemas/weather-snapshot.schema.json"
click node_decision_contract "https://github.com/arslan-kokane/hydrowise/blob/main/packages/contracts/schemas/irrigation-decision.schema.json"
click node_esp32 "https://github.com/arslan-kokane/hydrowise/tree/main/firmware/esp32/src"
click node_ml "https://github.com/arslan-kokane/hydrowise/tree/main/ml"

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_web_entry,node_dashboard,node_api_client,node_web_contracts,node_farmer toneBlue
class node_api_app,node_routes,node_schemas toneAmber
class node_mock_data,node_weather,node_sensors,node_evaluation,node_sensor_contract,node_weather_contract,node_decision_contract,node_weather_service toneMint
class node_esp32,node_ml toneRose
class node_pump toneIndigo
```

## Components

### Dashboard

- [Web entry](https://github.com/arslan-kokane/hydrowise/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [Dashboard UI](https://github.com/arslan-kokane/hydrowise/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [API client](https://github.com/arslan-kokane/hydrowise/blob/main/apps/web/src/api/client.ts): `apps/web/src/api/client.ts`
- [Web contracts](https://github.com/arslan-kokane/hydrowise/blob/main/apps/web/src/types/contracts.ts): `apps/web/src/types/contracts.ts`

### API service

- [FastAPI app](https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/main.py): `services/api/app/main.py`
- [API routes](https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/routes.py): `services/api/app/routes.py`
- [API schemas](https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/models/schemas.py): `services/api/app/models/schemas.py`

### Decision inputs

- [Mock data logic](https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/mock/data_generator.py): `services/api/app/mock/data_generator.py`
- [Weather snapshot](https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/mock/data_generator.py): `services/api/app/mock/data_generator.py`
- [Sensor readings](https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/mock/data_generator.py): `services/api/app/mock/data_generator.py`
- [Decision evaluation](https://github.com/arslan-kokane/hydrowise/blob/main/services/api/app/mock/data_generator.py): `services/api/app/mock/data_generator.py`
- [Sensor schema](https://github.com/arslan-kokane/hydrowise/blob/main/packages/contracts/schemas/sensor-reading.schema.json): `packages/contracts/schemas/sensor-reading.schema.json`
- [Weather schema](https://github.com/arslan-kokane/hydrowise/blob/main/packages/contracts/schemas/weather-snapshot.schema.json): `packages/contracts/schemas/weather-snapshot.schema.json`
- [Decision schema](https://github.com/arslan-kokane/hydrowise/blob/main/packages/contracts/schemas/irrigation-decision.schema.json): `packages/contracts/schemas/irrigation-decision.schema.json`

### Planned integrations

- [ESP32 sensors](https://github.com/arslan-kokane/hydrowise/tree/main/firmware/esp32/src): `firmware/esp32/src`
- [ML model](https://github.com/arslan-kokane/hydrowise/tree/main/ml): `ml`

### Other components

- **Field user**
- **Weather API**
- **Pump relay**

## Connections

- Field user → Dashboard UI: uses
- Web entry → Dashboard UI: renders
- API client → FastAPI app: requests
- FastAPI app → API routes: registers
- API routes → Weather snapshot: gets snapshot
- API routes → Sensor readings: gets readings
- API routes → Mock data logic: gets history
- API routes → Decision evaluation: evaluates
- API routes → API schemas: validates
- Weather snapshot → Mock data logic: produces
- Sensor readings → Mock data logic: produces
- Decision evaluation → Mock data logic: produces
- Weather API → Weather snapshot: planned input
- ESP32 sensors → API routes: planned telemetry
- Decision evaluation → ML model: planned inference
- ML model → Decision evaluation: planned result
- Pump relay → Decision evaluation: future actuation