# synapse-codex/weather-forecasting-system architecture

> Architecture diagram of the GitHub repository synapse-codex/weather-forecasting-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/synapse-codex/weather-forecasting-system
- Repository: https://github.com/synapse-codex/weather-forecasting-system

## Overview

1. **Overall shape**
   - This repository is a two-service Python application for weather forecasting at a single location: Bakkhali Beach, West Bengal.
   - The system is split into a **backend prediction API** and a **frontend dashboard**, with shared machine-learning artifacts stored under `backend/models/`.

2. **Backend service boundary**
   - The backend lives in `backend/` and is the core application layer.
   - It exposes a **FastAPI** interface, handles request validation and prediction orchestration, and likely wraps the model inference flow behind REST endpoints.
   - This is the main integration boundary for any client, including the Streamlit frontend.

3. **Frontend service boundary**
   - The frontend lives in `frontend/app.py` and is a **Streamlit** application.
   - Its role is presentation and user interaction: taking forecast inputs from the user, calling the backend, and rendering forecast outputs and charts.
   - It should be treated as a separate UI process rather than part of the API runtime.

4. **Model inference layer**
   - `backend/predict.py` is the inference-focused module.
   - It likely loads the serialized model and transforms inputs into model-ready feature vectors, then returns the 7-output weather prediction described in the README.
   - The presence of `feature_names.pkl` and `target_names.pkl` indicates the model expects a fixed input schema and returns named outputs.

5. **Model artifacts**
   - `backend/models/xgb_weather_model.pkl` is the persisted **XGBoost** model.
   - The two pickle files for feature and target names are part of the model contract, tying the runtime code to the exact training feature set and output labels.
   - These artifacts are central to the architecture because they define the interface between preprocessing, inference, and UI display.

6. **Data acquisition / refresh path**
   - `backend/fetch.py` suggests a separate data ingestion or update step.
   - Based on the README’s “weekly automatic model updates,” this file likely handles retrieving fresh weather data used for retraining or model refresh workflows.
   - This is the only clearly identifiable data-ingestion subsystem in the repo, even though no database is present in the file tree.

7. **Runtime data flow**
   - A user interacts with the Streamlit frontend.
   - The frontend sends prediction parameters to the FastAPI backend.
   - The backend validates the request, loads or uses the persisted model artifacts, generates multi-output predictions, applies any domain constraints described in the README, and returns structured results.
   - The frontend then renders those results as text and charts.

8. **Training vs inference separation**
   - The repository primarily exposes the **inference path** in code, while the training pipeline is mostly represented by saved artifacts rather than training scripts.
   - That means the operational architecture is model-serving oriented: load a pre-trained model, predict, and optionally refresh via a fetch/update process.
   - This separation reduces runtime complexity and keeps the deployed backend lightweight.

9. **External-facing interfaces**
   - The backend is documented as RESTful and Swagger-enabled, which is a significant architectural boundary for consumers and debugging.
   - The frontend does not appear to talk directly to the model; it should be considered a thin client over the API.
   - Any other integrations would most likely be through the backend HTTP layer.

10. **Container and deployment structure**
   - `Dockerfile.backend`, `Dockerfile.frontend`, and `docker-compose.yml` indicate the system is designed to run as two coordinated containers.
   - This implies a deployment topology with isolated runtime environments for API and UI, connected over the Compose network.
   - `runtime.txt` suggests compatibility with managed Python deployment environments as well.

11. **Technology stack that matters architecturally**
   - **Python 3.9** is the runtime base.
   - **FastAPI** drives the backend contract and validation model.
   - **Streamlit** drives the user-facing dashboard.
   - **XGBoost** is the prediction engine, and **Pickle**-serialized artifacts are the model distribution mechanism.

12. **Notable architectural characteristics**
   - The system is optimized for a single forecasting domain and a fixed set of weather outputs, not for generalized multi-tenant use.
   - There is no visible database, message queue, or object store in the tree, so persistence appears to be file-based via model artifacts rather than application state storage.
   - The main architectural concerns are model loading, input/output schema consistency, and service separation between UI and API.

