EveryRupee
<div align="center"> <!-- Placeholder for your project logo. Suggested size: 200x200px --> <img src="https://i.ibb.co/yFdqX31P/image-removebg-preview-4.png" alt="EveryRupee Logo" width="150" height="150" style="border-radius: 20px;" /> # EveryRupee **One platform. Three financial control rooms.** [](https://reactjs.org/) [](https://fastapi.tiangolo.com/) [](https://supabase.com/) [](https://www.typescriptlang.org/) [](https://tailwindcss.com/) EveryRupee is a role-based fintech workspace for retail users, businesses, and advisors. It combines deterministic financial tools, Supabase-backed authentication, a FastAPI processing engine, and an educational AI sandbox inside a polished React interface. [Getting Started](#-quick-start) • [Architecture](#-architecture) • [API Surface](#-api-surface) • [Roadmap](#-roadmap--next-steps) </div> --- ## 📖 Table of Contents - [Overview](#-overview) - [Role Experiences](#-role-experiences) - [Feature Highlights](#-feature-highlights) - [Tech Stack](#-tech-stack) - [Architecture](#-architecture) - [Quick Start](#-quick-start) - [Environment Variables](#-environment-variables) - [API & Database](#-api--database) - [Roadmap & Next Steps](#-roadmap--next-steps) --- ## 🌟 Overview EveryRupee is built around a simple idea: **different financial users need different operating surfaces.** The result is a single product that feels cohesive while still respecting role-specific needs: - 🛍️ **Retail users** get statement intelligence, spending breakdowns, risk scoring, and planning calculators. - 🏢 **Businesses** get treasury-style visibility, GST invoice generation, and receivables workflows. - 🤝 **Advisors** get a client triage console and a controlled read-only access request flow. --- ## 🎭 Role Experiences | Role | What the user sees | Current Data Source | | :--- | :--- | :--- | | **Retail** | Statement upload, spending charts, risk gauge, recent transactions, calculator suite | Live Supabase data + FastAPI | | **Business** | Cash flow visualizer, GST invoice generator, receivables tracker | Authenticated UI + Mock data | | **Advisor** | Risk triage board, top-risk client spotlight, access-request workflow | Authenticated UI + Mock data | --- ## ✨ Feature Highlights ### 🛍️ Retail Dashboard - **Intelligent Uploads:** Route CSV bank statements through the FastAPI engine. - **Data Normalization:** Parse and normalize inconsistent transaction rows from various bank export formats. - **Smart Categorization:** Automatically categorize spending into `Food`, `Transport`, `Shopping`, `Housing`, etc. - **Risk Assessment:** Estimate credit risk deterministically using income vs. debt volume. - **Financial Tooling:** Generate SHA-256 file hashes, simulate blockchain TxIDs, and utilize calculators for SIPs, EMI, retirement, GST, and more. ### 🏢 Business Dashboard - **Treasury View:** Monitor inflow vs. outflow in a visual cash flow interface. - **GST Invoicing:** Generate GST invoices with deterministic taxable value, GST, and total payable math. - **Receivables Ledger:** Track outstandings via a lightweight invoice ledger. ### 🤝 Advisor Dashboard - **Client Triage:** Sort households by risk score and default probability for fast, actionable insights. - **Access Workflow:** Queue read-only access requests via email. - **Privacy First:** Advisory access is intentionally constrained and strictly client-owned by design. ### 🧠 Educational AI Sandbox Accessible directly from the dashboard UI, this chat assistant answers general questions about taxes, SIPs, credit risk, and investing. It is **intentionally sandboxed**—it cannot and does not read private financial records. *(Includes safe fallbacks if the `GEMINI_API_KEY` is missing).* --- ## 🛠 Tech Stack **Frontend:** React 18 • TypeScript • Vite • Tailwind CSS • Radix UI • React Router • TanStack Query • Recharts • Sonner **Backend:** FastAPI • Uvicorn • Pandas • Google Generative AI (Gemini) • python-multipart **Data & Auth:** Supabase Postgres • Supabase Auth • Row-Level Security (RLS) --- ## 🏗 Architecture ```mermaid graph TD; A[React + Vite Frontend] -->|fetch API| B(FastAPI Backend) B --> C[Pandas Statement Parsing] B --> D[Document Hashing] B --> E[Credit Risk Engine] B --> F[Gemini AI Sandbox] A -->|Supabase JS| G[(Supabase PostgreSQL)] G --> H[Auth & Profiles] G --> I[Retail Transactions] G --> J[Document Vault & RLS] ``` *(Note: If your markdown viewer doesn't support Mermaid, see the text breakdown below)* > The React frontend communicates directly with Supabase for Auth, Profiles, and persistent storage using RLS. Heavy lifting (document hashing, CSV pandas parsing, deterministic risk calculation, and AI) is routed through the FastAPI processing engine. --- ## 🚀 Quick Start ### 1. Install dependencies **Frontend:** ```powershell npm install ``` **Backend:** ```powershell # Windows py -3 -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r backend/requirements.txt # Mac/Linux python3 -m venv .venv source .venv/bin/activate pip install -r backend/requirements.txt ``` ### 2. Configure environment variables Clone the example env files: ```powershell # Frontend cp .env.example .env # Backend cp backend/.env.example backend/.env ``` *(See the [Environment Variables](#-environment-variables) section below for required values).* ### 3. Set up Supabase (Required for Authentication & Data) **For Open Source Contributors:** 1. **Create your own Supabase project** at [supabase.com](https://supabase.com) 2. **Copy environment variables:** ```bash cp .env.example .env cp backend/.env.example backend/.env ``` 3. **Get your Supabase credentials:** - Go to your Supabase dashboard → Settings → API - Copy the "Project URL" and "anon/public" key - Update `.env` with your values: ``` VITE_SUPABASE_URL=https://your-project-ref.supabase.co VITE_SUPABASE_ANON_KEY=your-anon-key-here ``` 4. **Apply the database schema:** ```bash npx supabase login npx supabase link --project-ref your-project-ref npx supabase db push ``` This creates required tables (`profiles`, `retail_profiles`, `retail_transactions`, `retail_credit_risk`, `document_vault`) and configures **Row-Level Security (RLS)**. **Note:** The app includes a **demo mode** that works without Supabase for development/testing. Just use the dev bypass feature in the auth flow. ### 4. Start the Application **Start the Backend (FastAPI):** ```powershell uvicorn backend.main:app --reload # Runs on http://127.0.0.1:8000 ``` **Start the Frontend (Vite):** ```powershell npm run dev # Runs on http://localhost:5173 ``` --- ## 🔐 Environment Variables ### Frontend `.env` | Key | Required | Purpose | | --- | :---: | --- | | `VITE_SUPABASE_URL` | ❌ | Supabase project URL (optional - app works in demo mode) | | `VITE_SUPABASE_ANON_KEY` | ❌ | Supabase anon key (optional - app works in demo mode) | | `VITE_API_BASE_URL` | ✅ | Base URL for the FastAPI backend | ### Backend `backend/.env` | Key | Required | Purpose | | --- | :---: | --- | | `FRONTEND_ORIGINS` | 💡 | Comma-separated allowed CORS origins | | `GEMINI_API_KEY` | ❌ | Enables AI insights (optional - falls back to demo content) | | `DATABASE_URL` | ❌ | Direct database access (optional - backend uses Supabase client) | **Note:** The application is designed to work without any external services in **demo mode**. Supabase and Gemini API keys are optional for development and testing. ## 🎭 Demo Mode EveryRupee includes a comprehensive **demo mode** that works without any external dependencies: - **No Supabase required**: Use the "Dev Preview" option in authentication - **No Gemini API required**: AI insights fall back to curated demo content - **Full functionality**: All features work with realistic sample data - **Perfect for development**: Test the UI/UX without setting up external services To access demo mode: 1. Start the app (`npm run dev`) 2. Click "Continue as Guest" or use the dev bypass feature 3. Select "Retail" role for the full dashboard experience --- ## 🛜 API Surface | Method | Route | Purpose | | :--- | :--- | :--- | | `GET` | `/api/health` | Backend health check | | `POST` | `/api/upload` | Hash uploaded file & return simulated blockchain TxID | | `POST` | `/api/parse-transactions`| Parse CSV statement into normalized JSON rows | | `POST` | `/api/calculate-risk` | Compute deterministic credit-risk from income/debt | | `POST` | `/api/chat` | Return educational finance response from AI sandbox | > **Statement Parsing Rules:** > The retail upload flow is highly flexible. It auto-recognizes multiple date headers (`transaction_date`, `value_date`, etc.), description headers (`merchant`, `narration`, etc.), and handles various amount formats (single column, separate debit/credit, negative parenthesis). --- ## 🗄️ Database Model | Table | Purpose | | --- | --- | | `profiles` | Authenticated user identity, name, email, and app role | | `retail_profiles` | Retail-specific attributes (e.g., annual income) | | `retail_transactions`| Parsed, categorized, and cleaned statement rows | | `retail_credit_risk` | Saved deterministic risk assessments | | `document_vault` | Document metadata, file hashes, and TxIDs | --- ## 🗺 Roadmap & Next Steps EveryRupee is designed as a multi-role financial operating system with trust, clarity, and product polish at the center. Future iterations will focus on: - [ ] **Business Persistence:** Persist business invoices in Supabase with role-aware policies. - [ ] **Advisor Access:** Replace mock clients with secure, authorized shared portfolio views. - [ ] **Storage Workflows:** Move document metadata into a full blob-storage workflow tied to `document_vault`. - [ ] **Enhanced Categorization:** Expand statement rules beyond initial keyword mapping (potentially utilizing local NLP models). - [ ] **Testing:** Add comprehensive automated testing for CSV parsing, risk scoring, and role-protected routing. --- <div align="center"> <b>Crafted with purpose by:</b><br><br> <a href="https://github.com/AyushBinjola1"> <img src="https://img.shields.io/badge/GitHub-ayushbinjola-181717?style=for-the-badge&logo=github&logoColor=white" alt="GitHub Badge"> </a> <br><br> <i>Not just another education platform, but an AI-powered bridge for inclusive learning.</i> </div>