# kspavitra/fishermen-ai architecture

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

## Overview

Fishermen-AI is a mobile-first, voice-oriented fishing advisory app for coastal Karnataka. The main workflow is a fisher’s voice or text query reaching the Flask decision endpoint, which fetches weather and evaluates marine safety before returning a GO/CAUTION/DO NOT GO-style advisory. The README also describes market, seasonal fishing, safety, emergency, trip-management, and offline capabilities. The frontend is represented by its existing index.html path; its implementation was not sampled, so its internal feature wiring is not shown.

Main entry points: [`frontend/index.html`](https://github.com/kspavitra/fishermen-ai/blob/master/frontend/index.html) (Voice and Text App), [`backend/app.py`](https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py) (Decision API), [`backend/weather_service.py`](https://github.com/kspavitra/fishermen-ai/blob/master/backend/weather_service.py) (Weather Service), [`backend/decision_engine.py`](https://github.com/kspavitra/fishermen-ai/blob/master/backend/decision_engine.py) (Marine Decision Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Fisher App"]
  node_app["Voice and Text App<br/>[index.html]"]
end

subgraph group_advisory["Advisory Backend"]
  node_decision_api["Decision API<br/>[app.py]"]
  node_weather_api["Weather and Forecast API<br/>[app.py]"]
  node_weather_service["Weather Service<br/>[weather_service.py]"]
  node_decision_engine["Marine Decision Engine<br/>[decision_engine.py]"]
end

subgraph group_fishing["Fishing Information"]
  node_tide_calendar["Tide and Calendar<br/>[app.py]"]
  node_best_time["Best Fishing Times<br/>[app.py]"]
  node_market["Fish Market Prices<br/>[app.py]"]
  node_fish_guide["Seasonal Fish Guide<br/>[app.py]"]
  node_fish_photo["Fish Photo Identification<br/>[app.py]"]
  node_schemes["Government Schemes<br/>[app.py]"]
end

subgraph group_safety["Safety and Offline"]
  node_emergency["Emergency and Location Sharing<br/>[index.html]"]
  node_trip_tools["Trip History and Reports<br/>[index.html]"]
  node_dashboard_fuel["Dashboard and Fuel Calculator<br/>[index.html]"]
  node_offline["Offline Support<br/>[sw.js]"]
end

node_fisher(("Fisher"))
node_openweather["OpenWeatherMap"]

node_fisher -->|"asks for advice"| node_app
node_app -->|"submits query"| node_decision_api
node_decision_api -->|"fetches weather"| node_weather_service
node_weather_service -->|"requests conditions"| node_openweather
node_weather_service -->|"returns weather"| node_decision_api
node_decision_api -->|"evaluates conditions"| node_decision_engine
node_decision_api -->|"returns advisory"| node_app
node_app -.->|"requests forecasts"| node_weather_api
node_weather_api -->|"gets weather data"| node_weather_service
node_app -.->|"views guidance"| node_tide_calendar
node_app -.->|"views time windows"| node_best_time
node_app -.->|"checks prices"| node_market
node_app -.->|"views predictions"| node_fish_guide
node_app -.->|"identifies catch"| node_fish_photo
node_app -.->|"views schemes"| node_schemes
node_app -.->|"uses emergency tools"| node_emergency
node_app -.->|"manages trips"| node_trip_tools
node_app -.->|"views trip metrics"| node_dashboard_fuel
node_app -.->|"uses cached data"| node_offline

click node_app "https://github.com/kspavitra/fishermen-ai/blob/master/frontend/index.html"
click node_decision_api "https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py"
click node_weather_api "https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py"
click node_weather_service "https://github.com/kspavitra/fishermen-ai/blob/master/backend/weather_service.py"
click node_decision_engine "https://github.com/kspavitra/fishermen-ai/blob/master/backend/decision_engine.py"
click node_tide_calendar "https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py"
click node_best_time "https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py"
click node_market "https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py"
click node_fish_guide "https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py"
click node_fish_photo "https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py"
click node_schemes "https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py"
click node_emergency "https://github.com/kspavitra/fishermen-ai/blob/master/frontend/index.html"
click node_trip_tools "https://github.com/kspavitra/fishermen-ai/blob/master/frontend/index.html"
click node_dashboard_fuel "https://github.com/kspavitra/fishermen-ai/blob/master/frontend/index.html"
click node_offline "https://github.com/kspavitra/fishermen-ai/blob/master/frontend/sw.js"

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_app toneBlue
class node_decision_api,node_weather_api,node_weather_service,node_decision_engine toneAmber
class node_tide_calendar,node_best_time,node_market,node_fish_guide,node_fish_photo,node_schemes toneMint
class node_emergency,node_trip_tools,node_dashboard_fuel,node_offline toneRose
class node_fisher,node_openweather toneIndigo
```

## Components

### Fisher App

- [Voice and Text App](https://github.com/kspavitra/fishermen-ai/blob/master/frontend/index.html): `frontend/index.html`

### Advisory Backend

- [Decision API](https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py): `backend/app.py`
- [Weather and Forecast API](https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py): `backend/app.py`
- [Weather Service](https://github.com/kspavitra/fishermen-ai/blob/master/backend/weather_service.py): `backend/weather_service.py`
- [Marine Decision Engine](https://github.com/kspavitra/fishermen-ai/blob/master/backend/decision_engine.py): `backend/decision_engine.py`

### Fishing Information

- [Tide and Calendar](https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py): `backend/app.py`
- [Best Fishing Times](https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py): `backend/app.py`
- [Fish Market Prices](https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py): `backend/app.py`
- [Seasonal Fish Guide](https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py): `backend/app.py`
- [Fish Photo Identification](https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py): `backend/app.py`
- [Government Schemes](https://github.com/kspavitra/fishermen-ai/blob/master/backend/app.py): `backend/app.py`

### Safety and Offline

- [Emergency and Location Sharing](https://github.com/kspavitra/fishermen-ai/blob/master/frontend/index.html): `frontend/index.html`
- [Trip History and Reports](https://github.com/kspavitra/fishermen-ai/blob/master/frontend/index.html): `frontend/index.html`
- [Dashboard and Fuel Calculator](https://github.com/kspavitra/fishermen-ai/blob/master/frontend/index.html): `frontend/index.html`
- [Offline Support](https://github.com/kspavitra/fishermen-ai/blob/master/frontend/sw.js): `frontend/sw.js`

### Other components

- **Fisher**
- **OpenWeatherMap**

## Connections

- Fisher → Voice and Text App: asks for advice (evidence: `README.md`)
- Voice and Text App → Decision API: submits query (evidence: `README.md`)
- Decision API → Weather Service: fetches weather (evidence: `backend/app.py`)
- Weather Service → OpenWeatherMap: requests conditions (evidence: `backend/weather_service.py`)
- Weather Service → Decision API: returns weather (evidence: `backend/app.py`)
- Decision API → Marine Decision Engine: evaluates conditions (evidence: `backend/app.py`)
- Decision API → Voice and Text App: returns advisory (evidence: `README.md`)
- Voice and Text App → Weather and Forecast API: requests forecasts
- Weather and Forecast API → Weather Service: gets weather data (evidence: `backend/app.py`)
- Voice and Text App → Tide and Calendar: views guidance
- Voice and Text App → Best Fishing Times: views time windows
- Voice and Text App → Fish Market Prices: checks prices
- Voice and Text App → Seasonal Fish Guide: views predictions
- Voice and Text App → Fish Photo Identification: identifies catch
- Voice and Text App → Government Schemes: views schemes
- Voice and Text App → Emergency and Location Sharing: uses emergency tools
- Voice and Text App → Trip History and Reports: manages trips
- Voice and Text App → Dashboard and Fuel Calculator: views trip metrics
- Voice and Text App → Offline Support: uses cached data
