PulseCast — UPI Merchant Transaction Volume Forecaster

Predict 30-day daily transaction volume with festival-aware patterns, simulating ₹18,000 annual savings per merchant across 500 test kirana stores.

---

Demo

Dashboard Preview

Screenshots

Hero & Stats	Historical Charts

Forecast	Alerts & Surge Detection

Savings Simulator	Full Dashboard

Demo Video

A full walkthrough video is available at assets/demo_video.mp4.

Try it instantly — the app has a built-in Demo Mode that generates NPCI-calibrated synthetic data. No CSV needed to explore all features.

---

Where to Get CSV Data

PulseCast accepts UPI merchant transaction CSVs. You can use any of these sources:

1. Included Sample CSV (Easiest)

A ready-to-use sample is bundled in the repo:

assets/sample_upi_transactions.csv   (9,717 transactions · 8 months · kirana store)

Format preview:

Transaction Date,Amount,Status,Merchant,Payment Mode,UTR
2025-06-01 09:37:00,59.93,SUCCESS,Kirana Store Demo,UPI,UTR134126396
2025-06-01 20:14:00,90.70,SUCCESS,Kirana Store Demo,UPI,UTR732719211
2025-06-01 17:17:00,137.37,SUCCESS,Kirana Store Demo,UPI,UTR331191390

2. Export from UPI Apps

Download your real transaction history from any UPI app:

App	How to Export
PhonePe	Profile → Transaction History → Download Statement (CSV)
Google Pay	Activity → All Transactions → Export
Paytm	Passbook → Statement → Download
Any UPI app	Look for "Download Statement" or "Export Transactions"

3. Kaggle Datasets

Search for UPI/digital payment datasets on Kaggle:

• UPI Transactions Dataset — search "UPI transactions India"
• Digital Payments India — search "digital payments merchant"
• NPCI UPI Statistics — aggregate monthly volumes (for calibration reference)

4. Generate Your Own

The built-in synthetic generator creates realistic data:

# Via API
curl http://127.0.0.1:8000/api/demo?merchant_type=kirana&history_days=365

# Or just use Demo Mode in the Streamlit dashboard

CSV Format Requirements

The auto-detect parser handles most formats. Minimum required columns:

Column	Required	Aliases Accepted
Date	✅	date, timestamp, txn_date, transaction_date, created_at, payment_date
Amount	✅	amount, value, txn_amount, total, paid, price, debit, credit
Status	Optional	status, txn_status, state, result (filters to SUCCESS only)

Supported delimiters: , \t ; | — auto-detected. Date formats: YYYY-MM-DD, DD-MM-YYYY, DD/MM/YYYY, YYYY-MM-DD HH:MM:SS, and more.

---

Research Foundation

Paper / Source	Key Idea Used	Where Applied
TimesFM (arXiv:2310.10688, ICML 2024)	Zero-shot forecasting via patched-decoder transformer, 200M params	Core forecasting engine (CP3)
Holiday Intervention Analysis (JDMDC 2024)	Binary holiday indicators as exogenous variables; pre/post-holiday modeling	Festival covariate features
Fourier Features (Prophet / N-BEATS)	Cyclical encoding of day-of-week and month-of-year	Seasonal covariates
NPCI UPI Statistics	Real UPI volume/value trends, P2P vs P2M breakdowns	Synthetic data calibration

---

Quick Start

# Clone & setup
git clone https://github.com/sohamukute/PulseCast.git
cd PulseCast
cp .env.example .env
# Edit .env → add CALENDARIFIC_API_KEY (free: https://calendarific.com/signup)

# Create virtual environment
python3 -m venv .venv && source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start the backend
uvicorn backend.main:app --reload &

# Run Streamlit dashboard
PYTHONPATH=$PWD streamlit run frontend/app_v2.py

Open http://localhost:8501 in your browser. The demo mode runs automatically — no setup needed.

---

Architecture

