# parth-yangandul-df/querywise architecture

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

- Interactive diagram: https://gitdiagram.com/parth-yangandul-df/querywise
- Repository: https://github.com/parth-yangandul-df/querywise

## Overview

1. **Overall shape**
QueryWise is a three-tier system: a FastAPI backend, a React admin console, and an Angular chat UI. The backend owns all business logic, SQL generation/execution, metadata persistence, and LLM orchestration; the two frontends are thin clients with different audiences.

2. **Primary user flows**
There are two main paths: an admin/curation path in the React app for managing connections, glossary, knowledge, users, and metrics; and an end-user conversational path in the Angular app for asking natural-language questions and reviewing results. Both call the same backend API, but with different UI and role constraints.

3. **Backend API boundary**
The backend exposes versioned REST endpoints under `/api/v1`, including auth, users, connections, glossary, knowledge, sessions, query, query history, sample queries, metrics, and health/ready checks. The API layer is mostly a routing and validation boundary; orchestration lives deeper in services and LangGraph nodes.

4. **Query orchestration core**
The center of the system is the LangGraph-based query pipeline in `backend/app/llm/graph`. A request flows through history loading, turn resolution, optional follow-up handling, context building, SQL composition, SQL validation, database execution, result interpretation, and history writing. This is the main place where natural language becomes executable SQL and then a user-facing answer.

5. **State and turn management**
The graph uses explicit state models in `backend/app/llm/graph/state.py` and related node code to carry context across turns. That state includes conversation history, resolved intent, SQL, execution output, and status flags such as empty-result handling. Recent work also added turn context persistence so follow-up queries can reuse prior context safely.

6. **Semantic metadata layer**
A separate semantic subsystem builds database-aware context from glossary terms, schema metadata, relationships, sample queries, embeddings, and knowledge chunks. Its job is to improve retrieval and grounding before SQL generation, not to execute queries. This layer is important because QueryWise is not only an LLM-to-SQL system; it is a metadata-augmented system.

7. **Data persistence**
The metadata store is PostgreSQL with async SQLAlchemy models under `backend/app/db/models`. It stores users, connections, chat sessions, query history, schema cache, glossary, knowledge, metrics, audit logs, and embeddings-related data. Migrations in Alembic show the schema has evolved to support RBAC, chat sessions, manual relationships, turn context, and auditability.

8. **Database connectors**
Actual source databases are accessed through connector plugins in `backend/app/connectors`, with PostgreSQL and SQL Server implementations present. The connector registry lets the backend support multiple database backends while keeping the query pipeline and UI agnostic to the specific source system.

9. **Safety and control boundaries**
The system explicitly separates SQL generation from execution safety. SQL goes through validation/sanitization before execution, and the backend includes retry/correction logic when LLM-generated SQL fails. Scope constraints such as `resource_id` and `employee_id` are part of the architecture, not just UI filters, so end-user access is enforced server-side.

10. **Session, history, and streaming**
QueryWise persists conversation state per session and query history for follow-ups. It also streams progress over SSE from the query API, which means the frontend can render incremental state rather than waiting for the final answer. Empty-result responses are treated as a first-class outcome with a dedicated status and message.

11. **Observability and operational support**
The backend includes logging, metrics, rate limiting, Redis integration, query cache, tracing hooks, and exception handlers. These are not decorative; they support safe production operation of an LLM-driven system where latency, retries, and failures are expected. There are also scripts for backup/restore, re-embedding, and metadata seeding.

12. **Frontend responsibilities**
The React admin console is a standard Vite app with API clients and route-level pages for operational management. The Angular app is a separate chat-focused client with its own service layer and result-table interactions such as search, sort, pagination, and CSV export. The split suggests two independently evolving UIs sharing one backend contract.

13. **Deployment and environments**
The repo is containerized with Docker Compose for local end-to-end startup and GitHub Actions for backend/frontend deployment workflows. Environment files, startup auto-setup flags, and migration scripts indicate the architecture is designed to be reproducible across local dev, test, and deployment environments.

14. **Testing and validation**
The test suite mixes backend unit tests, semantic-layer tests, and end-to-end tests for auth, connections, sessions, query flow, streaming, and pipeline behavior. This matches the architecture: most important failures occur at the boundaries between metadata, LLM orchestration, and real database execution, so those boundaries are heavily tested.

