# akxt09/reports-summarization-for-financial-advisors architecture

> Architecture diagram of the GitHub repository akxt09/reports-summarization-for-financial-advisors, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akxt09/reports-summarization-for-financial-advisors
- Repository: https://github.com/akxt09/reports-summarization-for-financial-advisors

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“Financial Report Summarizer using LLMs”) that provides a Flask UI for uploading financial PDFs, runs a RAG pipeline (LlamaIndex + FAISS + LangChain + OpenAI), generates Word summaries, and evaluates them with RAGAS.

##### File Structure
- Top-level:
- app/: Flask application package
– config.py (env & API settings)
– routes.py (HTTP endpoints)
– services/: core pipeline modules
- document_ingester.py (PDF → chunks → FAISS index)
- summary_generator.py (RAG prompts → one/two‐page summary)
- raga_evaluator.py (compute relevance/faithfulness/recall)
- financial_processor.py (domain‐specific parsing)
– utils/file_handler.py (I/O helpers)
– static/, templates/: UI assets and pages
- requirements.txt & run.py: app entry and dependencies

##### Extract Key Architectural Insights from README
- RAG pipeline with vector store (FAISS)
- LlamaIndex for ingestion/embedding
- LangChain for prompt orchestration
- python-docx for summary generation
- Flask for web layer
- External OpenAI API calls

##### Components & Relationships
a. Main Components
1. Browser (User Interface)
2. Flask Web Server (routes.py + config)
3. Service Layer
– Document Ingester (LlamaIndex + FAISS)
– Vector Store (FAISS index)
– Summarizer (LangChain + OpenAI)
– Evaluator (RAGAS)
– Document Generator (python-docx)
4. File System (uploaded PDFs, generated .docx)
5. External Services (OpenAI API)
b. Relationships & Data Flows
- User uploads PDF → HTTP POST to Flask routes
- routes.py calls Document Ingester → creates vector index
- routes.py invokes Summary Generator → LangChain calls OpenAI → returns text
- Summary Generator writes .docx via python-docx → filesystem
- routes.py invokes RagaEvaluator → returns metrics
- Flask returns links/metrics to UI for download/display
c. Architectural Patterns & Design Principles
- Layered Architecture: UI → Web/API layer → Service layer → Data/storage → External services
- Separation of Concerns: document ingestion, summarization, evaluation, and I/O in separate modules
- Retrieval-Augmented Generation pattern
d. Technologies & Frameworks
- Flask, Jinja2 (templates), JavaScript/CSS (static)
- LlamaIndex + FAISS (vector store)
- LangChain (RAG orchestration)
- python-docx (Word generation)
- RAGAS (evaluation metrics)
- OpenAI API

##### Detailed Level of Abstraction
- Four service modules individually rather than lumping them as “Backend Logic.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["Browser UI"]:::frontend
        Static["Static Assets (CSS/JS)"]:::frontend
        Templates["HTML Templates"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Routes["Flask Routes"]:::backend
        Config["App Configuration"]:::backend
        subgraph "Service Layer"
            direction TB
            Ingester["Document Ingester"]:::service
            Processor["Financial Processor"]:::service
            Summarizer["Summary Generator"]:::service
            Evaluator["RAGAS Evaluator"]:::service
            FileHandler["File Handler Utility"]:::service
        end
    end

    %% Storage Layer
    subgraph "Storage"
        direction TB
        VectorStore["FAISS Vector Store"]:::storage
        FileSystem["File System"]:::storage
    end

    %% External Services
    OpenAI["OpenAI API"]:::external

    %% Data Flows
    Browser -->|"HTTP POST PDF"| Routes
    Static --> Browser
    Templates --> Browser

    Routes -->|"load config"| Config
    Routes -->|"ingest document"| Ingester
    Ingester -->|"store chunks"| VectorStore
    Ingester -->|"+ domain parse"| Processor
    Ingester -->|"use helper"| FileHandler
    FileHandler --> FileSystem

    Routes -->|"generate summary"| Summarizer
    Summarizer -->|"call embeddings"| VectorStore
    Summarizer -->|"OpenAI request"| OpenAI
    OpenAI -->|"response text"| Summarizer
    Summarizer -->|"create .docx"| FileHandler
    FileHandler --> FileSystem

    Routes -->|"evaluate summary"| Evaluator
    Evaluator -->|"metrics"| Routes

    Routes -->|"serve download"| FileSystem

    %% Click Events
    click Static "https://github.com/akxt09/reports-summarization-for-financial-advisors/blob/main/Code/financial-summarizer/app/static/css/styles.css"
    click Static "https://github.com/akxt09/reports-summarization-for-financial-advisors/blob/main/Code/financial-summarizer/app/static/js/main.js"
    click Templates "https://github.com/akxt09/reports-summarization-for-financial-advisors/blob/main/Code/financial-summarizer/app/templates/index.html"
    click Templates "https://github.com/akxt09/reports-summarization-for-financial-advisors/blob/main/Code/financial-summarizer/app/templates/error.html"
    click Routes "https://github.com/akxt09/reports-summarization-for-financial-advisors/blob/main/Code/financial-summarizer/app/routes.py"
    click Config "https://github.com/akxt09/reports-summarization-for-financial-advisors/blob/main/Code/financial-summarizer/app/config.py"
    click Ingester "https://github.com/akxt09/reports-summarization-for-financial-advisors/blob/main/Code/financial-summarizer/app/services/document_ingester.py"
    click Processor "https://github.com/akxt09/reports-summarization-for-financial-advisors/blob/main/Code/financial-summarizer/app/services/financial_processor.py"
    click Summarizer "https://github.com/akxt09/reports-summarization-for-financial-advisors/blob/main/Code/financial-summarizer/app/services/summary_generator.py"
    click Evaluator "https://github.com/akxt09/reports-summarization-for-financial-advisors/blob/main/Code/financial-summarizer/app/services/raga_evaluator.py"
    click FileHandler "https://github.com/akxt09/reports-summarization-for-financial-advisors/blob/main/Code/financial-summarizer/app/utils/file_handler.py"
    click FileSystem "https://github.com/akxt09/reports-summarization-for-financial-advisors/blob/main/Code/financial-summarizer/run.py"
    click VectorStore "https://github.com/akxt09/reports-summarization-for-financial-advisors/blob/main/Code/financial-summarizer/requirements.txt"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#4A90E2,stroke-width:1px;
    classDef backend fill:#DFF7E0,stroke:#3BA55D,stroke-width:1px;
    classDef service fill:#E8F5E9,stroke:#66BB6A,stroke-width:1px;
    classDef storage fill:#FFF9C4,stroke:#FBC02D,stroke-width:1px;
    classDef external fill:#FFEBEE,stroke:#E53935,stroke-width:1px;
```
