# dhruvatreja/datavisualization_langgraph architecture

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

- Interactive diagram: https://gitdiagram.com/dhruvatreja/datavisualization_langgraph
- Repository: https://github.com/dhruvatreja/datavisualization_langgraph

## Overview

##### Project Type & Purpose
- This is a full-stack application focused on bridging natural language queries to data visualizations using SQL. It integrates a LangGraph-based AI agent that interprets user input, dynamically generates SQL queries, executes them on a SQLite (or CSV-converted) database, and then returns visual visualizations through a streaming API.
- The project uses LangGraph Studio for orchestration and offers two back-end implementations (JavaScript and Python) along with a dedicated SQLite server (handling uploads and query execution).

##### Analyzing the File Structure
- Top-level components include:
- frontend: A Next.js React-based application that provides the user interface, handles file uploads, and displays visualizations.
- backend_js and backend_py: Two implementations of the back-end logic (node and Python) that define the core LangGraph agent. These folders include key modules/nodes (DataFormatter, DatabaseManager, LLMManager, SQLAgent, WorkflowManager, etc.) that map directly to the steps in the agent workflow.
- sqlite_server: A standalone service responsible for handling database file (SQLite, CSV) uploads, storing files, and providing schema information.
- Config files (like package.json, tsconfig.json, .env.example) across these directories indicate the presence of containerized deployments, dependency management, and environment variable configurations.

##### Detailed Architecture Breakdown & Key Components
A. Frontend:
- Located in the “frontend” directory with components (e.g., Logo, UploadButton, several graph components).
- It communicates with the LangGraph API via a URL defined in its .env file.
- It fetches visualizations and workflow traces through a streaming API.
- How front-end connects to both the LangGraph backend (for query processing) and indirectly to the SQLite server (for file/data upload).

B. Backend:
- Two implementations: backend_js (JavaScript/TypeScript) and backend_py (Python). Both implement the LangGraph agent.
- Key modules within the my_agent folder correspond to nodes in the agent’s workflow:
- Parse Question: Analyzes the natural language query along with database schema.
- Get Unique Nouns: Extracts specific data values from non-numeric fields to refine the query.
- Generate SQL: Creates SQL based on the question and extracted data.
- Validate and Fix SQL: Ensures correctness of query syntax and table/column names.
- Execute SQL: Carries out the query on a SQLite database.
- Choose Visualization: Uses an LLM to select an appropriate chart type (bar, line, scatter, etc.).
- Format Results & Format Data for Visualization: Prepares the data both in textual and graphical formats.
- The LangGraph agent architecture is containerized via LangGraph Studio, which packages these modules and provides a URL for API access.

C. SQLite Server:
- This component handles file uploads (under 1MB) and manages the SQLite databases.
- It includes routing (see ProjectRoutes.js) and maintains storage (sqlite_server/uploads) for user-uploaded databases.
- It acts as an intermediary, allowing the backend to execute queries on the appropriate database instance.

D. External/Orchestration Components:
- LangGraph Studio: Acts as the orchestration layer to run the LangGraph API in a containerized environment. It manages environment variables (e.g., OPENAI_API_KEY, DB_ENDPOINT_URL), connects the backend agent with the SQLite server, and provides a visual interface for monitoring agent state.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    U("User"):::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE("Frontend UI (React/Next.js)"):::frontend
    end

    %% Orchestration Layer
    subgraph "LangGraph Studio"
        LS("LangGraph Studio Orchestrator"):::orchestration
    end

    %% Backend Implementation Options
    subgraph "Backend Agents"
        BJS("Backend JS Agent"):::backend
        BPY("Backend Py Agent"):::backend
    end

    %% LangGraph Agent Workflow
    subgraph "LangGraph Agent Workflow"
        PQ("Parse Question"):::agent
        GUN("Get Unique Nouns"):::agent
        GS("Generate SQL"):::agent
        VF("Validate_and_Fix_SQL"):::agent
        ES("Execute SQL"):::agent
        FR("Format Results"):::agent
        FD("Format_Data_for_Visualization"):::agent
        VO("Visualization Output"):::agent
    end

    %% SQLite Server Layer
    subgraph "SQLite Server"
        SS("SQLite Server (Uploads & Query Execution)"):::database
    end

    %% Data Flow
    U -->|"interacts"| FE
    FE -->|"sends query"| LS
    FE -->|"file upload"| SS

    LS -->|"routes request"| BJS
    LS -->|"routes request"| BPY

    BJS -->|"initiates agent"| PQ
    BPY -->|"initiates agent"| PQ

    PQ -->|"processes"| GUN
    GUN -->|"processes"| GS
    GS -->|"processes"| VF
    VF -->|"processes"| ES

    ES -->|"executes query"| SS
    SS -->|"returns data"| ES

    ES -->|"formats data"| FR
    ES -->|"formats data"| FD
    FR -->|"merges"| VO
    FD -->|"merges"| VO

    VO -->|"sends visualization"| FE

    %% Click Events
    click FE "https://github.com/dhruvatreja/datavisualization_langgraph/tree/main/frontend/src/components"
    click BJS "https://github.com/dhruvatreja/datavisualization_langgraph/tree/main/backend_js/my_agent"
    click BPY "https://github.com/dhruvatreja/datavisualization_langgraph/blob/main/backend_py/my_agent/main.py"
    click SS "https://github.com/dhruvatreja/datavisualization_langgraph/blob/main/sqlite_server/routes/ProjectRoutes.js"
    click LS "https://github.com/dhruvatreja/datavisualization_langgraph/blob/main/backend_js/langgraph.json"

    %% Styles
    classDef external fill:#E0E0E0,stroke:#000,stroke-width:1px;
    classDef frontend fill:#AEDFF7,stroke:#0077B6,stroke-width:2px;
    classDef orchestration fill:#FFE5A0,stroke:#FF9F1C,stroke-width:2px;
    classDef backend fill:#C3F0CA,stroke:#2D6A4F,stroke-width:2px;
    classDef agent fill:#F6E7CB,stroke:#E29578,stroke-width:2px;
    classDef database fill:#F9C0C0,stroke:#D90429,stroke-width:2px;
```
