# komalsai234/llm-powered-employee-insights architecture

> Architecture diagram of the GitHub repository komalsai234/llm-powered-employee-insights, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/komalsai234/llm-powered-employee-insights
- Repository: https://github.com/komalsai234/llm-powered-employee-insights

## Overview

##### Project type and purpose
- This is a full-stack, LLM-powered employee information retrieval system.
- Frontend: Streamlit UI (`app.py`)
- Backend: FastAPI service (`backend/api.py` + helper modules)
- Data store: relational database populated via SQL script (`data/employee_db.sql`)
- External AI service: Groq API for natural-language→SQL translation and summarization

##### File structure
- Top-level:
- `app.py` → Streamlit application entry point
- `config.py` → all runtime settings (DB URL, Groq API keys, etc.)
- `requirements.txt` → Python dependencies (Streamlit, FastAPI, HTTPX, SQL drivers)
- `data/employee_db.sql` → DDL/DML to set up and seed the employee database
- `backend/` directory:
- `api.py` → FastAPI app exposing endpoints for queries
- `db.py` → database connection and session management
- `groq_handler.py` → orchestrates calls to Groq API to generate SQL and summaries
- `query_executor.py` → executes SQL against the DB and returns raw results

##### README for additional insights
1. User enters natural-language query in the Streamlit UI
2. UI forwards query to FastAPI backend
3. Backend uses `groq_handler` → Groq endpoint → generates SQL
4. `query_executor` runs SQL via `db.py` → fetches rows
5. Optionally, `groq_handler` summarizes the result
6. API returns structured data to UI for display

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        User["User"]:::external
        Streamlit["Streamlit UI (app.py)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Config["Configuration Module"]:::backend
        API["FastAPI Service<br/>(/query endpoint)"]:::backend
        LLM["LLM Adapter<br/>(Groq Handler)"]:::backend
        SQLExec["SQL Executor"]:::backend
        DBConn["Database Connector"]:::backend
    end

    %% External & Data
    subgraph "External & Data"
        direction TB
        Groq["Groq AI Service"]:::external
        DB["Employee DB"]:::datastore
        Seed["DB Seed Script"]:::datastore
    end

    %% Connections
    User -->|"enters query"| Streamlit
    Streamlit -->|"POST /query"| API
    API -->|"calls"| LLM
    LLM -->|"HTTP request"| Groq
    Groq -->|"returns SQL/summaries"| LLM
    LLM -->|"provides SQL"| SQLExec
    SQLExec -->|"executes via"| DBConn
    DBConn -->|"runs SQL"| DB
    DB -->|"returns rows"| DBConn
    DBConn -->|"returns results"| SQLExec
    SQLExec -->|"results"| API
    API -->|"JSON response"| Streamlit
    Streamlit -->|"renders answer"| User

    %% Optional seed
    Seed -.->|"initializes"| DB

    %% Config injections
    Config --> API
    Config --> LLM
    Config --> SQLExec
    Config --> DBConn

    %% Click Events
    click Streamlit "https://github.com/komalsai234/llm-powered-employee-insights/blob/main/app.py"
    click Config "https://github.com/komalsai234/llm-powered-employee-insights/blob/main/config.py"
    click API "https://github.com/komalsai234/llm-powered-employee-insights/blob/main/backend/api.py"
    click LLM "https://github.com/komalsai234/llm-powered-employee-insights/blob/main/backend/groq_handler.py"
    click SQLExec "https://github.com/komalsai234/llm-powered-employee-insights/blob/main/backend/query_executor.py"
    click DBConn "https://github.com/komalsai234/llm-powered-employee-insights/blob/main/backend/db.py"
    click Seed "https://github.com/komalsai234/llm-powered-employee-insights/blob/main/data/employee_db.sql"
    click Requirements "https://github.com/komalsai234/llm-powered-employee-insights/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#D0E7FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#E6FDFD,stroke:#00A36C,color:#0366d6
    classDef external fill:#FFF4E5,stroke:#FF8C00,color:#FF8C00
    classDef datastore fill:#F0F0F0,stroke:#666666,color:#666666
    class Requirements internal
    click Requirements "https://github.com/komalsai234/llm-powered-employee-insights/blob/main/requirements.txt"
```
