CashClock is a full-stack web application that gives Indian small and medium enterprises (SMEs) real-time visibility into their cash position — and early warning of when they might run out of money. It uses Holt-Winters statistical forecasting and Claude AI to predict cash flow 30 days ahead, detect anomalies in transactions, and surface pre-approved loan offers to businesses at risk of a cash crisis.
The platform serves two types of users: business owners, who see a personalised dashboard of their cash health, forecast, anomalies, and loan options; and bank managers, who see a portfolio-wide view of all SME clients with risk classification, lending pipeline, and approval tools. The AI component is optional — the app falls back to rule-based summaries if no API key is configured, so it runs fully offline.
Hackathon: NatWest Group — Code for Purpose India Hackathon
Problem it solves: Most Indian SMEs lack the financial tooling to anticipate cash shortfalls. CashClock gives them the same forecasting capability that large enterprises pay enterprise software for — at zero cost.
All features listed below are implemented and functional in the current codebase.
- 30-day cash flow forecast — three confidence paths (likely / optimistic / pessimistic) using Holt-Winters Exponential Smoothing
- No-Cash Zone detection — automatically identifies future dates when projected balance drops below ₹15,000
- Balance tracker — week-over-week trend with percentage change
- Forecast minimum — shows the lowest projected balance and the exact date it occurs
- Daily cash calendar — colour-coded calendar (green / yellow / red) showing each day's cash health
- Anomaly feed — unusual transactions flagged with severity (warning / high / critical), probable cause, and a suggested action
- What-if scenario builder — model a revenue change (±50%) or a one-off cash injection, with live chart update showing impact vs baseline
- AI Ask Box (UI present — not yet functional; planned for a future release)
- PDF report download — multi-page formal business report including forecast chart, anomaly summary, and health score
- In-app loan application — business owners can apply for a pre-approved loan directly from the dashboard
- Portfolio overview — total clients, at-risk count, pre-approved count, and accepted-offer rate as KPI cards
- Risk distribution panel — healthy / watch / urgent / declining breakdown with counts and colour coding
- Industry distribution pie chart — breakdown of portfolio across SME sectors
- Health score histogram — distribution of runway scores (0–100) across all businesses
- Loan pipeline funnel — tracks offer sent → applied → approved → accepted
- Forecasted dip timeline — which businesses will hit a cash crisis and when
- Business list with search and filter — search by name, filter by industry and risk level
- Bulk loan offer dispatch — send pre-approved offers to all at-risk businesses with one click
- Per-business detail view — manager can drill into any business, see its full forecast, and manually approve a loan
- Holt-Winters ETS forecasting — triple exponential smoothing with weekly aggregation and day-of-week redistribution
- Rolling z-score anomaly detection — severity classification relative to each business's own baseline, not a fixed threshold
- Runway score (0–100) — composite score combining balance coverage, trend direction, volatility, and dip severity
- Dynamic per-business thresholds — calibrated from each business's own 365-day transaction history
- Claude AI integration — plain-English summaries via
claude-haiku-4-5(free-text Q&A not yet functional) - Loan risk scoring — three tiers (low / medium / high) that determine interest rate and loan size
Backend
| Category | Technology |
|---|---|
| Language | Python 3.10+ |
| Web Framework | FastAPI + Uvicorn |
| Forecasting | statsmodels (Holt-Winters Exponential Smoothing) |
| Data Processing | pandas, numpy |
| AI / LLM | Anthropic Claude API (claude-haiku-4-5) — optional |
| PDF Generation | ReportLab |
| Database | SQLite (Python built-in sqlite3) |
| Config | python-dotenv |
Frontend
| Category | Technology |
|---|---|
| Language | JavaScript (ES2022) |
| Framework | React 18 |
| Build Tool | Vite 5 |
| Styling | Tailwind CSS 3 |
| Charts | Recharts 2 |
| HTTP Client | Axios |
| Icons | Lucide React |
Infrastructure
| Category | Detail |
|---|---|
| Database | SQLite file — no external database required |
| AI API | Anthropic Claude API (optional — rule-based fallback included) |
| Environment | Runs fully on localhost — no cloud account needed |
cashclock/
├── backend/ # FastAPI Python server
│ ├── main.py # API routes and server entry point
│ ├── forecaster.py # Holt-Winters 30-day cash flow forecast
│ ├── anomaly.py # Rolling z-score anomaly detection
│ ├── health_insights.py # Runway score and health classification
│ ├── ai_coach.py # Claude AI summaries and free-text Q&A
│ ├── loan.py # Loan sizing, risk scoring, repayment schedule
│ ├── pdf_report.py # ReportLab PDF report generation
│ ├── database.py # SQLite schema creation and queries
│ ├── data_generator.py # Realistic SME transaction data generator
│ ├── generate_sample.py # Script to seed the database with sample data
│ ├── seed_data.sql # Pre-generated SQL seed data (10 SME businesses)
│ ├── requirements.txt # Python dependencies
│ └── .env.example # Environment variable template
│
├── frontend/ # React + Vite web application
│ ├── src/
│ │ ├── App.jsx # Root component and routing
│ │ ├── main.jsx # Entry point
│ │ ├── index.css # Global styles (Tailwind directives)
│ │ └── components/
│ │ ├── Landing.jsx # Role selection screen
│ │ ├── Dashboard.jsx # Manager portfolio dashboard
│ │ ├── CustomerDashboard.jsx # Business owner dashboard
│ │ ├── CustomerView.jsx # Business list selector
│ │ ├── ManagerBusinessPage.jsx # Per-business detail (manager)
│ │ ├── LoanOfferPage.jsx # Loan offer detail and application
│ │ ├── LoanOfferCard.jsx # Loan offer summary card
│ │ ├── CashBalanceForecastChart.jsx # 30-day forecast line chart
│ │ ├── CashFlowBreakdownChart.jsx # Monthly inflow/outflow bar chart
│ │ ├── CashCalendar.jsx # Daily colour-coded calendar
│ │ ├── PatternDrivers.jsx # Trend sparkline + seasonality bars
│ │ ├── AnomalyBandMini.jsx # Mini anomaly indicator
│ │ ├── WhatIfPanel.jsx # Scenario builder UI
│ │ ├── TrainingProgress.jsx # Loading animation screen
│ │ ├── LoginPage.jsx # Login screen
│ │ └── ChartLegendBaseline.jsx # Chart legend component
│ ├── package.json
│ ├── vite.config.js # Vite config — proxies /api/* to backend :8000
│ ├── tailwind.config.js
│ └── postcss.config.js
│
├── datasets/ # Raw SME dataset files used for data generation
└── README.md
These instructions set up the project to run entirely on your local machine. No cloud accounts, no deployment needed.
Before you begin, make sure you have the following installed:
| Tool | Minimum Version | Download |
|---|---|---|
| Python | 3.10 | python.org |
| Node.js | 18 | nodejs.org |
| npm | bundled with Node.js | — |
| Git | any recent version | git-scm.com |
An Anthropic API key is optional. The app works fully without it — it will use rule-based text summaries instead of AI-generated ones.
git clone https://github.com/anshul23102/cashclock.git
cd cashclockcd backendCreate and activate a virtual environment:
# macOS / Linux
python3 -m venv venv
source venv/bin/activate
# Windows (Command Prompt)
python -m venv venv
venv\Scripts\activateYou should see (venv) appear at the start of your terminal prompt.
Install Python dependencies:
pip install -r requirements.txtThis installs FastAPI, statsmodels, pandas, ReportLab, anthropic, and all other dependencies.
Configure environment variables:
cp .env.example .envStart the backend server:
uvicorn main:app --reload --port 8000You should see output like:
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process
The backend API is now running at http://localhost:8000. Keep this terminal open.
Open a new terminal window (keep the backend terminal running), then from the project root:
cd frontend
npm install
npm run devYou should see:
VITE v5.x.x ready in XXX ms
➜ Local: http://localhost:5173/
The Vite dev server automatically proxies all
/api/*requests to the backend on port 8000. No CORS configuration or manual URL changes needed.
Navigate to http://localhost:5173 in your browser.
You will see the CashClock landing page with two role options:
| Role | What you see |
|---|---|
| I'm a Bank Manager | Portfolio view of all 10 SME clients with KPIs, charts, and loan tools |
| I'm a Business Owner | Business selector → personal dashboard with forecast, anomalies, and loan offer |
| Problem | Fix |
|---|---|
ModuleNotFoundError on backend start |
Make sure your venv is activated — you should see (venv) in your prompt |
npm install fails |
Check Node.js version: node --version must be 18+ |
| Backend starts but frontend shows blank | Confirm backend is running on port 8000 and frontend on 5173 |
| AI summaries say "rule-based fallback" | Either no API key is set, or the key in .env is invalid — this is expected behaviour |
- Click "I'm a Business Owner" on the landing page
- Select a business from the list (e.g. Ravi Electronics)
- The dashboard loads with:
- Current balance and week-over-week change
- 30-day forecast chart with three confidence bands
- No-cash zone warnings (if any)
- Recent anomalies with severity labels
- Open any business dashboard and scroll to "What-If Scenario"
- Drag the Revenue Change slider (e.g. to −30%)
- Optionally enter a one-off cash injection (e.g. ₹50,000)
- Click "Run Scenario" — the forecast chart updates to show projected vs baseline
Note: The AI Ask Box button is present in the UI but is not yet functional. Free-text Q&A is planned for a future release.
On any business dashboard, click "Download Report". A multi-page PDF is generated and downloaded, containing:
- Business summary and current health score
- 30-day forecast chart (image embedded)
- Anomaly table with severity and causes
- Loan eligibility summary
- Log in as Bank Manager
- On the dashboard, click "Send Offers to All At-Risk" to bulk-send pre-approved offers
- Or search for a specific business → expand it → click "Approve Loan" to approve individually
curl http://localhost:8000/api/businesses/1/forecast{
"runway_score": 67,
"classification": "temporary_dip",
"loan_eligible": true,
"no_cash_zones": [
{ "date": "2025-05-03", "projected_balance": 8200, "severity": "critical" }
],
"forecast": [
{ "date": "2025-04-13", "likely": 142500, "low": 118000, "high": 167000 }
]
}| Method | Endpoint | Description |
|---|---|---|
GET |
/api/health |
Server health check |
GET |
/api/businesses |
List all businesses with summary stats |
GET |
/api/businesses/{id} |
Full business data + 365 days of transactions |
GET |
/api/businesses/{id}/forecast |
30-day forecast, health score, anomaly summary |
GET |
/api/businesses/{id}/anomalies |
Detailed anomaly report with z-scores |
GET |
/api/businesses/{id}/breakdown |
Monthly cash flow + expense composition |
POST |
/api/businesses/{id}/scenario |
What-if scenario analysis |
POST |
/api/businesses/{id}/ask |
AI Q&A endpoint (not yet wired to the UI) |
GET |
/api/businesses/{id}/report/pdf |
Download multi-page PDF report |
POST |
/api/businesses/{id}/apply-loan |
Business owner submits loan application |
POST |
/api/businesses/{id}/approve-loan |
Manager approves a loan |
GET |
/api/businesses/{id}/loan-status |
Poll current loan application status |
GET |
/api/portfolio/manager |
Full manager portfolio with all KPIs |
POST |
/api/portfolio/send-offers |
Bulk send pre-approved loan offers |
POST |
/api/offer/accept |
Business owner accepts a loan offer |
Indian SME cash flows are strongly seasonal — festivals (Diwali, Holi), monsoon slowdowns, and quarterly GST cycles create recurring patterns that simpler models miss. Holt-Winters Triple Exponential Smoothing (ETS) was chosen because it explicitly models level, trend, and seasonality as separate components, producing personalised forecasts from each business's own 365-day history rather than industry averages.
Key engineering detail: Raw daily data is aggregated to weekly before fitting, which removes noise from zero-revenue weekends and public holidays. The fitted weekly forecast is then redistributed back to daily values using each business's observed day-of-week pattern — preserving weekly cycle accuracy while giving granular daily output.
A fixed rupee threshold fails across SMEs with vastly different transaction scales — ₹50,000 is routine for one business and extraordinary for another. Rolling z-scores normalise each transaction against that business's own recent history window. A spike that is 2.5σ above this business's typical pattern is flagged regardless of absolute value, making the detector equally sensitive for a micro-SME and a mid-size manufacturer.
┌──────────────────────────────────────────────────────────────┐
│ Browser (React 18) │
│ Landing Page → Manager Dashboard / Business Dashboard │
│ Recharts · Tailwind CSS · Lucide Icons · Axios │
└───────────────────────────┬──────────────────────────────────┘
│ HTTP / REST
│ (Vite proxy: /api/* → :8000)
▼
┌──────────────────────────────────────────────────────────────┐
│ FastAPI Backend (:8000) │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ forecaster │ │ anomaly │ │ health_insights │ │
│ │Holt-Winters │ │ rolling z- │ │ runway score 0- │ │
│ │ETS, 30-day │ │ score detect │ │ 100, classif. │ │
│ └─────────────┘ └──────────────┘ └──────────────────┘ │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ ai_coach │ │ loan │ │ pdf_report │ │
│ │ Claude API │ │ risk scoring │ │ ReportLab │ │
│ │ + fallback │ │ + repayment │ │ multi-page │ │
│ └─────────────┘ └──────────────┘ └──────────────────┘ │
└───────────────────────────┬──────────────────────────────────┘
│
┌──────────────┴──────────────┐
▼ ▼
┌─────────────────────┐ ┌────────────────────┐
│ SQLite DB │ │ Anthropic API │
│ businesses table │ │ claude-haiku-4-5 │
│ daily_data table │ │ [optional] │
└─────────────────────┘ └────────────────────┘
Data flow for a forecast request:
Browser GET /api/businesses/{id}/forecast
→ main.py route handler
→ database.py: fetch 365 days of daily_data
→ forecaster.py: aggregate weekly → fit ETS → project 30 days → redistribute daily
→ anomaly.py: compute rolling z-scores → classify severity
→ health_insights.py: compute runway score → classify risk tier
→ ai_coach.py: generate summary (Claude API or rule-based)
→ JSON response → React renders charts
| Limitation | Detail |
|---|---|
| Simulated data | 10 SME businesses are generated from realistic statistical templates — not real bank transaction data |
| No authentication | The role selection screen has no passwords or session management; anyone can switch roles |
| SQLite only | The database is a local file; it is not designed for concurrent multi-user access |
| India-only patterns | All businesses are modelled with INR, Indian seasonal events, and Indian tax cycles |
| No live bank feed | Cash flow data is pre-loaded; the app is not connected to any live transaction API or account aggregator |
| Forecast accuracy | ETS works well for the patterns in the generated data; accuracy on real-world data would require re-calibration |
These are features that would be built with more time — they are not currently implemented.
- Open Banking integration — connect to RBI account aggregator APIs for live transaction data
- User authentication — secure login with JWT tokens and role-based access control
- PostgreSQL migration — replace SQLite with a production-grade database for multi-user scale
- Push notifications — alert business owners via SMS or email when a no-cash zone is predicted
- 90-day forecast horizon — extend beyond the current 30-day window
- Mobile app — React Native client for on-the-go cash health monitoring
| Variable | Required | Description |
|---|---|---|
ANTHROPIC_API_KEY |
Optional | Claude API key for AI-generated forecast summaries. Q&A feature not yet functional. Omit for rule-based fallbacks. |
# Copy the example file and edit it
cp backend/.env.example backend/.envSecurity: Never commit your
.envfile. It is already in.gitignore. Only commit.env.examplewith placeholder values.
This project is submitted under the Apache License 2.0, in compliance with NatWest Group Code for Purpose — India Hackathon requirements.
- All commits are DCO-compliant (Developer Certificate of Origin)
- A single email address (
anshul23102@iiitd.ac.in) is used for all commits and hackathon communication - All third-party libraries are used under their respective open-source licences (MIT, Apache 2.0, BSD-3)
- No confidential, proprietary, or real customer data is included in this repository
- No API keys, passwords, or secrets are hard-coded anywhere in the codebase
Built with ❤️ for the NatWest Group Code for Purpose — India Hackathon
Helping Indian SMEs see their financial future clearly.
