Lumen — The AI Financial Intelligence Layer

Lumen is a full-stack intelligent finance system designed to automate expense tracking, bill management, document extraction, and real-time financial insights using AI.

This project includes:

• A modern React + TypeScript frontend
• A secure Flask backend with JWT authentication
• File uploads (images/PDFs), bill extraction, and verification
• Automatic transaction creation & categorisation
• AI-powered document analysis

---

Screenshots

Analysis Dashbord

Past Transactions

Add Bills

Add Transactions

GST Checker

File ITR

---

🚀 Features

1. Smart Transaction Management

• Add, edit, and view transactions
• Category filtering
• Sorting by date (ASC/DESC)
• Pagination
• Bill preview (images) and bill download

2. AI-Powered Bill Extraction

• Upload receipts or invoices
• Automated extraction of vendor, amount, date, and payment info
• Verification status (pending, verified, rejected)

3. User Authentication

• JWT-based login/signup
• Protected routes on both frontend and backend

4. Full Document Pipeline

• Every bill upload automatically:

  • Creates a Transaction
  • Creates a Document entry
  • Links the two together

5. Clean Financial Dashboard

• Summary cards: Verified, Pending, Suspicious
• Table view with actions

6. ITR Form Filling

• Automatically fills your ITR File based on your transaction
• Allows to directly download the PDF.

---

🏗️ Tech Stack

Frontend

• React + TypeScript
• TailwindCSS
• ShadCN UI
• Axios API wrapper
• React Router

Backend

• Flask (Python)
• Flask-JWT-Extended
• SQLAlchemy ORM
• SQLite / PostgreSQL
• File uploads + static file serving

---

🔧 Setup Instructions

Backend Setup

cd backend
pip install -r requirements.txt
flask run

create .env file with perplexity api and gst checker api Backend runs at: http://localhost:5000

Frontend Setup

cd frontend
npm install
npm run dev

Frontend runs at: http://localhost:5173

---

📡 Lumen API Endpoints

🔐 Authentication

POST /auth/signup

Create a new user.

Body:

{
  "first_name": "",
  "last_name": "",
  "email": "",
  "phone_number": "",
  "password": "",
  "organization": "",
  "aadhar_number": "",
  "pan_number": "",
  "date_of_birth": "",
  "employment_type": "",
  "annual_salary": "",
  "address": ""
}

---

POST /auth/login

Authenticate user.

Body:

{ "email": "", "password": "" }

Response:

{
  "access": "<JWT_ACCESS>",
  "refresh": "<JWT_REFRESH>"
}

---

GET /auth/me (JWT Required)

Returns the authenticated user's profile.

---

PUT /auth/update-profile (JWT Required)

Update profile fields.

Accepts any subset of:

first_name, last_name, phone_number, organization,
aadhar_number, pan_number, date_of_birth, employment_type,
annual_salary, address, email

---

💸 Transactions

GET /transactions/all (JWT Required)

Fetch paginated, optionally filtered, optionally sorted transactions.

Query Params:

page=1
per_page=20
category=food
sort=asc | desc | created_asc | created_desc

Response:

{
  "transactions": [...],
  "page": 1,
  "total_pages": 3,
  "total": 60,
  "category_filter": null,
  "sort": "desc"
}

---

GET /transactions/ (JWT Required)

Fetch a single transaction + linked document metadata.

---

POST /transactions/add (JWT Required)

Create a manual transaction (non-bill).

Body:

{
  "item_name": "",
  "amount": "",
  "category": "",
  "payment_mode": "",
  "transaction_date": "YYYY-MM-DD",
  "vendor": "",
  "description": "",
  "tags": ""
}

---

📄 Document + Bill Extraction

GET /document/ (JWT Required)

Fetch paginated documents.

Query Params:

page=1
limit=20

---

POST /document/add (JWT Required)

Upload bill → OCR → LLM extraction → GST lookup → auto-create Transaction & Document.

Form-Data:

file: <file>
vendor: optional
category: optional
notes: optional

Response:

{
  "transaction_id": 12,
  "document_id": 9,
  "status": "verified",
  "llm": { ...extracted_fields },
  "gst_details": { ... },
  "file_url": "/documents/<file>"
}

---

GET /documents/

Downloads a stored bill file.

---

🧾 GST Lookup

POST /gst/check_public (JWT Required)

Lookup GSTIN using rotating API keys.

Body:

{ "gstin": "22AAAAA0000A1Z5" }

---

🧮 ITR Generation

POST /itr/generate (JWT Required)

Generate a filled ITR PDF using user profile + transactions.

Body:

{
  "form_data": { ... }
}

Response: A downloadable PDF.