# abdullahsezdi/happyllm architecture

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

- Interactive diagram: https://gitdiagram.com/abdullahsezdi/happyllm
- Repository: https://github.com/abdullahsezdi/happyllm

## Overview

##### Project type and purpose
- HappyLLM is a Python-based, LLM-enabled data-analysis platform built on Streamlit.
- It provides an interactive UI for well-being and happiness analysis of countries via a multi-agent LLM system (Data Analysis Agent, Causal Analysis Agent, General Q&A Agent).

##### File structure
- Top-level:
- .devcontainer/ – development container config
- README.md, requirements.txt – project metadata
- src/ – application code and data
- src/ contains:
- ana_script.py – Streamlit entry point & orchestration layer
- llm_agents.py – definitions of the three LLM agents
- cleaned_dataset.csv – the well-being data store

##### README insights
- Streamlit is used as the UI framework.
- Google API is called for LLM inference.
- Key features: multi-agent architecture, interactive charts, natural-language queries.

##### Main components and their interactions
a. Frontend (Presentation Layer)
– Component: Streamlit UI (ana_script.py)
– Responsibility: accept user queries, render visualizations and tables
b. Orchestration / Business Logic
– Component: Controller in ana_script.py
– Responsibility: route user requests to the correct LLM agent
c. Agents (Compute Layer)
– Components in llm_agents.py:
- Data Analysis Agent
- Causal Analysis Agent
- General Q&A Agent
– Responsibility: generate prompts, call Google LLM API, post-process responses
d. Data Store
– Component: cleaned_dataset.csv
– Responsibility: hold well-being metrics used by Data Analysis Agent for charting
e. External Service
– Component: Google LLM API
– Responsibility: perform model inference
f. Visualization Module
– Implicit in ana_script.py via Streamlit’s charting libraries

##### Architectural patterns and design principles
- Multi-agent pattern: each agent encapsulates a distinct analysis responsibility
- Layered separation: Presentation (UI), Business (orchestration), Compute (agents), Data (CSV), External Services
- Single-page application style using Streamlit’s reactive model

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        User["User"]:::external
        StreamlitUI["Streamlit UI\n(visualizations via Streamlit)"]:::frontend
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        Controller["Query Router / Controller"]:::business
    end

    %% Agent Layer
    subgraph "Agent Layer"
        direction TB
        DataAnalysisAgent["Data Analysis Agent"]:::business
        CausalAnalysisAgent["Causal Analysis Agent"]:::business
        GeneralQAAAAgent["General Q&A Agent"]:::business
    end

    %% Data & External Services
    subgraph "Data & External"
        direction TB
        CleanedDataset[("cleaned_dataset.csv")]:::data
        GoogleLLM["Google LLM API"]:::external
    end

    %% Metadata & Config
    subgraph "Project Info"
        direction TB
        README["README.md"]:::metadata
        Requirements["requirements.txt"]:::metadata
        EnvConfig[".devcontainer/devcontainer.json"]:::metadata
    end

    %% Connections
    User -->|"submits query"| StreamlitUI
    StreamlitUI -->|"routes request"| Controller
    Controller -->|"LLM prompt →"| DataAnalysisAgent
    Controller -->|"LLM prompt →"| CausalAnalysisAgent
    Controller -->|"LLM prompt →"| GeneralQAAAAgent
    DataAnalysisAgent -->|"reads data"| CleanedDataset
    DataAnalysisAgent <-->|"LLM call ↔"| GoogleLLM
    CausalAnalysisAgent <-->|"LLM call ↔"| GoogleLLM
    GeneralQAAAAgent <-->|"LLM call ↔"| GoogleLLM
    DataAnalysisAgent -->|"response →"| Controller
    CausalAnalysisAgent -->|"response →"| Controller
    GeneralQAAAAgent -->|"response →"| Controller
    Controller -->|"renders output"| StreamlitUI

    %% Click Events
    click StreamlitUI "https://github.com/abdullahsezdi/happyllm/blob/main/src/ana_script.py"
    click Controller "https://github.com/abdullahsezdi/happyllm/blob/main/src/ana_script.py"
    click DataAnalysisAgent "https://github.com/abdullahsezdi/happyllm/blob/main/src/llm_agents.py"
    click CausalAnalysisAgent "https://github.com/abdullahsezdi/happyllm/blob/main/src/llm_agents.py"
    click GeneralQAAAAgent "https://github.com/abdullahsezdi/happyllm/blob/main/src/llm_agents.py"
    click CleanedDataset "https://github.com/abdullahsezdi/happyllm/blob/main/src/cleaned_dataset.csv"
    click EnvConfig "https://github.com/abdullahsezdi/happyllm/blob/main/.devcontainer/devcontainer.json"
    click README "https://github.com/abdullahsezdi/happyllm/blob/main/README.md"
    click Requirements "https://github.com/abdullahsezdi/happyllm/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#D6E4FF,stroke:#0366d6,stroke-width:1px;
    classDef business fill:#DFF8E4,stroke:#28a745,stroke-width:1px;
    classDef data fill:#FFF3CD,stroke:#d39e00,stroke-width:1px;
    classDef external fill:#F8D7DA,stroke:#d73a49,stroke-width:1px;
    classDef metadata fill:#E2E3E5,stroke:#6c757d,stroke-width:1px;
```