Main entry points: [`backend/app/api/v1`](https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/api/v1) (API layer), [`backend/app/llm/graph`](https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/llm/graph) (Query graph), [`backend/app/llm/graph/nodes`](https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/llm/graph/nodes) (Graph nodes), [`backend/app/db/models`](https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/db/models) (Metadata store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_api["API layer<br/>FastAPI v1"]
  node_backend_query_service["Query service<br/>Orchestration<br/>[query_service.py]"]
  node_backend_llm_graph{{"Query graph<br/>LangGraph pipeline"}}
  node_backend_graph_state["Graph state<br/>Turn state<br/>[state.py]"]
  node_backend_graph_nodes["Graph nodes<br/>Workflow nodes"]
  node_backend_semantic["Semantic layer<br/>Metadata grounding"]
  node_backend_llm_providers["LLM providers<br/>Model adapters"]
  node_backend_sql_safety["SQL safety<br/>Validation/sanitizer<br/>[sql_validator.py]"]
  node_backend_connectors["DB connectors<br/>Source adapters"]
  node_backend_registry["Connector registry<br/>Routing"]
  node_backend_models[("Metadata store<br/>SQLAlchemy models")]
  node_backend_migrations["Migrations<br/>Alembic schema"]
  node_backend_core["Core services<br/>Ops/runtime"]
  node_backend_auth["Auth & RBAC<br/>Access control<br/>[auth.py]"]
  node_backend_query_api["Query API<br/>Streaming endpoint<br/>[query.py]"]
  node_backend_admin_api["Admin APIs<br/>CRUD endpoints"]
  node_backend_health["Health checks<br/>Readiness<br/>[health.py]"]
end

subgraph group_frontends["Frontends"]
  node_frontend_admin["Admin console<br/>React/Vite app"]
  node_frontend_chat["Chat UI<br/>Angular app"]
end

subgraph group_ops["Ops"]
end

node_frontend_admin -->|"calls"| node_backend_api
node_frontend_chat -->|"calls"| node_backend_api
node_backend_api -->|"routes to"| node_backend_auth
node_backend_api -->|"routes to"| node_backend_admin_api
node_backend_api -->|"routes to"| node_backend_query_api
node_backend_api -->|"routes to"| node_backend_health
node_backend_query_api -->|"delegates to"| node_backend_query_service
node_backend_query_service -->|"invokes"| node_backend_llm_graph
node_backend_llm_graph -->|"uses"| node_backend_graph_state
node_backend_llm_graph -->|"composed of"| node_backend_graph_nodes
node_backend_graph_nodes -->|"enriches with"| node_backend_semantic
node_backend_graph_nodes -->|"validates"| node_backend_sql_safety
node_backend_graph_nodes -->|"executes via"| node_backend_connectors
node_backend_connectors -->|"selected by"| node_backend_registry
node_backend_llm_graph -->|"uses"| node_backend_llm_providers
node_backend_semantic -->|"reads/writes"| node_backend_models
node_backend_admin_api -->|"persists"| node_backend_models
node_backend_query_service -->|"persists"| node_backend_models
node_backend_core -.->|"supports"| node_backend_api
node_backend_migrations -->|"evolves"| node_backend_models
node_frontend_admin -.->|"enforces"| node_backend_auth
node_frontend_chat -.->|"streams"| node_backend_query_api

click node_backend_api "https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/api/v1"
click node_backend_query_service "https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/services/query_service.py"
click node_backend_llm_graph "https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/llm/graph"
click node_backend_graph_state "https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/llm/graph/state.py"
click node_backend_graph_nodes "https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/llm/graph/nodes"
click node_backend_semantic "https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/semantic"
click node_backend_llm_providers "https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/llm/providers"
click node_backend_sql_safety "https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/llm/agents/sql_validator.py"
click node_backend_connectors "https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/connectors"
click node_backend_registry "https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/connectors/connector_registry.py"
click node_backend_models "https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/db/models"
click node_backend_migrations "https://github.com/parth-yangandul-df/querywise/tree/main/backend/alembic/versions"
click node_backend_core "https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/core"
click node_frontend_admin "https://github.com/parth-yangandul-df/querywise/tree/main/frontend/src"
click node_frontend_chat "https://github.com/parth-yangandul-df/querywise/tree/main/angular-test/src/app"
click node_backend_auth "https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/api/v1/endpoints/auth.py"
click node_backend_query_api "https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/api/v1/endpoints/query.py"
click node_backend_admin_api "https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/api/v1/endpoints"
click node_backend_health "https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/api/v1/endpoints/health.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_backend_api,node_backend_query_service,node_backend_llm_graph,node_backend_graph_state,node_backend_graph_nodes,node_backend_semantic,node_backend_llm_providers,node_backend_sql_safety,node_backend_connectors,node_backend_registry,node_backend_models,node_backend_migrations,node_backend_core,node_backend_auth,node_backend_query_api,node_backend_admin_api,node_backend_health toneBlue
class node_frontend_admin,node_frontend_chat toneAmber
```

## Components

### Backend

FastAPI API, query orchestration, semantic layer, connectors, and persistence

- [API layer](https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/api/v1): FastAPI v1 · Versioned REST boundary for auth, users, connections, glossary, knowledge, sessions, query, history, sample queries, metrics, and health · `backend/app/api/v1`
- [Query service](https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/services/query_service.py): Orchestration · Coordinates query requests, session handling, streaming, history, and safety checks · `backend/app/services/query_service.py`
- [Query graph](https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/llm/graph): LangGraph pipeline · Main natural-language-to-SQL workflow and answer generation pipeline · `backend/app/llm/graph`
- [Graph state](https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/llm/graph/state.py): Turn state · Conversation and execution state carried across query turns · `backend/app/llm/graph/state.py`
- [Graph nodes](https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/llm/graph/nodes): Workflow nodes · History loading, turn resolution, follow-up handling, context building, SQL composition, validation, execution, interpretation, and history writing · `backend/app/llm/graph/nodes`
- [Semantic layer](https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/semantic): Metadata grounding · Builds retrieval and grounding context from glossary, schema, relationships, samples, embeddings, and knowledge · `backend/app/semantic`
- [LLM providers](https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/llm/providers): Model adapters · OpenAI, Anthropic, Groq, Ollama, and OpenRouter provider integrations · `backend/app/llm/providers`
- [SQL safety](https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/llm/agents/sql_validator.py): Validation/sanitizer · Validates and sanitizes generated SQL before execution · `backend/app/llm/agents/sql_validator.py`
- [DB connectors](https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/connectors): Source adapters · Pluggable database access for PostgreSQL and SQL Server · `backend/app/connectors`
- [Connector registry](https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/connectors/connector_registry.py): Routing · Selects the correct source database connector implementation · `backend/app/connectors/connector_registry.py`
- [Metadata store](https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/db/models): SQLAlchemy models · Persistent metadata for users, connections, sessions, history, glossary, knowledge, metrics, audits, schema cache, and sample queries · `backend/app/db/models`
- [Migrations](https://github.com/parth-yangandul-df/querywise/tree/main/backend/alembic/versions): Alembic schema · Database evolution for RBAC, sessions, turn context, audit logs, and related metadata · `backend/alembic/versions`
- [Core services](https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/core): Ops/runtime · Logging, metrics, Redis, caching, rate limiting, tracing, exceptions, and retry support · `backend/app/core`
- [Auth & RBAC](https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/api/v1/endpoints/auth.py): Access control · JWT auth, protected routes, and server-side role and scope enforcement · `backend/app/api/v1/endpoints/auth.py`
- [Query API](https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/api/v1/endpoints/query.py): Streaming endpoint · Query, history, session, and SSE streaming contract used by both frontends · `backend/app/api/v1/endpoints/query.py`
- [Admin APIs](https://github.com/parth-yangandul-df/querywise/tree/main/backend/app/api/v1/endpoints): CRUD endpoints · Connections, glossary, knowledge, users, sample queries, metrics, and dictionary management · `backend/app/api/v1/endpoints`
- [Health checks](https://github.com/parth-yangandul-df/querywise/blob/main/backend/app/api/v1/endpoints/health.py): Readiness · Liveness and readiness endpoints for operational monitoring · `backend/app/api/v1/endpoints/health.py`

### Frontends

Admin console and chat UI clients

- [Admin console](https://github.com/parth-yangandul-df/querywise/tree/main/frontend/src): React/Vite app · Operational UI for managing connections, glossary, knowledge, users, metrics, and history · `frontend/src`
- [Chat UI](https://github.com/parth-yangandul-df/querywise/tree/main/angular-test/src/app): Angular app · Conversation-focused UI for natural-language question asking and result review · `angular-test/src/app`

## Connections

- Admin console → API layer: calls · Admin console uses the REST API for management actions
- Chat UI → API layer: calls · Chat UI uses the same backend contract for conversational queries
- API layer → Auth & RBAC: routes to · Authentication and role checks are handled at the API boundary
- API layer → Admin APIs: routes to · Operational CRUD endpoints for curation and administration
- API layer → Query API: routes to · Query and streaming endpoints for conversational use
- API layer → Health checks: routes to · Health and readiness checks
- Query API → Query service: delegates to · Query endpoints orchestrate through the service layer
- Query service → Query graph: invokes · Service hands requests to the LangGraph pipeline
- Query graph → Graph state: uses · Workflow state carries turn context and execution results
- Query graph → Graph nodes: composed of · Pipeline is implemented as a sequence of workflow nodes
- Graph nodes → Semantic layer: enriches with · Nodes retrieve semantic grounding and context
- Graph nodes → SQL safety: validates · Generated SQL is checked before execution
- Graph nodes → DB connectors: executes via · Validated SQL runs against the selected source database connector
- DB connectors → Connector registry: selected by · Registry resolves connector implementations by database type
- Query graph → LLM providers: uses · LLM-backed nodes call provider adapters for generation and interpretation
- Semantic layer → Metadata store: reads/writes · Semantic context depends on stored metadata, glossary, embeddings, and cache
- Admin APIs → Metadata store: persists · Admin operations update metadata records in the store
- Query service → Metadata store: persists · Sessions, history, and query outcomes are written to the metadata store
- Core services → API layer: supports · Cross-cutting runtime behavior wraps the API layer
- Migrations → Metadata store: evolves · Alembic migrations track schema changes for stored metadata
- Admin console → Auth & RBAC: enforces · Protected routes and role-aware UI depend on auth state
- Chat UI → Query API: streams · Chat client consumes incremental query progress and results