# adiendendra/fishing-backend architecture

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

- Interactive diagram: https://gitdiagram.com/adiendendra/fishing-backend
- Repository: https://github.com/adiendendra/fishing-backend

## Overview

This repository implements a fishing-forecast backend: a browser requests a location and date, receives cached or partial weather data, and asynchronous stages add astronomy, deterministic fishing-activity scoring, and an AI-written explanation. A scheduled job prewarms forecasts through the same cache pipeline. Source excerpts establish these runtime links; the tree also contains a Telegram notifier directory, but provides no source evidence to map its behavior.

Main entry points: [`lambda_functions/weather_activity/handler.py`](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/weather_activity/handler.py) (Activity handler), [`lambda_functions/shared/weather_cache_pipeline.py`](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/weather_cache_pipeline.py) (Cache pipeline), [`lambda_functions/weather_analysis/handler.py`](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/weather_analysis/handler.py) (Analysis handler), [`lambda_functions/weather_handler/handler.py`](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/weather_handler/handler.py) (Request handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Request and scheduling"]
  node_gateway["HTTP API Gateway"]
  node_request_handler["Request handler<br/>[handler.py]"]
  node_prewarm_handler["Prewarm handler<br/>[handler.py]"]
end

subgraph group_forecast["Forecast and cache"]
  node_pipeline["Cache pipeline"]
  node_weather_data["Weather data fetch<br/>[weather_data.py]"]
  node_cache_keys["Cache key helper<br/>[cache_keys.py]"]
  node_cache[("Weather cache")]
end

subgraph group_activity["Fishing activity"]
  node_activity_handler["Activity handler<br/>[handler.py]"]
  node_astronomy["Astronomy calculations<br/>[astronomy.py]"]
  node_fish_scoring["Fishing activity scoring"]
end

subgraph group_analysis["AI analysis"]
  node_analysis_handler["Analysis handler<br/>[handler.py]"]
  node_ai_analysis["Weather narrative<br/>[ai_analysis.py]"]
  node_species_analysis["Species identification<br/>[ai_analysis.py]"]
end

node_angler(("Browser client"))
node_eventbridge(("EventBridge schedule"))
node_open_meteo["Open-Meteo"]
node_gemini["Gemini API"]
node_ssm[("Parameter Store")]

node_angler -->|"requests forecast"| node_gateway
node_gateway -->|"routes request"| node_request_handler
node_eventbridge -->|"triggers schedule"| node_prewarm_handler
node_request_handler -->|"creates key"| node_cache_keys
node_request_handler -->|"reads cache"| node_cache
node_request_handler -->|"builds on miss"| node_pipeline
node_prewarm_handler -->|"prewarms dates"| node_pipeline
node_pipeline -->|"fetches bundle"| node_weather_data
node_weather_data -->|"requests conditions"| node_open_meteo
node_pipeline -->|"creates key"| node_cache_keys
node_pipeline -->|"writes partial data"| node_cache
node_pipeline -->|"invokes asynchronously"| node_activity_handler
node_activity_handler -->|"reads partial data"| node_cache
node_activity_handler -->|"calculates astronomy"| node_astronomy
node_activity_handler -->|"scores conditions"| node_fish_scoring
node_activity_handler -->|"writes activity data"| node_cache
node_activity_handler -->|"invokes asynchronously"| node_analysis_handler
node_analysis_handler -->|"reads activity data"| node_cache
node_analysis_handler -->|"generates narrative"| node_ai_analysis
node_analysis_handler -->|"gets API key"| node_ssm
node_ai_analysis -->|"requests narrative"| node_gemini
node_analysis_handler -->|"writes completed data"| node_cache
node_species_analysis -.->|"identifies from image"| node_gemini

click node_request_handler "https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/weather_handler/handler.py"
click node_prewarm_handler "https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/weather_processor/handler.py"
click node_pipeline "https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/weather_cache_pipeline.py"
click node_weather_data "https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/weather_data.py"
click node_cache_keys "https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/cache_keys.py"
click node_activity_handler "https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/weather_activity/handler.py"
click node_astronomy "https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/astronomy.py"
click node_fish_scoring "https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/fishing_activity.py"
click node_analysis_handler "https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/weather_analysis/handler.py"
click node_ai_analysis "https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/ai_analysis.py"
click node_species_analysis "https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/ai_analysis.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_gateway,node_request_handler,node_prewarm_handler,node_angler toneBlue
class node_pipeline,node_weather_data,node_cache_keys,node_cache,node_ssm toneAmber
class node_activity_handler,node_astronomy,node_fish_scoring,node_gemini toneMint
class node_analysis_handler,node_ai_analysis,node_species_analysis toneRose
class node_eventbridge,node_open_meteo toneIndigo
```

## Components

### Request and scheduling

- **HTTP API Gateway**
- [Request handler](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/weather_handler/handler.py): `lambda_functions/weather_handler/handler.py`
- [Prewarm handler](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/weather_processor/handler.py): `lambda_functions/weather_processor/handler.py`

### Forecast and cache

- [Cache pipeline](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/weather_cache_pipeline.py): `lambda_functions/shared/weather_cache_pipeline.py`
- [Weather data fetch](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/weather_data.py): `lambda_functions/shared/weather_data.py`
- [Cache key helper](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/cache_keys.py): `lambda_functions/shared/cache_keys.py`
- **Weather cache**

### Fishing activity

- [Activity handler](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/weather_activity/handler.py): `lambda_functions/weather_activity/handler.py`
- [Astronomy calculations](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/astronomy.py): `lambda_functions/shared/astronomy.py`
- [Fishing activity scoring](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/fishing_activity.py): `lambda_functions/shared/fishing_activity.py`

### AI analysis

- [Analysis handler](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/weather_analysis/handler.py): `lambda_functions/weather_analysis/handler.py`
- [Weather narrative](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/ai_analysis.py): `lambda_functions/shared/ai_analysis.py`
- [Species identification](https://github.com/adiendendra/fishing-backend/blob/main/lambda_functions/shared/ai_analysis.py): `lambda_functions/shared/ai_analysis.py`

### Other components

- **Browser client**
- **EventBridge schedule**
- **Open-Meteo**
- **Gemini API**
- **Parameter Store**

## Connections

- Browser client → HTTP API Gateway: requests forecast
- HTTP API Gateway → Request handler: routes request
- EventBridge schedule → Prewarm handler: triggers schedule
- Request handler → Cache key helper: creates key
- Request handler → Weather cache: reads cache
- Request handler → Cache pipeline: builds on miss
- Prewarm handler → Cache pipeline: prewarms dates
- Cache pipeline → Weather data fetch: fetches bundle
- Weather data fetch → Open-Meteo: requests conditions
- Cache pipeline → Cache key helper: creates key
- Cache pipeline → Weather cache: writes partial data
- Cache pipeline → Activity handler: invokes asynchronously
- Activity handler → Weather cache: reads partial data
- Activity handler → Astronomy calculations: calculates astronomy
- Activity handler → Fishing activity scoring: scores conditions
- Activity handler → Weather cache: writes activity data
- Activity handler → Analysis handler: invokes asynchronously
- Analysis handler → Weather cache: reads activity data
- Analysis handler → Weather narrative: generates narrative
- Analysis handler → Parameter Store: gets API key
- Weather narrative → Gemini API: requests narrative
- Analysis handler → Weather cache: writes completed data
- Species identification → Gemini API: identifies from image