# shy742/shubh_sawariya architecture

> Architecture diagram of the GitHub repository shy742/shubh_sawariya, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shy742/shubh_sawariya
- Repository: https://github.com/shy742/shubh_sawariya

## Overview

##### Project type and purpose
- This is a full-stack web application (“BRM Financial Analyzer”) built with Flask (Python) on the backend and plain HTML/CSS/JavaScript (D3.js) on the frontend.

##### File structure
- Top-level files/directories
– app.py: main Flask application and HTTP API endpoints
– check_env.py: ensures required env vars (GOOGLE_API_KEY) are present
– cors_middleware.py: Flask middleware for handling CORS
– gunicorn_config.py, Procfile, render.yaml, runtime.txt, .buildpacks: deployment/config for Render.com and Gunicorn
– index.html, script.js, styles.css: static frontend assets
– requirements.txt: Python dependencies (Flask, PyPDF2, python-dotenv, etc.)
– test_api_key.py: unit test for env var validation
– .env, .gitignore: local dev config

- Patterns & architectural hints
– Monolithic service combining API server + static asset hosting
– Middleware pattern for CORS and environment checks
– Single codebase, no separate “frontend” microservice

##### Insights from README
- Backend: Flask handles file upload, PDF parsing, AI calls
- AI integration: Google Gemini AI for data extraction
- Visualization: D3-Sankey in script.js
- Deploy on Render.com with env vars

a. Main components
1. Client Browser (UI)
- index.html + script.js + styles.css
- D3.js for Sankey rendering and chat widget
2. Flask API Server
- Endpoints:
– /upload → handles PDF uploads
– /sankey-data → returns processed financial flows
– /chat → proxies chat queries to AI
- Middleware: CORS, env validation
- PDF processing: PyPDF2
3. External Service
- Google Gemini AI (via HTTPS REST API)
4. Infrastructure / Deployment
- Gunicorn WSGI server (gunicorn_config.py)
- Render.com (render.yaml, Procfile, .buildpacks)

b. Relationships & data flows
1. User uploads PDF via browser UI → HTTP POST to Flask
2. Flask → PyPDF2 extracts raw text/data
3. Flask → Google Gemini AI for semantic financial extraction
4. Gemini returns structured JSON → Flask formats for Sankey
5. Flask → JSON response → browser
7. Chat UI: browser sends query → Flask → Gemini → browser

c. Architectural patterns & principles
– Monolithic API + static asset server
– Layered pattern: Presentation (UI) → API layer → Service layer (PDF, AI)
– Middleware for cross-cutting concerns (CORS, config validation)
– Third-party service integration

d. Key technologies & libraries
– Flask, Gunicorn, python-dotenv, PyPDF2
– D3.js (D3-Sankey) for visualizations
– Render.com for hosting
– Google Gemini AI as external ML service

- Break the system into: Browser UI, Flask API, PDF Parser, AI Service, Deployment infra
- Interactions: upload → parse → AI call → JSON → rendering
- Technologies on each component
- Environment/configuration pieces (dotenv, gunicorn, Render) are noted in the infra section

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Browser (UI)"
        A1["index.html"]:::ui
        A2["script.js"]:::ui
        A3["styles.css"]:::ui
    end

    subgraph "Flask API Server"
        B1["app.py"]:::backend
        subgraph "Middleware"
            B2["cors_middleware.py"]:::middleware
            B3["check_env.py"]:::middleware
        end
    end

    C1["Google Gemini AI"]:::external

    subgraph "Deployment Infra"
        D1["Procfile"]:::infra
        D2["render.yaml"]:::infra
        D3[".buildpacks"]:::infra
        D4["gunicorn_config.py"]:::infra
    end

    subgraph "Environment & Config"
        E1[".env"]:::infra
        E2["requirements.txt"]:::infra
        E3["runtime.txt"]:::infra
    end

    subgraph "Testing"
        F1["test_api_key.py"]:::infra
    end

    A2 -->|"POST PDF to /upload"| B1
    B1 -->|"extract via PyPDF2"| B1
    B1 -->|"call AI API"| C1
    C1 -->|"structured JSON"| B1
    B1 -->|"JSON sankey-data"| A2
    A2 -->|"user chat query"| B1
    B1 -->|"chat response JSON"| A2

    click A1 "https://github.com/shy742/shubh_sawariya/blob/main/index.html"
    click A2 "https://github.com/shy742/shubh_sawariya/blob/main/script.js"
    click A3 "https://github.com/shy742/shubh_sawariya/blob/main/styles.css"
    click B1 "https://github.com/shy742/shubh_sawariya/blob/main/app.py"
    click B2 "https://github.com/shy742/shubh_sawariya/blob/main/cors_middleware.py"
    click B3 "https://github.com/shy742/shubh_sawariya/blob/main/check_env.py"
    click E1 "https://github.com/shy742/shubh_sawariya/blob/main/.env"
    click E2 "https://github.com/shy742/shubh_sawariya/blob/main/requirements.txt"
    click E3 "https://github.com/shy742/shubh_sawariya/blob/main/runtime.txt"
    click D1 "https://github.com/shy742/shubh_sawariya/tree/main/Procfile"
    click D2 "https://github.com/shy742/shubh_sawariya/blob/main/render.yaml"
    click D3 "https://github.com/shy742/shubh_sawariya/blob/main/.buildpacks"
    click D4 "https://github.com/shy742/shubh_sawariya/blob/main/gunicorn_config.py"
    click F1 "https://github.com/shy742/shubh_sawariya/blob/main/test_api_key.py"

    classDef ui fill:#ADD8E6,stroke:#000,color:#000
    classDef backend fill:#90EE90,stroke:#000,color:#000
    classDef middleware fill:#98FB98,stroke:#000,color:#000
    classDef external fill:#FFA500,stroke:#000,color:#000
    classDef infra fill:#D3D3D3,stroke:#000,color:#000
```
