Demand / sales forecasting dashboard
Turn a historical CSV into a forward-looking view: cleaned timeline, forecast line with a rough uncertainty band, and simple error scores on recent history so you can sanity-check before investing in heavier BI or forecasting stacks. Scoped MVP — not a replacement for enterprise demand or FP&A systems.
Commercial-facing shell for forecasting.vahdetlabs.com. Same Streamlit app URL as the reference deployment; engagement and scoping go through Vahdetlabs.
Limitations & scope
- Univariate only — one target series per run; no promo/pricing/holiday regressors.
- Uncertainty bands derive from residual spread around the fit — decision support, not guaranteed intervals.
- Short or messy history pushes the engine toward trend-only Holt–Winters or an explicit naive last-value fallback.
Overview
Problem. Teams often need a readable forward view of a single KPI over time (sales, visits, orders) without standing up a full analytics stack.
Approach. A Streamlit app accepts a CSV with a date column and one numeric series (or uses bundled demo series). It validates input, aligns observations to a chosen calendar frequency, fits exponential smoothing (Holt–Winters with additive trend and optional seasonality when history supports it), and surfaces fit status explicitly when seasonality is disabled or the solver falls back.
Outputs. Interactive Plotly chart (history vs forecast vs residual-based band), MAPE/MAE vs a naive last-value baseline on held-out recent periods (single or rolling windows), rule-based narrative text, and download of forecast table plus JSON summary metadata.
Workflow
Path through the running app (single session):
-
1
Load data
Upload CSV or select a built-in demo series. Automatic detection picks time and value columns from common names (
date,sales,value, etc.). -
2
Configure & run
User sets horizon, holdout / rolling backtest options, and frequency mode (
auto, daily, weekly, monthly). Computation runs only when Run forecast is clicked so results always match one coherent settings snapshot. -
3
Prepare series
pandas-based resampling, duplicate handling, and interpolation strategy with validation flags for gaps and zero-fill cases.
-
4
Forecast & diagnose
statsmodels Holt–Winters where applicable (e.g. weekly seasonal component for daily data only when enough observations exist); otherwise trend-only or naive fallback with visible status.
-
5
Evaluate & export
Backtest MAPE/MAE vs naive baseline; optional rolling averages across splits. Download
forecast.csvandsummary.json; optional server-side artifact path when writable.
Features
CSV & demo paths
Same workflow for uploaded files or packaged sample time series — useful for demos and smoke checks.
Frequency-aware smoothing
Daily / weekly / monthly handling with conservative seasonal activation rules tied to history length.
Backtest vs baseline
Holdout and rolling modes report error metrics against “repeat last value” so improvements are interpretable.
Plotly chart
Historical line, point forecast, and shaded interval derived from residual spread (documented in-app as approximate).
Artifacts
Forecast table and JSON summary including model status, resampling notes, and metric fields suitable for audit or pipelines.
Explicit UX contract
In-app copy explains why compute is button-gated and what each status means — reduces mistaken “live auto-update” assumptions.
Tech stack
- Runtime / UI: Python 3, Streamlit.
- Data: pandas, NumPy — ingestion, validation, resampling, gap reporting.
- Models: statsmodels exponential smoothing (Holt–Winters); naive last-value fallback paths.
- Viz: Plotly (via Streamlit).
- Tests: pytest coverage for forecast helpers, fingerprints, summary export, smoke path on demo CSVs.
Entrypoint: python src/cli.py run → Streamlit runs src/app.py. No separate REST API in this repository.
Deployment / live app
The canonical interactive deployment is the hosted Streamlit instance linked from this shell’s primary CTAs (forecast.vahdetkaratas.com). This HTML shell is static documentation around that app.
Repository layout: application code under src/, demo CSVs under data/, shell sources under shell/, rendered marketing layouts emitted as layout-shell/ and layout-shell-commercial/ by shell/render-shell.mjs.
Limitations (detail)
The hero summary lists non-negotiable scope boundaries. In addition:
- No authentication, multi-user tenancy, or job scheduling — session-scoped Streamlit as documented in-repo.
- Exports are explicit downloads (plus optional local artifact write); there is no separate analytics warehouse integration.
- Model choice is fixed to exponential-smoothing family paths implemented in code — not an AutoML marketplace.
Why this project
Demonstrates a complete thin vertical slice: responsible defaults for time-series prep, transparent model states, evaluation that compares against an understandable baseline, and operator-facing exports — without pretending the forecast is omniscient or production-complete.