Financial Digital Twin API (FinTwin)

A comprehensive, full-stack solution for personal financial management. FinTwin acts as your digital financial clone, featuring detailed spending analysis, Generative AI chat assistance, and real-time smart spending checks to help you make informed financial decisions.

---

Important Note: All commits made by the GitHub account alyyrizvi02-art belong to me, as that is my alternate ID.

---

Features in Detail

• Spending Analysis Dashboard: Cleaned and synthesized data categorization. Get a high-level view of your spending habits, top categories, and financial snapshot in an intuitive UI.
• GenAI Financial Assistant: A conversational AI agent (RAG-enabled) that understands natural language. You can log expenses (e.g., "I spent $50 on food at Walmart") or ask for insights into your financial health.
• SmartSpend Check: A real-time evaluation engine for potential purchases. It cross-references your current financial status to let you know if a purchase fits within your budget.
• Profile Management: View and manage your comprehensive financial profile, including current income, savings, debts, and long-term financial goals.
• PDF Reporting Export: Generate beautifully formatted, at-a-glance PDF reports of your spending summaries and top categories.

Technology Stack

• Backend: Python 3.10+, FastAPI, Pydantic, Uvicorn
• Frontend: React 18, Vite, Recharts for visualizations, Lucide for icons
• Database / Cloud: AWS DynamoDB (via Boto3)
• AI/ML: RAG Service (Retrieval-Augmented Generation), Agent Orchestrator (currently in Mock Mode)
• Testing: Pytest with unittest.mock

Project Structure

FinTwin/
├── backend/          # FastAPI application server
│   ├── main.py       # API entrypoint and route definitions
│   ├── services/     # Business logic (Transaction, AI, Data Prep, DB Services)
│   └── requirements.txt
├── frontend/         # React application UI
│   ├── src/          # React components and assets
│   ├── package.json  # Node dependencies
│   └── vite.config.js
├── tests/            # Pytest test suite for backend logic
└── README.md         # Project documentation

Getting Started

Prerequisites

• Python 3.8 or higher
• Node.js & npm (npm install --legacy-peer-deps might be needed for React 18/Eslint 8 dependencies)
• AWS Credentials (only required if DynamoDB is used in production. Development/Testing can run with mocks)

Backend Setup

1. Navigate to the backend directory or run from the root:

   cd backend

2. Create and activate a virtual environment (recommended):

   • Windows:

     python -m venv venv
     .\venv\Scripts\activate

   • macOS/Linux:

     python3 -m venv venv
     source venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt
   pip install pytest # for running tests

4. Run the backend server:

   • Standard Mode:

     python main.py

   • Development Mode (Auto-Reload):

     uvicorn main:app --reload

   The backend API will run on http://localhost:8000.

   Note: The AI services (RAG, IBM Granite) and DB dependencies are currently designed with a Mock Mode or gracefully degrade for demonstration purposes.

Frontend Setup

1. Navigate to the frontend directory:

   cd frontend

2. Install dependencies (we recommend using legacy peer deps if you run into Eslint conflicts):

   npm install

3. Run the development server:

   npm run dev

   The frontend application will be accessible via the URL provided in the terminal (usually http://localhost:5173).

4. Build for production:

   npm run build

Testing

To run the backend test suite (which uses mocking to avoid hitting live databases):

# From the root directory, with venv activated
pytest tests/

API Endpoints Reference

• GET / : API Root health check message.
• GET /api/spending : Retrieves cleaned and categorized spending data.
• GET /api/export-summary : Downloads a generated PDF snapshot of your finances.
• GET /api/profile : Retrieves the user's financial profile.
• POST /api/chat : Send a natural language message to the GenAI assistant (e.g. log transactions).
• POST /api/smartspend : Check if a specific spending amount and category is a wise choice.

---

FinTwin - Your smart AI financial partner.