# boulkadi/finance_analysis_cih architecture

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

- Interactive diagram: https://gitdiagram.com/boulkadi/finance_analysis_cih
- Repository: https://github.com/boulkadi/finance_analysis_cih

## Overview

##### Project Type and Purpose
- Finance_Analysis_CIH is a full-stack, data-centric, interactive analytics application built in Python with Streamlit as the UI layer.
- It ingests PDF financial reports from Banque CIH, extracts and cleans tabular/text data, visualizes trends, and provides an AI-powered Q&A interface using LangChain (with Google Generative AI and Hugging Face backends).

##### File Structure Analysis
- Top-level “stream.py”: the main Streamlit app orchestrating UI, data loading, analysis, visualization, and AI queries.
- “rapports_CIH/”: raw PDF inputs (2013–2024).
- “output/”: processed CSV/text outputs.
- “.streamlit/secrets.toml”: credentials for external AI APIs.
- “requirements.txt”: dependencies (Streamlit, LangChain, PDF parsers, plotting libs).
- “test.ipynb”: exploratory notebook likely for prototyping extraction/analysis.

##### Core Components
a. Streamlit Frontend
- UI widgets (file selector, parameters, chart panels, Q&A chat).
- Initiates user actions (upload, select report, ask question).
b. PDF Ingestion & Extraction Module
- Locates PDFs in rapports_CIH/.
- Uses a PDF parser (e.g., pdfplumber or PyPDF2) + text cleaners to produce raw text/tables.
c. Data Processing & Cleaning Module
- Cleans, normalizes, aggregates financial tables.
- Writes intermediate CSV/text to output/.
d. Visualization Module
- Leverages Plotly/Matplotlib/Altair via Streamlit to render interactive charts and tables.
e. AI Q&A Module (LangChain)
- Loads cleaned text segments.
- Sends context + user query to LLM endpoints (Google GenAI / HuggingFace).
- Receives answer and streams back to UI.
f. External Services
- Google Generative AI API
- Hugging Face Inference API
g. Storage
- Local filesystem for PDFs & CSVs
- .streamlit/secrets.toml for credentials

##### Relationships and Data Flow
- User → Streamlit UI
- UI → PDF Ingestion → Extraction → Data Processing
- Processed data → Storage & Visualization
- User Q&A → AI Q&A Module → External LLM APIs → Response → UI

##### Architectural Patterns and Principles
- Monolithic modular structure: one Python service subdivided into logical modules.
- Separation of concerns: ingestion, processing, visualization, AI querying.
- Extensibility points: swapping PDF parsers or LLM backends via config.
- Configuration management via .streamlit/secrets.toml.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Local Application Modules
    subgraph "Local Application"
        UI["Streamlit Frontend\n(stream.py)"]:::frontend
        Ingest["PDF Ingestion & Extraction\n(pdfplumber/PyPDF2)"]:::module
        Process["Data Processing & Cleaning\n(Pandas/Numpy)"]:::module
        Visual["Visualization\n(Plotly/Altair)"]:::module
        AI["AI Q&A Module\n(LangChain)"]:::module
    end

    %% Storage Components
    subgraph "Storage"
        RawFS["Raw PDF Storage\n(rapports_CIH/)"]:::storage
        ProcFS["Processed Data Storage\n(output/)"]:::storage
        Secrets["AI Credentials\n(.streamlit/secrets.toml)"]:::storage
    end

    %% External Services
    subgraph "External Services"
        Google(("Google Generative AI")):::cloud
        HF(("Hugging Face Inference API")):::cloud
    end

    %% Supporting Files
    subgraph "Project Files"
        Requirements["Dependencies\n(requirements.txt)"]:::infra
        Notebook["Exploratory Notebook\n(test.ipynb)"]:::infra
    end

    %% Data Flow
    RawFS -->|provides PDFs| Ingest
    UI -->|upload/select report| Ingest
    Ingest -->|raw text/tables| Process
    Process -->|writes CSV/text| ProcFS
    Process -->|data| Visual
    Visual -->|renders charts| UI

    UI -->|ask question| AI
    Secrets -->|API keys| AI
    AI -->|query| Google
    AI -->|query| HF
    Google -->|response| AI
    HF -->|response| AI
    AI -->|answer| UI

    %% Click Events
    click UI "https://github.com/boulkadi/finance_analysis_cih/blob/main/stream.py"
    click Ingest "https://github.com/boulkadi/finance_analysis_cih/tree/main/rapports_CIH/"
    click RawFS "https://github.com/boulkadi/finance_analysis_cih/tree/main/rapports_CIH/"
    click ProcFS "https://github.com/boulkadi/finance_analysis_cih/tree/main/output/"
    click Process "https://github.com/boulkadi/finance_analysis_cih/tree/main/output/"
    click Visual "https://github.com/boulkadi/finance_analysis_cih/blob/main/stream.py"
    click AI "https://github.com/boulkadi/finance_analysis_cih/blob/main/stream.py"
    click Secrets "https://github.com/boulkadi/finance_analysis_cih/blob/main/.streamlit/secrets.toml"
    click Requirements "https://github.com/boulkadi/finance_analysis_cih/blob/main/requirements.txt"
    click Notebook "https://github.com/boulkadi/finance_analysis_cih/blob/main/test.ipynb"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#21618C,color:#1B2631;
    classDef module fill:#A9DFBF,stroke:#196F3D,color:#1B2631;
    classDef storage fill:#F9E79F,stroke:#B9770E,color:#1B2631;
    classDef cloud fill:#E8DAEF,stroke:#7D3C98,color:#1B2631,stroke-dasharray: 5 5;
    classDef infra fill:#E5E7E9,stroke:#566573,color:#1B2631;
```
