# ombhojane/dbrx-nexus architecture

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

- Interactive diagram: https://gitdiagram.com/ombhojane/dbrx-nexus
- Repository: https://github.com/ombhojane/dbrx-nexus

## Overview

##### Project type and purpose
- This is a single‐service conversational AI web application built with Streamlit.
- It accepts natural‐language queries, translates them into SQL via an LLM (Google Gemini), executes against a local SQLite database, then formats and returns the result conversationally.

##### File structure
- Top‐level files:
- app.py – contains both the Streamlit UI and the orchestration logic (NLU, SQL generation, database calls, response formatting).
- create_database.py – one‐off script to populate `phones.db`.
- phones.db – the SQLite database file.
- style.css – custom styling for the Streamlit UI.
- .env – holds GEMINI_API_KEY for Google Generative AI.
- requirements.txt – Python dependencies (streamlit, sqlite3, google-generativeai).

##### Key architecture details from the README
- Streamlit provides the interactive UI layer.
- Google’s Generative AI (via GEMINI_API_KEY) is the external LLM service.
- SQLite is the local datastore.
- Data flow: User → NLU (LLM) → SQL → SQLite → formatting (LLM) → UI.

##### Main components and their relationships
a. Components
1. Streamlit UI (app.py + style.css)
2. Conversational AI module
- NL Parser / SQL Generator (calls Google Gemini API)
- Response Formatter (also uses LLM)
3. Local SQLite Database (phones.db)
4. Database‐setup script (create_database.py) – optional/off‐line
5. External LLM service (Google Generative AI via GEMINI_API_KEY)
b. Interactions
- User enters text in the Streamlit UI.
- app.py sends input to the NL Parser, which invokes the external LLM API to generate an SQL query.
- app.py executes the SQL against phones.db via sqlite3.
- Raw results are passed to the Response Formatter, which again calls the LLM to turn rows into natural‐language.
- The formatted answer is rendered back in the UI.

##### Architectural patterns & principles
- Monolithic service with clear logical layers (Presentation, Business Logic, Data Access).
- Separation of concerns: UI styling (style.css), orchestration (app.py), data layer (phones.db).
- External dependency isolation: LLM calls abstracted into functions in app.py.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Streamlit UI"]:::ui
        Style["style.css"]:::ui
    end

    %% Logic Layer
    subgraph "Logic Layer"
        SQL["SQL Generator"]:::logic
        RF["Response Formatter"]:::logic
    end

    %% Data Layer
    subgraph "Data Layer"
        DB[(SQLite Database)]:::data
        Init["create_database.py"]:::data
    end

    %% Configuration & Dependencies
    subgraph "Configuration & Dependencies"
        Env[".env"]:::external
        Req["requirements.txt"]:::external
    end

    %% External Service
    Ext(("Google Generative AI")):::external

    %% Data Flows
    UI -->|"User query (text)"| SQL
    SQL -->|"Prompt for SQL"| Ext
    Ext -->|"Generated SQL"| SQL
    SQL -->|"Execute SQL"| DB
    DB -->|"Query results"| SQL
    SQL -->|"Raw results"| RF
    RF -->|"Prompt for response"| Ext
    Ext -->|"Formatted response"| RF
    RF -->|"Display answer"| UI

    %% DB Initialization Flow
    Init -->|"Populate DB"| DB

    %% Click Events
    click UI "https://github.com/ombhojane/dbrx-nexus/blob/main/app.py"
    click Style "https://github.com/ombhojane/dbrx-nexus/blob/main/style.css"
    click SQL "https://github.com/ombhojane/dbrx-nexus/blob/main/app.py"
    click RF "https://github.com/ombhojane/dbrx-nexus/blob/main/app.py"
    click DB "https://github.com/ombhojane/dbrx-nexus/blob/main/phones.db"
    click Init "https://github.com/ombhojane/dbrx-nexus/blob/main/create_database.py"
    click Env "https://github.com/ombhojane/dbrx-nexus/blob/main/.env"
    click Req "https://github.com/ombhojane/dbrx-nexus/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef logic fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef data fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
