EveryRupee

One platform. Three financial control rooms.

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 • Architecture • API Surface • Roadmap

📖 Table of Contents

• Overview
• Role Experiences
• Feature Highlights
• Tech Stack
• Architecture
• Quick Start
• Environment Variables
• API & Database
• 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

✨ 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

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:

npm install

Backend:

# 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:

# Frontend
cp .env.example .env

# Backend
cp backend/.env.example backend/.env

(See the 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

2. Copy environment variables:

   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:

   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):

uvicorn backend.main:app --reload
# Runs on http://127.0.0.1:8000

Start the Frontend (Vite):

npm run dev
# Runs on http://localhost:5173

🔐 Environment Variables

Frontend .env

Backend backend/.env

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

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

🗺 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.

Crafted with purpose by:

Not just another education platform, but an AI-powered bridge for inclusive learning.