# masteryodaa/sql-agent architecture

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

- Interactive diagram: https://gitdiagram.com/masteryodaa/sql-agent
- Repository: https://github.com/masteryodaa/sql-agent

## Overview

##### Project type and purpose
- This is a lightweight, full‑stack Streamlit application (“app.py”) augmented by an AI agent (“agent.py”) for querying or augmenting data in a local SQLite database (Chinook.db).
- The app is packaged for reproducible local development using a VS Code devcontainer (.devcontainer/) and holds secrets in .streamlit/secrets.toml.

##### File structure
- Top‑level files
– app.py            → Streamlit entry‑point (presentation + orchestration)
– agent.py          → AI/LLM logic module (business logic)
– Chinook.db        → SQLite database (data layer)
– requirements.txt  → Python dependency list
– readme.md         → install instructions + screenshots
- Config directories
– .devcontainer/    → dev environment (Docker + VS Code)
– .streamlit/       → Streamlit config & secrets (e.g. API keys)
- Supporting assets
– screenshots/      → UI examples

##### Detail
- Don’t lump agent.py and app.py together—keep business logic and presentation distinct.
- Flow of secrets from .streamlit/secrets.toml into both the UI and agent modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global User
    User["User (Web Browser)"]:::user

    %% Devcontainer Boundary
    subgraph "Devcontainer Environment" 
        direction TB
        UI["Streamlit UI (app.py)"]:::ui
        Agent["Agent Module (agent.py)"]:::agent
        DB["SQLite Database (Chinook.db)"]:::db
        Secrets["Secrets Store (.streamlit/secrets.toml)"]:::secret
        DevConfig["Devcontainer Config (devcontainer.json)"]:::config
        Req["Dependencies (requirements.txt)"]:::config
        Readme["Documentation (readme.md)"]:::config
        Assets["UI Example Assets (screenshots/)"]:::config
    end

    %% External Service
    ExtAI["External AI Service (OpenAI API)"]:::external

    %% Connections
    User -->|"User input"| UI
    UI -->|"passes user query"| Agent
    Agent -->|"runs SQL query"| DB
    DB -->|"returns result set"| Agent
    Agent -->|"calls completions API"| ExtAI
    ExtAI -->|"AI response"| Agent
    Agent -->|"processed data"| UI
    UI -->|"renders charts/tables/text"| User
    Secrets --> UI
    Secrets --> Agent

    %% Click Events
    click UI "https://github.com/masteryodaa/sql-agent/blob/main/app.py"
    click Agent "https://github.com/masteryodaa/sql-agent/blob/main/agent.py"
    click DB "https://github.com/masteryodaa/sql-agent/blob/main/Chinook.db"
    click Secrets "https://github.com/masteryodaa/sql-agent/blob/main/.streamlit/secrets.toml"
    click DevConfig "https://github.com/masteryodaa/sql-agent/blob/main/.devcontainer/devcontainer.json"
    click Req "https://github.com/masteryodaa/sql-agent/blob/main/requirements.txt"
    click Readme "https://github.com/masteryodaa/sql-agent/blob/main/readme.md"
    click Assets "https://github.com/masteryodaa/sql-agent/tree/main/screenshots/"

    %% Styles
    classDef user fill:#f2f2f2,stroke:#666,stroke-width:1px
    classDef ui fill:#cceeff,stroke:#3399cc,stroke-width:2px
    classDef agent fill:#ccffcc,stroke:#33cc33,stroke-width:2px
    classDef db fill:#ffcc66,stroke:#cc9933,stroke-width:2px,stroke-dasharray: 5 5
    classDef external fill:#cc99ff,stroke:#9966cc,stroke-width:2px,stroke-dasharray: 2 2
    classDef config fill:#eeeeee,stroke:#aaaaaa,stroke-width:1px
    classDef secret fill:#ffcccc,stroke:#cc6666,stroke-width:1px
```