Main entry points: [`backend/predict.py`](https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/predict.py) (Predictor), [`backend/app.py`](https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/app.py) (API app), [`Dockerfile.backend`](https://github.com/synapse-codex/weather-forecasting-system/blob/main/Dockerfile.backend) (API image), [`frontend/app.py`](https://github.com/synapse-codex/weather-forecasting-system/blob/main/frontend/app.py) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_app["API app<br/>[app.py]"]
  node_backend_predict["Predictor<br/>inference module<br/>[predict.py]"]
  node_backend_fetch["Fetcher<br/>data refresh<br/>[fetch.py]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["Dashboard<br/>Streamlit app<br/>[app.py]"]
end

subgraph group_artifacts["Model Artifacts"]
  node_model_file[("XGBoost model<br/>serialized model")]
  node_feature_file["Feature names<br/>schema artifact<br/>[feature_names.pkl]"]
  node_target_file["Target names<br/>schema artifact<br/>[target_names.pkl]"]
end

subgraph group_deploy["Deployment"]
  node_backend_container["API image<br/>container<br/>[Dockerfile.backend]"]
  node_frontend_container["UI image<br/>container"]
  node_compose["Compose stack<br/>orchestration<br/>[docker-compose.yml]"]
  node_runtime["Python runtime<br/>version pin<br/>[runtime.txt]"]
  node_requirements["Dependencies<br/>package spec<br/>[requirements.txt]"]
end

node_repo["Weather system"]
node_readme["Usage guide<br/>documentation<br/>[README.md]"]
node_license["License"]

node_repo -->|"contains"| node_backend_app
node_repo -->|"contains"| node_frontend_app
node_repo -->|"ships"| node_model_file
node_repo -->|"ships"| node_feature_file
node_repo -->|"ships"| node_target_file
node_backend_app -->|"calls"| node_backend_predict
node_backend_predict -->|"loads"| node_model_file
node_backend_predict -->|"reads"| node_feature_file
node_backend_predict -->|"reads"| node_target_file
node_backend_predict -.->|"depends on"| node_backend_fetch
node_frontend_app -->|"requests"| node_backend_app
node_compose -->|"runs"| node_backend_container
node_compose -->|"runs"| node_frontend_container
node_backend_container -->|"packages"| node_backend_app
node_frontend_container -->|"packages"| node_frontend_app
node_backend_container -->|"installs"| node_requirements
node_frontend_container -->|"installs"| node_requirements
node_backend_container -.->|"pins"| node_runtime
node_readme -.->|"documents"| node_backend_app
node_readme -.->|"documents"| node_frontend_app
node_readme -.->|"documents"| node_compose
node_license -.->|"governs"| node_repo

click node_backend_app "https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/app.py"
click node_backend_predict "https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/predict.py"
click node_backend_fetch "https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/fetch.py"
click node_frontend_app "https://github.com/synapse-codex/weather-forecasting-system/blob/main/frontend/app.py"
click node_model_file "https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/models/xgb_weather_model.pkl"
click node_feature_file "https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/models/feature_names.pkl"
click node_target_file "https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/models/target_names.pkl"
click node_backend_container "https://github.com/synapse-codex/weather-forecasting-system/blob/main/Dockerfile.backend"
click node_frontend_container "https://github.com/synapse-codex/weather-forecasting-system/blob/main/Dockerfile.frontend"
click node_compose "https://github.com/synapse-codex/weather-forecasting-system/blob/main/docker-compose.yml"
click node_runtime "https://github.com/synapse-codex/weather-forecasting-system/blob/main/runtime.txt"
click node_requirements "https://github.com/synapse-codex/weather-forecasting-system/blob/main/requirements.txt"
click node_readme "https://github.com/synapse-codex/weather-forecasting-system/blob/main/README.md"
click node_license "https://github.com/synapse-codex/weather-forecasting-system/tree/main/LICENSE"

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_backend_app,node_backend_predict,node_backend_fetch toneBlue
class node_frontend_app toneAmber
class node_model_file,node_feature_file,node_target_file toneMint
class node_backend_container,node_frontend_container,node_compose,node_runtime,node_requirements toneRose
class node_repo,node_readme,node_license toneNeutral
```

## Components

### Backend

API, inference, and data refresh runtime

- [API app](https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/app.py): FastAPI app · HTTP interface and request boundary · `backend/app.py`
- [Predictor](https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/predict.py): inference module · Loads artifacts and produces weather outputs · `backend/predict.py`
- [Fetcher](https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/fetch.py): data refresh · Retrieves fresh data for updates or retraining · `backend/fetch.py`

### Frontend

Streamlit dashboard runtime

- [Dashboard](https://github.com/synapse-codex/weather-forecasting-system/blob/main/frontend/app.py): Streamlit app · User-facing forecasting UI · `frontend/app.py`

### Model Artifacts

Persisted model contract and serialized assets

- [XGBoost model](https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/models/xgb_weather_model.pkl): serialized model · Persisted weather prediction model · `backend/models/xgb_weather_model.pkl`
- [Feature names](https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/models/feature_names.pkl): schema artifact · Expected model input feature contract · `backend/models/feature_names.pkl`
- [Target names](https://github.com/synapse-codex/weather-forecasting-system/blob/main/backend/models/target_names.pkl): schema artifact · Named weather outputs returned by the model · `backend/models/target_names.pkl`

### Deployment

Container and compose packaging

- [API image](https://github.com/synapse-codex/weather-forecasting-system/blob/main/Dockerfile.backend): container · Backend runtime packaging · `Dockerfile.backend`
- [UI image](https://github.com/synapse-codex/weather-forecasting-system/blob/main/Dockerfile.frontend): container · Frontend runtime packaging · `Dockerfile.frontend`
- [Compose stack](https://github.com/synapse-codex/weather-forecasting-system/blob/main/docker-compose.yml): orchestration · Runs backend and frontend together · `docker-compose.yml`
- [Python runtime](https://github.com/synapse-codex/weather-forecasting-system/blob/main/runtime.txt): version pin · Managed Python execution target · `runtime.txt`
- [Dependencies](https://github.com/synapse-codex/weather-forecasting-system/blob/main/requirements.txt): package spec · Shared Python dependencies for both services · `requirements.txt`

### Other components

- **Weather system**: project · Two-service weather forecasting application
- [Usage guide](https://github.com/synapse-codex/weather-forecasting-system/blob/main/README.md): documentation · Explains setup, usage, and workflow · `README.md`
- [License](https://github.com/synapse-codex/weather-forecasting-system/tree/main/LICENSE): license · Project licensing terms · `LICENSE`

## Connections

- Weather system → API app: contains · Core API service
- Weather system → Dashboard: contains · User interface service
- Weather system → XGBoost model: ships · Persisted inference asset
- Weather system → Feature names: ships · Input schema contract
- Weather system → Target names: ships · Output label contract
- API app → Predictor: calls · Routes requests into inference
- Predictor → XGBoost model: loads · Uses persisted model weights
- Predictor → Feature names: reads · Aligns inputs to expected features
- Predictor → Target names: reads · Maps outputs to weather labels
- Predictor → Fetcher: depends on · Refresh path supports model lifecycle
- Dashboard → API app: requests · UI consumes backend API
- Compose stack → API image: runs · Backend service container
- Compose stack → UI image: runs · Frontend service container
- API image → API app: packages · API runtime image
- UI image → Dashboard: packages · UI runtime image
- API image → Dependencies: installs · Backend dependencies
- UI image → Dependencies: installs · Frontend dependencies
- API image → Python runtime: pins · Python version compatibility
- Usage guide → API app: documents · Describes API usage
- Usage guide → Dashboard: documents · Describes dashboard usage
- Usage guide → Compose stack: documents · Describes deployment workflow
- License → Weather system: governs · Repository license terms
