The Forecasting Service is a specialized microservice responsible for generating accurate demand predictions for bakery products. It integrates trained ML models with real-time weather and traffic data to provide actionable forecasts for business planning.

Features

Core Functionality

Single Product Forecasting: Generate predictions for individual products
Batch Forecasting: Process multiple products and time periods
Real-time Predictions: On-demand forecasting with external data
Business Rules: Spanish bakery-specific adjustments
Alert System: Automated notifications for demand anomalies

Integration Points

Training Service: Loads trained Prophet models
Data Service: Retrieves weather and traffic data
Notification Service: Sends alerts and reports
Gateway Service: Authentication and request routing

API Endpoints

Forecasts

POST /api/v1/forecasts/single - Generate single forecast
POST /api/v1/forecasts/batch - Generate batch forecasts
GET /api/v1/forecasts/list - List historical forecasts
GET /api/v1/forecasts/alerts - Get forecast alerts
PUT /api/v1/forecasts/alerts/{id}/acknowledge - Acknowledge alert

Predictions

POST /api/v1/predictions/realtime - Real-time prediction
GET /api/v1/predictions/quick/{product} - Quick multi-day forecast

Business Logic

Spanish Bakery Rules

Siesta Impact: Reduced afternoon activity consideration
Weather Adjustments: Rain reduces traffic, extreme temperatures affect product mix
Holiday Handling: Spanish holiday calendar integration
Weekend Patterns: Different demand patterns for weekends

Business Types

Individual Bakery: Single location with direct sales
Central Workshop: Production facility supplying multiple locations

Configuration

Environment Variables

# Database
DATABASE_URL=postgresql+asyncpg://user:pass@host:port/db

# External Services
TRAINING_SERVICE_URL=http://training-service:8000
DATA_SERVICE_URL=http://data-service:8000

# Business Rules
WEEKEND_ADJUSTMENT_FACTOR=0.8
HOLIDAY_ADJUSTMENT_FACTOR=0.5
RAIN_IMPACT_FACTOR=0.7

Performance Settings

MAX_FORECAST_DAYS=30
PREDICTION_CACHE_TTL_HOURS=6
FORECAST_BATCH_SIZE=100

Development

Setup

cd services/forecasting
pip install -r requirements.txt

Testing

pytest tests/ -v --cov=app

Running Locally

uvicorn app.main:app --reload --port 8000

Deployment

Docker

docker build -t forecasting-service .
docker run -p 8000:8000 forecasting-service

Kubernetes

kubectl apply -f infrastructure/kubernetes/base/forecasting-service.yaml

Monitoring

Metrics

forecasts_generated_total - Total forecasts generated
predictions_served_total - Total predictions served
forecast_processing_time_seconds - Processing time histogram
active_models_count - Number of active models

Health Checks

/health - Service health status
/metrics - Prometheus metrics endpoint

Performance

Benchmarks

Single Forecast: < 2 seconds average
Batch Forecasting: 100 products in < 30 seconds
Concurrent Load: 95%+ success rate at 20 concurrent requests

Optimization

Model caching for faster predictions
Feature preparation optimization
Database query optimization
Asynchronous external API calls

Troubleshooting

Common Issues

No Model Found Error
- Ensure training service has models for tenant/product
- Check model training logs in training service
High Prediction Latency
- Monitor model cache hit rate
- Check external service response times
- Review database query performance
Inaccurate Predictions
- Verify external data quality (weather/traffic)
- Check model performance metrics
- Review business rule configurations

Logging

# View service logs
docker logs forecasting-service

# Debug level logging
LOG_LEVEL=DEBUG uvicorn app.main:app

Contributing

Follow the existing code structure and patterns
Add tests for new functionality
Update documentation for API changes
Ensure performance benchmarks are maintained

License

This service is part of the Bakery Forecasting Platform - MIT License