# sam-92/datainsightchatbot architecture

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

- Interactive diagram: https://gitdiagram.com/sam-92/datainsightchatbot
- Repository: https://github.com/sam-92/datainsightchatbot

## Overview

##### Project type and purpose
- This is a full-stack data-analysis chatbot built with Streamlit on the front end and Python “agents” on the back end. It interprets natural-language queries into SQL and Python code, runs them against a dataset (PostgreSQL in production or SQLite locally), and returns visualizations to the user. LangChain and OpenAI power the NLP layers.

##### File structure
- Top level:
- app.py            → Streamlit entry point, navigation between pages
- .streamlit/       → Streamlit config for theming and deployment
- Procfile          → Heroku deployment
- requirements.txt, pyproject.toml → dependencies
- pages/            → Streamlit “pages” (service overview + chatbot UI)
- subs/             → core backend modules (agent orchestration, DB connectors, prompt templates, styling, visualization functions)
- Key patterns:
- Single-page/front-controller (app.py) dispatches to sub-pages
- Modular “agent” design: separate concerns (SQL agent / Python agent)
- Configurable DB connection for local vs. cloud

##### README for additional insights
- Confirms architecture:
- Streamlit front end
- LangChain to orchestrate two AI agents (SQL + Python)
- OpenAI’s GPT-4 for NL→SQL/Python
- PostgreSQL (cloud) or SQLite (local) for data
- matplotlib (via Python agent) for plots
- Mentions prompt engineering modules and semantic similarity selector

- Use clear, consistent component labels (e.g., “SQL Agent”, “Python Agent”)
- Blue for frontend components
- Green for backend modules
- Gray for data storage
- Orange for external services
- Yellow for deployment/infrastructure
- Rounded rectangles for microservices or agents

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["Client Browser"]:::frontend

    %% Frontend Layer
    subgraph "Frontend Layer"
        App["Streamlit Application (app.py)"]:::frontend
        IRISH["Irish Data Chatbot Page"]:::frontend
        OVERVIEW["Service Overview Page"]:::frontend
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        AGENT["SQL Agent (agent.py)"]:::backend
        PROMPTS["Prompt Templates & Semantic Selector (prompts.py)"]:::backend
        POST["Python Agent (post_processing.py)"]:::backend
        VIS["Visualization Functions (visualisation.py)"]:::backend
        DBCONN["DB Connection Manager (db_connections.py)"]:::backend
        STYLES["Styles & UI Helpers (styles.py)"]:::backend
    end

    %% Data Storage Layer
    subgraph "Data Storage"
        PG["PostgreSQL (cloud)"]:::db
        SQLITE["SQLite (local)"]:::db
    end

    %% External Services
    OpenAI["OpenAI API (GPT-4)"]:::external

    %% Infrastructure Layer
    subgraph "Infrastructure"
        PROC["Heroku Procfile"]:::infra
        STCONFIG[".streamlit/config.toml"]:::infra
        REQS["requirements.txt"]:::infra
        PYPROJ["pyproject.toml"]:::infra
    end

    %% Data Flows
    User -->|"interacts with"| App
    App -->|"navigates to"| IRISH
    App -->|"navigates to"| OVERVIEW

    IRISH -->|"submits query"| AGENT
    IRISH -->|"submits query"| POST

    AGENT -->|"uses templates"| PROMPTS
    AGENT -->|"requests DB connection"| DBCONN
    DBCONN -->|"connects to"| PG
    DBCONN -->|"connects to"| SQLITE

    AGENT -->|"calls OpenAI"| OpenAI
    PROMPTS -->|"calls OpenAI"| OpenAI

    POST -->|"processes data"| VIS
    VIS -->|"returns visual output"| IRISH

    AGENT -->|"returns SQL results"| IRISH
    POST -->|"returns processed results"| IRISH

    %% Click Events
    click App "https://github.com/sam-92/datainsightchatbot/blob/main/app.py"
    click IRISH "https://github.com/sam-92/datainsightchatbot/blob/main/pages/irish_data_chatbot.py"
    click OVERVIEW "https://github.com/sam-92/datainsightchatbot/blob/main/pages/service_overview.py"
    click PROC "https://github.com/sam-92/datainsightchatbot/tree/main/Procfile"
    click STCONFIG "https://github.com/sam-92/datainsightchatbot/blob/main/.streamlit/config.toml"
    click AGENT "https://github.com/sam-92/datainsightchatbot/blob/main/subs/agent.py"
    click PROMPTS "https://github.com/sam-92/datainsightchatbot/blob/main/subs/prompts.py"
    click POST "https://github.com/sam-92/datainsightchatbot/blob/main/subs/post_processing.py"
    click VIS "https://github.com/sam-92/datainsightchatbot/blob/main/subs/visualisation.py"
    click DBCONN "https://github.com/sam-92/datainsightchatbot/blob/main/subs/db_connections.py"
    click STYLES "https://github.com/sam-92/datainsightchatbot/blob/main/subs/styles.py"
    click REQS "https://github.com/sam-92/datainsightchatbot/blob/main/requirements.txt"
    click PYPROJ "https://github.com/sam-92/datainsightchatbot/blob/main/pyproject.toml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0288D1,color:#000
    classDef backend fill:#E0F7FA,stroke:#00796B,color:#000
    classDef db fill:#F5F5F5,stroke:#616161,color:#000
    classDef external fill:#FFF3E0,stroke:#FB8C00,color:#000
    classDef infra fill:#FFF9C4,stroke:#FBC02D,color:#000
```
