parth-yangandul-df/querywise

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.