PulseCast/
├── backend/
│   ├── main.py                 # FastAPI entry + CORS
│   ├── config.py               # Pydantic Settings (reads .env)
│   ├── middleware.py            # Request logging & timing
│   ├── routers/                # API endpoints (13 routes)
│   │   ├── upload.py           # CSV upload with auto-detect
│   │   ├── forecast.py         # TimesFM forecast (CP3)
│   │   ├── insights.py         # BI & alerts (CP4)
│   │   ├── demo.py             # Synthetic data demo
│   │   └── festivals.py        # Festival API proxy
│   ├── services/
│   │   ├── csv_parser.py       # Auto-detect CSV format
│   │   ├── forecaster.py       # TimesFM wrapper (CP3)
│   │   ├── festival_api.py     # Calendarific + Nager.Date
│   │   ├── features.py         # Fourier + holiday covariates
│   │   ├── salary_detection.py # Dynamic salary-day detection
│   │   └── intelligence.py     # BI metrics (CP4)
│   └── data/
│       └── synthetic.py        # NPCI-calibrated generator
├── frontend/
│   ├── app_v2.py               # Streamlit dashboard (Soft-Pop theme)
│   ├── theme.py                # Soft-Pop CSS theme system
│   ├── api_client.py           # REST client for backend
│   ├── charts.py               # Plotly visualizations (8 chart types)
│   ├── widgets.py              # Reusable UI components (14 widgets)
│   ├── app.py                  # Legacy dashboard
│   └── components/             # Legacy components
├── tests/                      # 186 unit + 70 E2E tests (256 total)
├── assets/                     # Screenshots, demo video, sample CSV
├── .env.example                # API key template
├── requirements.txt
├── Dockerfile
└── README.md

---

Key Design Decisions

• Zero hardcoded data: Festivals come from live APIs, salary-day spikes are auto-detected
• Dynamic everything: Impact metrics computed from each merchant's actual data
• NPCI-calibrated synthetics: Statistical distributions match real UPI P2M patterns
• Robust fallback chain: Calendarific → Nager.Date → cached last-known
• Soft-Pop theme: Custom CSS theme with indigo/teal/amber palette for clean visual hierarchy

---

API Endpoints

Method	Endpoint	Description
GET	/api/health	Server health & engine status
GET	/api/demo	Generate synthetic merchant data
POST	/api/upload	Upload & parse UPI CSV
POST	/api/forecast	Run TimesFM forecast
POST	/api/insights	Business intelligence metrics
POST	/api/alerts	Predictive alerts engine
POST	/api/pipeline	Full orchestrated pipeline
POST	/api/compare	Multi-merchant comparison
GET	/api/festivals	Festival calendar (live API)
POST	/api/export	Export report (JSON/CSV)
POST	/api/clear-cache	Clear LRU cache

Interactive API docs: http://localhost:8000/docs

---

Tech Stack

Layer	Technology	Why
Forecasting	TimesFM 2.0 (PyTorch)	Zero-shot, no training, ICML 2024
Backend	FastAPI 2.0	Async, auto-docs, CORS
Frontend	Streamlit 1.54	Rapid prototyping, free hosting
Theme	Soft-Pop (tweakcn)	Custom CSS — indigo/teal/amber palette
Charts	Plotly	Interactive, publication-quality
Festival Data	Calendarific + Nager.Date	Dynamic, no hardcoding
Testing	Pytest	256 tests (186 unit + 70 E2E)
Storage	In-memory + LRU cache	Zero-config

---

Testing

# Run all 256 tests
PYTHONPATH=$PWD pytest tests/ -v

# Unit tests only (186)
PYTHONPATH=$PWD pytest tests/ -v -k "not e2e"

# E2E tests only (70) — requires backend running
PYTHONPATH=$PWD pytest tests/ -v -k "e2e"

---

Resume Bullet

Built UPI merchant cash flow forecasting app using TimesFM (ICML 2024), predicting 30-day transaction volume with festival-aware patterns via dynamic holiday intervention analysis, simulating ₹18,000 annual savings per merchant across 500 test kirana stores