# aditya-singh-3112/llm_dbms_v2 architecture

> Architecture diagram of the GitHub repository aditya-singh-3112/llm_dbms_v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aditya-singh-3112/llm_dbms_v2
- Repository: https://github.com/aditya-singh-3112/llm_dbms_v2

## Overview

LLM-Powered DBMS lets users register and share tenant-isolated Postgres databases, then ask questions in natural language and receive streamed, SQL-backed answers. The principal path runs from the browser’s Ask page through the ask API and a tool-using agent to guarded database tools; conversation memory, optional textbook grounding, and write confirmation support that flow. Separate branches cover authentication, database administration, file import/export, and sharing. Edges reflect shown excerpts, SOURCE INDEX references, or README claims; unsampled subsystem wiring is omitted or marked unverified.

Main entry points: [`frontend/src/api.js`](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/frontend/src/api.js) (API client), [`app/main.py`](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/main.py) (API runtime), [`app/api/ask.py`](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/api/ask.py) (Question routes), [`app/services/mcp_tools.py`](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/mcp_tools.py) (Database tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser application"]
  node_ask_ui["Ask workflow<br/>[AskPage.jsx]"]
  node_turn_ui["Answer display<br/>[TurnCard.jsx]"]
  node_db_ui["Database workspace<br/>[DatabasesPage.jsx]"]
  node_import_ui["Import dialog<br/>[ImportModal.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["HTTP API"]
  node_auth_api["Authentication routes<br/>[auth.py]"]
  node_database_api["Database routes<br/>[databases.py]"]
  node_ask_api["Question routes<br/>[ask.py]"]
  node_tables_api["Tables routes<br/>[tables.py]"]
  node_export_api["Export routes<br/>[export.py]"]
end

subgraph group_services["Domain services"]
  node_auth_service["Auth service<br/>[auth.py]"]
  node_registry["Database registry"]
  node_agent["SQL agent<br/>[agent_factory.py]"]
  node_tool_adapter["Agent tool adapter"]
  node_mcp_tools["Database tools<br/>[mcp_tools.py]"]
  node_sql_guard["SQL validation<br/>[sql_validator.py]"]
  node_executor["Postgres executor"]
  node_conversations["Conversation memory"]
  node_rag["Textbook retrieval<br/>[rag_service.py]"]
  node_import_service["File import<br/>[import_service.py]"]
  node_export_service["File export<br/>[export_service.py]"]
end

subgraph group_runtime["Runtime and stores"]
  node_app_runtime["API runtime<br/>[main.py]"]
  node_database_manager["Database manager<br/>[database.py]"]
  node_mongo[("MongoDB")]
  node_postgres[("Postgres tenants")]
  node_redis[("Redis cache")]
end

node_user(("User"))
node_gemini["Gemini models"]

node_user -->|"asks question"| node_ask_ui
node_ask_ui -->|"submits request"| node_api_client
node_ask_ui -->|"renders turns"| node_turn_ui
node_api_client -->|"calls API"| node_ask_api
node_user -->|"manages databases"| node_db_ui
node_db_ui -->|"requests database actions"| node_api_client
node_db_ui -.->|"opens import"| node_import_ui
node_api_client -->|"calls API"| node_auth_api
node_api_client -->|"calls API"| node_database_api
node_api_client -.->|"calls API"| node_tables_api
node_api_client -.->|"calls API"| node_export_api
node_app_runtime -->|"registers route"| node_ask_api
node_app_runtime -->|"registers route"| node_auth_api
node_app_runtime -->|"registers route"| node_database_api
node_app_runtime -->|"registers route"| node_tables_api
node_app_runtime -->|"registers route"| node_export_api
node_auth_api -->|"delegates to"| node_auth_service
node_database_api -->|"delegates to"| node_registry
node_ask_api -->|"invokes"| node_agent
node_ask_api -->|"uses memory"| node_conversations
node_ask_api -->|"uses tools"| node_mcp_tools
node_ask_api -->|"checks database"| node_registry
node_agent -->|"uses adapter"| node_tool_adapter
node_agent -->|"retrieves references"| node_rag
node_tool_adapter -->|"calls tools"| node_mcp_tools
node_mcp_tools -->|"validates SQL"| node_sql_guard
node_mcp_tools -->|"executes SQL"| node_executor
node_mcp_tools -->|"checks permissions"| node_registry
node_tables_api -->|"imports files"| node_import_service
node_tables_api -->|"uses database tools"| node_mcp_tools
node_export_api -.->|"exports data"| node_export_service
node_registry -->|"creates tenant schema"| node_database_manager
node_app_runtime -->|"initializes stores"| node_database_manager
node_database_manager -->|"connects"| node_mongo
node_database_manager -->|"connects"| node_postgres
node_database_manager -->|"connects"| node_redis
node_registry -->|"stores registry"| node_mongo
node_conversations -.->|"stores history"| node_mongo
node_executor -.->|"runs tenant SQL"| node_postgres
node_rag -->|"uses vector store"| node_postgres
node_rag -->|"caches retrieval"| node_redis
node_agent -->|"generates SQL and answers"| node_gemini
node_rag -->|"embeds queries"| node_gemini

click node_ask_ui "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/frontend/src/pages/AskPage.jsx"
click node_turn_ui "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/frontend/src/components/TurnCard.jsx"
click node_db_ui "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/frontend/src/pages/DatabasesPage.jsx"
click node_import_ui "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/frontend/src/components/ImportModal.jsx"
click node_api_client "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/frontend/src/api.js"
click node_auth_api "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/api/auth.py"
click node_database_api "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/api/databases.py"
click node_ask_api "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/api/ask.py"
click node_tables_api "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/api/tables.py"
click node_export_api "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/api/export.py"
click node_auth_service "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/auth.py"
click node_registry "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/database_registry.py"
click node_agent "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/agent/agent_factory.py"
click node_tool_adapter "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/agent/tool_service_adapter.py"
click node_mcp_tools "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/mcp_tools.py"
click node_sql_guard "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/sql_validator.py"
click node_executor "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/postgres_executor.py"
click node_conversations "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/conversation_service.py"
click node_rag "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/rag_service.py"
click node_import_service "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/import_service.py"
click node_export_service "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/export_service.py"
click node_app_runtime "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/main.py"
click node_database_manager "https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/core/database.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ask_ui,node_turn_ui,node_db_ui,node_import_ui,node_api_client,node_user toneBlue
class node_auth_api,node_database_api,node_ask_api,node_tables_api,node_export_api toneAmber
class node_auth_service,node_registry,node_agent,node_tool_adapter,node_mcp_tools,node_sql_guard,node_executor,node_conversations,node_rag,node_import_service,node_export_service toneMint
class node_app_runtime,node_database_manager,node_mongo,node_postgres,node_redis toneRose
class node_gemini toneIndigo
```

## Components

### Browser application

- [Ask workflow](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/frontend/src/pages/AskPage.jsx): `frontend/src/pages/AskPage.jsx`
- [Answer display](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/frontend/src/components/TurnCard.jsx): `frontend/src/components/TurnCard.jsx`
- [Database workspace](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/frontend/src/pages/DatabasesPage.jsx): `frontend/src/pages/DatabasesPage.jsx`
- [Import dialog](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/frontend/src/components/ImportModal.jsx): `frontend/src/components/ImportModal.jsx`
- [API client](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/frontend/src/api.js): `frontend/src/api.js`

### HTTP API

- [Authentication routes](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/api/auth.py): `app/api/auth.py`
- [Database routes](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/api/databases.py): `app/api/databases.py`
- [Question routes](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/api/ask.py): `app/api/ask.py`
- [Tables routes](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/api/tables.py): `app/api/tables.py`
- [Export routes](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/api/export.py): `app/api/export.py`

### Domain services

- [Auth service](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/auth.py): `app/services/auth.py`
- [Database registry](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/database_registry.py): `app/services/database_registry.py`
- [SQL agent](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/agent/agent_factory.py): `app/agent/agent_factory.py`
- [Agent tool adapter](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/agent/tool_service_adapter.py): `app/agent/tool_service_adapter.py`
- [Database tools](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/mcp_tools.py): `app/services/mcp_tools.py`
- [SQL validation](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/sql_validator.py): `app/services/sql_validator.py`
- [Postgres executor](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/postgres_executor.py): `app/services/postgres_executor.py`
- [Conversation memory](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/conversation_service.py): `app/services/conversation_service.py`
- [Textbook retrieval](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/rag_service.py): `app/services/rag_service.py`
- [File import](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/import_service.py): `app/services/import_service.py`
- [File export](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/services/export_service.py): `app/services/export_service.py`

### Runtime and stores

- [API runtime](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/main.py): `app/main.py`
- [Database manager](https://github.com/aditya-singh-3112/llm_dbms_v2/blob/master/app/core/database.py): `app/core/database.py`
- **MongoDB**
- **Postgres tenants**
- **Redis cache**

### Other components

- **User**
- **Gemini models**

## Connections

- User → Ask workflow: asks question (evidence: `README.md`)
- Ask workflow → API client: submits request (evidence: `frontend/src/pages/AskPage.jsx`)
- Ask workflow → Answer display: renders turns (evidence: `frontend/src/pages/AskPage.jsx`)
- API client → Question routes: calls API (evidence: `README.md`)
- User → Database workspace: manages databases (evidence: `README.md`)
- Database workspace → API client: requests database actions (evidence: `frontend/src/pages/DatabasesPage.jsx`)
- Database workspace → Import dialog: opens import
- API client → Authentication routes: calls API (evidence: `README.md`)
- API client → Database routes: calls API
- API client → Tables routes: calls API
- API client → Export routes: calls API
- API runtime → Question routes: registers route (evidence: `app/main.py`)
- API runtime → Authentication routes: registers route (evidence: `app/main.py`)
- API runtime → Database routes: registers route (evidence: `app/main.py`)
- API runtime → Tables routes: registers route (evidence: `app/main.py`)
- API runtime → Export routes: registers route (evidence: `app/main.py`)
- Authentication routes → Auth service: delegates to (evidence: `app/api/auth.py`)
- Database routes → Database registry: delegates to (evidence: `app/api/databases.py`)
- Question routes → SQL agent: invokes (evidence: `app/api/ask.py`)
- Question routes → Conversation memory: uses memory (evidence: `app/api/ask.py`)
- Question routes → Database tools: uses tools (evidence: `app/api/ask.py`)
- Question routes → Database registry: checks database (evidence: `app/api/ask.py`)
- SQL agent → Agent tool adapter: uses adapter (evidence: `app/agent/agent_factory.py`)
- SQL agent → Textbook retrieval: retrieves references (evidence: `app/agent/agent_factory.py`)
- Agent tool adapter → Database tools: calls tools (evidence: `app/agent/tool_service_adapter.py`)
- Database tools → SQL validation: validates SQL (evidence: `app/services/mcp_tools.py`)
- Database tools → Postgres executor: executes SQL (evidence: `app/services/mcp_tools.py`)
- Database tools → Database registry: checks permissions
- Tables routes → File import: imports files (evidence: `app/api/tables.py`)
- Tables routes → Database tools: uses database tools (evidence: `app/api/tables.py`)
- Export routes → File export: exports data
- Database registry → Database manager: creates tenant schema (evidence: `app/services/database_registry.py`)
- API runtime → Database manager: initializes stores (evidence: `app/main.py`)
- Database manager → MongoDB: connects (evidence: `app/core/database.py`)
- Database manager → Postgres tenants: connects (evidence: `app/core/database.py`)
- Database manager → Redis cache: connects (evidence: `app/core/database.py`)
- Database registry → MongoDB: stores registry (evidence: `app/services/database_registry.py`)
- Conversation memory → MongoDB: stores history
- Postgres executor → Postgres tenants: runs tenant SQL
- Textbook retrieval → Postgres tenants: uses vector store (evidence: `app/services/rag_service.py`)
- Textbook retrieval → Redis cache: caches retrieval (evidence: `app/services/rag_service.py`)
- SQL agent → Gemini models: generates SQL and answers (evidence: `README.md`)
- Textbook retrieval → Gemini models: embeds queries (evidence: `README.md`)