+
+---
+
+## ๐โโ๏ธ Overview
+
+**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.
+
+---
+
+## โ Features
+
+> All features listed below are implemented and functional in the current codebase.
+
+### ๐ Business Owner Dashboard
+
+- **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** โ free-text Q&A answered by Claude AI (falls back to rule-based response if no API key)
+- **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
+
+### ๐ฆ Bank Manager 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
+
+### ๐ค AI & Analytics Engine
+
+- **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 and free-text Q&A via `claude-haiku-4-5`
+- **Loan risk scoring** โ three tiers (low / medium / high) that determine interest rate and loan size
+
+---
+
+## ๐ ๏ธ Tech Stack
+
+**Backend**
+
+[](https://skillicons.dev)
+
+| 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**
+
+[](https://skillicons.dev)
+
+| 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**
+
+[](https://skillicons.dev)
+
+| 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 |
+
+---
+
+## ๐๏ธ Folder Structure
+
+```
+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
+```
+
+---
+
+## โ๏ธ Installation & Setup
+
+> These instructions set up the project to run **entirely on your local machine**. No cloud accounts, no deployment needed.
+
+### Prerequisites
+
+Before you begin, make sure you have the following installed:
+
+| Tool | Minimum Version | Download |
+|---|---|---|
+| **Python** | 3.10 | [python.org](https://python.org) |
+| **Node.js** | 18 | [nodejs.org](https://nodejs.org) |
+| **npm** | bundled with Node.js | โ |
+| **Git** | any recent version | [git-scm.com](https://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.
+
+---
+
+### Step 1 โ Clone the repository
+
+```bash
+git clone https://github.com/anshul23102/cashclock.git
+cd cashclock
+```
+
+---
+
+### Step 2 โ Set up the backend
+
+```bash
+cd backend
+```
+
+**Create and activate a virtual environment:**
+
+```bash
+# macOS / Linux
+python3 -m venv venv
+source venv/bin/activate
+
+# Windows (Command Prompt)
+python -m venv venv
+venv\Scripts\activate
+```
+
+You should see `(venv)` appear at the start of your terminal prompt.
+
+**Install Python dependencies:**
+
+```bash
+pip install -r requirements.txt
+```
+
+This installs FastAPI, statsmodels, pandas, ReportLab, anthropic, and all other dependencies.
+
+**Configure environment variables:**
+
+```bash
+cp .env.example .env
+```
+
+Open the `.env` file in any text editor. If you have an Anthropic API key, paste it in:
+
+```env
+ANTHROPIC_API_KEY=your_api_key_here
+```
+
+If you do not have a key, leave the file as-is โ the app will use rule-based fallbacks automatically.
+
+**Start the backend server:**
+
+```bash
+uvicorn main:app --reload --port 8000
+```
+
+You 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.
+
+---
+
+### Step 3 โ Set up the frontend
+
+Open a **new terminal window** (keep the backend terminal running), then from the project root:
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+You 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.
+
+---
+
+### Step 4 โ Open the app
+
+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 |
+
+---
+
+### Troubleshooting
+
+| 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 |
+
+---
+
+## ๐ Usage Examples
+
+### Viewing a business dashboard
+
+1. Click **"I'm a Business Owner"** on the landing page
+2. Select a business from the list (e.g. _Ravi Electronics_)
+3. 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
+
+### Running a what-if scenario
+
+1. Open any business dashboard and scroll to **"What-If Scenario"**
+2. Drag the **Revenue Change** slider (e.g. to โ30%)
+3. Optionally enter a one-off cash injection (e.g. โน50,000)
+4. Click **"Run Scenario"** โ the forecast chart updates to show projected vs baseline
+
+### Asking the AI coach
+
+In the **"Ask Your Business Coach"** panel, type a plain-English question:
+
+```
+"Why did my cash drop in February?"
+"When is my next predicted cash shortage?"
+"What's driving my expenses up this month?"
+```
+
+The response is generated by Claude AI if an API key is present, or by the rule-based engine otherwise.
+
+### Downloading a PDF report
+
+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
+
+### Manager: sending loan offers
+
+1. Log in as **Bank Manager**
+2. On the dashboard, click **"Send Offers to All At-Risk"** to bulk-send pre-approved offers
+3. Or search for a specific business โ expand it โ click **"Approve Loan"** to approve individually
+
+### Example API call
+
+```bash
+curl http://localhost:8000/api/businesses/1/forecast
+```
+
+```json
+{
+ "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 }
+ ]
+}
+```
+
+---
+
+## ๐ก API Reference
+
+| 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-powered free-text Q&A |
+| `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 |
+
+---
+
+## ๐ง Technical Depth
+
+### Why Holt-Winters Exponential Smoothing?
+
+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.
+
+### Why rolling z-score for anomaly detection?
+
+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.
+
+### System Architecture
+
+```
+โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+โ 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
+```
+
+---
+
+## โ ๏ธ Limitations
+
+| 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 |
+
+---
+
+## ๐ฎ Future Improvements
+
+> 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
+
+---
+
+## ๐ Configuration Reference
+
+| Variable | Required | Description |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | Optional | Claude API key for AI summaries and Q&A. Omit for rule-based fallbacks. |
+
+```bash
+# Copy the example file and edit it
+cp backend/.env.example backend/.env
+```
+
+> **Security:** Never commit your `.env` file. It is already in `.gitignore`. Only commit `.env.example` with placeholder values.
+
+---
+
+## ๐ License & Compliance
+
+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.*
+
+[](https://github.com/anshul23102)
+[](mailto:anshul23102@iiitd.ac.in)
+
+
+
+
diff --git a/frontend/src/App.jsx b/frontend/src/App.jsx
index caf7c7c..0ad9b03 100644
--- a/frontend/src/App.jsx
+++ b/frontend/src/App.jsx
@@ -22,10 +22,18 @@ export default function App() {
if (!businesses) {
return (
-
-
-
Could not connect to backend
-
Start the API on port 8000, then refresh.
+
+
+
+
+
+
Service unavailable
+
The backend is starting up โ this can take up to 60 seconds on first load.