How synapse-codex/weather-forecasting-system works
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: predict.py Predictor · backend/app.py API app · Dockerfile.backend API image · frontend/app.py Dashboard
Components 15
Backend
API, inference, and data refresh runtime
Model Artifacts
Persisted model contract and serialized assets
- XGBoost model · Persisted weather prediction model
backend/models/xgb_weather_model.pkl - Feature names · Expected model input feature contract
backend/models/feature_names.pkl - Target names · Named weather outputs returned by the model
backend/models/target_names.pkl
Deployment
Container and compose packaging
- API image · Backend runtime packaging
Dockerfile.backend - UI image · Frontend runtime packaging
Dockerfile.frontend - Compose stack · Runs backend and frontend together
docker-compose.yml - Python runtime · Managed Python execution target
runtime.txt - Dependencies · Shared Python dependencies for both services
requirements.txt
Other components
- Weather system · Two-service weather forecasting application
- Usage guide · Explains setup, usage, and workflow
README.md - License · Project licensing terms
LICENSE
Connections 22
- 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