# causalinferencelab/lang2sql architecture

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

- Interactive diagram: https://gitdiagram.com/causalinferencelab/lang2sql
- Repository: https://github.com/causalinferencelab/lang2sql

## Overview

##### Project type and purpose
- Lang2SQL is an open-source, full-stack Python tool that converts natural-language queries into optimized SQL, leverages DataHub metadata, vector search (FAISS/pgvector), and presents results via a Streamlit web UI (plus CLI).

##### File structure
- Top-level “cli” and “interface” directories (presentation layer)
- “engine” and “llm_utils” directories (core business logic / LLM orchestration)
- “data_utils” (DataHub API clients) and “db_utils” (DB connectors) (integration/adapters)
- “viz” (visualization components)
- “infra” (deployment scripts, monitoring, observability)
- Docker files and GitHub Actions workflows for containerization and CI/CD

##### README insights
- Four logical stages: NLP → table search (vector DB) → SQL generation → visualization
- Tech stack: LangGraph for LLM workflows, DataHub for metadata, Streamlit for UI
- CLI commands and environment config

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        CLI["CLI Module"]:::presentation
        Streamlit["Streamlit Web UI"]:::presentation
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        GraphBuilder["Graph Builder"]:::orchestration
        LangGraph["LangGraph Workflows"]:::orchestration
    end

    %% Core Engine Layer
    subgraph "Core Engine"
        direction TB
        QueryExec["Query Executor"]:::core
    end

    %% LLM & Prompting
    subgraph "LLM & Prompting"
        direction TB
        Prompts["Prompt Templates"]:::prompting
        LLMFactory["LLM Factory"]:::prompting
        ResponseParser["LLM Response Parser"]:::prompting
    end

    %% Integration Layer
    subgraph "Integration Adapters"
        direction TB
        subgraph "Metadata Integration"
            DataHub["DataHub Services"]:::integration
        end
        subgraph "Vector Search Integration"
            VectorDB["VectorDB Connectors"]:::integration
        end
        subgraph "Database Connectors"
            DBConnectors["DB Connectors"]:::integration
        end
    end

    %% Visualization
    subgraph "Visualization"
        direction TB
        Chart["Chart Display"]:::viz
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        DockerInfra["Docker & Compose"]:::infra
        Monitoring["Monitoring"]:::infra
        Observability["Observability"]:::infra
    end

    %% User
    User["User"]:::external

    %% Data Flow
    User -->|uses| CLI
    User -->|uses| Streamlit

    CLI -->|triggers| GraphBuilder
    Streamlit -->|calls| GraphBuilder

    GraphBuilder -->|orchestrates| LangGraph
    LangGraph -->|fetch metadata| DataHub
    LangGraph -->|semantic search| VectorDB
    LangGraph -->|load prompts| Prompts
    LangGraph -->|invoke LLM| LLMFactory
    LLMFactory -->|parse response| ResponseParser
    ResponseParser -->|SQL query| QueryExec

    QueryExec -->|executes SQL| DBConnectors
    DBConnectors -->|returns rows| QueryExec
    QueryExec -->|results| Chart
    Chart -->|renders| Streamlit

    %% Telemetry
    CLI -->|emit metrics| Monitoring
    Streamlit -->|emit metrics| Observability
    GraphBuilder -->|emit logs| Observability
    QueryExec -->|emit logs| Monitoring

    %% Containerization
    CLI -->|containerized by| DockerInfra
    Streamlit -->|containerized by| DockerInfra
    GraphBuilder -->|containerized by| DockerInfra
    QueryExec -->|containerized by| DockerInfra

    %% Click Events
    click CLI "https://github.com/causalinferencelab/lang2sql/tree/master/cli/"
    click Streamlit "https://github.com/causalinferencelab/lang2sql/blob/master/interface/streamlit_app.py"
    click GraphBuilder "https://github.com/causalinferencelab/lang2sql/blob/master/interface/graph_builder.py"
    click LangGraph "https://github.com/causalinferencelab/lang2sql/blob/master/llm_utils/chains.py"
    click QueryExec "https://github.com/causalinferencelab/lang2sql/blob/master/engine/query_executor.py"
    click Prompts "https://github.com/causalinferencelab/lang2sql/tree/master/prompt/"
    click LLMFactory "https://github.com/causalinferencelab/lang2sql/blob/master/llm_utils/llm/factory.py"
    click ResponseParser "https://github.com/causalinferencelab/lang2sql/blob/master/llm_utils/llm_response_parser.py"
    click DataHub "https://github.com/causalinferencelab/lang2sql/tree/master/data_utils/datahub_services/"
    click VectorDB "https://github.com/causalinferencelab/lang2sql/tree/master/llm_utils/vectordb/"
    click DBConnectors "https://github.com/causalinferencelab/lang2sql/tree/master/db_utils/"
    click Chart "https://github.com/causalinferencelab/lang2sql/blob/master/viz/display_chart.py"
    click DockerInfra "https://github.com/causalinferencelab/lang2sql/tree/master/docker/"
    click Monitoring "https://github.com/causalinferencelab/lang2sql/tree/master/infra/monitoring/"
    click Observability "https://github.com/causalinferencelab/lang2sql/tree/master/infra/observability/"

    %% Styles
    classDef presentation fill:#FFA500,stroke:#333,stroke-width:1px
    classDef orchestration fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef prompting fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef integration fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef viz fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#FFFFFF,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
