# safia-faiz02/ai-powered-personal-finance-assistant architecture

> Architecture diagram of the GitHub repository safia-faiz02/ai-powered-personal-finance-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/safia-faiz02/ai-powered-personal-finance-assistant
- Repository: https://github.com/safia-faiz02/ai-powered-personal-finance-assistant

## Overview

##### Project Type and Purpose
- This is a single‐page, full-stack “smart budgeting” web app built with Streamlit (frontend/UI) and Python (backend logic).
- It ingests PDF statements (via PyMuPDF), calls an external AI model (Deepseek V3 via the Camel framework), applies budgeting algorithms (50/30/20 rule, zero-based budgeting), and returns categorized expenses and recommendations.

##### File Structure Analysis
- app.py              ← Main Streamlit app containing UI and orchestration logic
- requirements.txt    ← Python dependencies: Streamlit, PyMuPDF, Camel, Deepseek model SDK
- sample_pdfs/        ← Sample PDF statements for demonstration/testing
- README.md           ← High-level project description, tech stack, and features

No separate frontend directory—Streamlit handles both UI and backend in one process. No database layer; data is transient.

##### Key Components
a. User Interface (Streamlit)
- Web browser ↔ Streamlit server (app.py)
- File upload widget for PDFs
b. PDF Processing (PyMuPDF)
- PDF parser module extracts raw transactions
c. AI Inference (Camel + Deepseek V3)
- External AI service endpoint called via Camel framework
- Returns categorized transaction data
d. Budgeting Engine
- Applies 50/30/20 rule and zero-based budgeting algorithms
- Flags overspending and formulates recommendations
e. Sample PDF Store (local filesystem)
- Serves sample files for quick testing
f. Output Renderer
- Streamlit charts, tables, and text blocks

##### Interactions and Data Flow
1. User uploads PDF (or selects sample).
2. Streamlit app (app.py) streams the PDF bytes to PyMuPDF.
3. Extracted transaction list is packaged and sent to Camel framework.
4. Camel calls Deepseek V3 API, returns categorized data.
5. Backend budgeting engine consumes the categorized data, runs algorithms.
6. Results (expense breakdown, flags, suggestions) rendered back in Streamlit UI.

##### Architectural Patterns & Principles
- Single‐process, event-driven UI (Streamlit)
- Modular separation: parsing, AI inference, budgeting logic, and rendering
- External AI service decoupled behind Camel framework interface
- No persistent storage—stateless request handling

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User Agent
    Browser["Web Browser"]:::external

    %% Sample PDFs Store
    SampleStore["Sample PDF Store"]:::external

    %% Streamlit App Container
    subgraph "Streamlit App (app.py)"
        direction TB
        UI["File Upload & Output Renderer"]:::ui
        PDF["PDF Processor (PyMuPDF)"]:::processor
        AI["AI Inference (Camel)"]:::ai
        Budget["Budgeting Engine"]:::engine
    end

    %% External AI Service
    Deepseek["Deepseek V3 API"]:::external

    %% Documentation & Dependencies
    README["Project Documentation (README.md)"]:::external
    REQS["Dependencies (requirements.txt)"]:::external

    %% Data Flows
    Browser -->|"uploads PDF"| UI
    SampleStore -->|"selects sample PDF"| UI
    UI -->|"PDF bytes"| PDF
    PDF -->|"Transaction JSON"| AI
    AI -->|"Categorized JSON"| Budget
    Budget -->|"Recommendations & breakdown"| UI
    AI -->|"calls API"| Deepseek

    %% Click Events
    click UI "https://github.com/safia-faiz02/ai-powered-personal-finance-assistant/blob/main/app.py"
    click PDF "https://github.com/safia-faiz02/ai-powered-personal-finance-assistant/blob/main/app.py"
    click AI "https://github.com/safia-faiz02/ai-powered-personal-finance-assistant/blob/main/app.py"
    click Budget "https://github.com/safia-faiz02/ai-powered-personal-finance-assistant/blob/main/app.py"
    click SampleStore "https://github.com/safia-faiz02/ai-powered-personal-finance-assistant/tree/main/sample_pdfs/"
    click README "https://github.com/safia-faiz02/ai-powered-personal-finance-assistant/blob/main/README.md"
    click REQS "https://github.com/safia-faiz02/ai-powered-personal-finance-assistant/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004aad,stroke-width:1.5px
    classDef processor fill:#ccffcc,stroke:#008000,stroke-width:1.5px
    classDef ai fill:#ffddcc,stroke:#ff6600,stroke-width:1.5px
    classDef engine fill:#e5ccff,stroke:#800080,stroke-width:1.5px
    classDef external fill:#f2f2f2,stroke:#999999,stroke-dasharray: 5 5,stroke-width:1px
```
