# mohamed-dahy/querymind architecture

> Architecture diagram of the GitHub repository mohamed-dahy/querymind, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohamed-dahy/querymind
- Repository: https://github.com/mohamed-dahy/querymind

## Overview

QueryMind is an AI data analyst for company databases. A user asks in the web canvas or HTTP API; the API invokes the agent, which selects relevant schema context, generates and validates SQL, runs it read-only, checks and summarizes the result, and retains conversation context for follow-ups. Distinct supporting capabilities include semantic definitions and example-query retrieval, workspace database and LLM-key management, authentication and audit, and the explorer and evaluation lab. Relationships below follow the README and shown source references; unsampled subsystems are included where documented, without asserting unverified internal calls.

Main entry points: [`src/querymind/api/routes.py`](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/api/routes.py) (HTTP API), [`src/querymind/agent/pipeline.py`](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/agent/pipeline.py) (Agent pipeline), [`src/querymind/semantic/retrieval.py`](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/semantic/retrieval.py) (Schema retrieval), [`src/querymind/db/executor.py`](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/db/executor.py) (Read-only execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_canvas["Question canvas<br/>[CanvasProvider.tsx]"]
  node_explorer_ui["Data explorer UI<br/>[GlossaryPage.tsx]"]
  node_eval_ui["Evaluation lab UI<br/>[EvalsFrame.tsx]"]
end

subgraph group_workspace["API and workspace"]
  node_api["HTTP API<br/>[routes.py]"]
  node_auth["Login and identity<br/>[tokens.py]"]
  node_workspace_admin["Workspace settings<br/>[connections.py]"]
  node_audit[("Audit trail<br/>[audit.py]")]
  node_conversations[("Conversation history<br/>[conversations.py]")]
  node_eval_service["Evaluation service<br/>[evals.py]"]
end

subgraph group_agent["Question answering"]
  node_agent["Agent pipeline<br/>[pipeline.py]"]
  node_schema_context["Schema context<br/>[schema.py]"]
  node_semantic["Business definitions<br/>[dictionary.py]"]
  node_retrieval["Schema retrieval<br/>[retrieval.py]"]
  node_llm["LLM providers<br/>[factory.py]"]
  node_answer["Answer and confidence<br/>[schemas.py]"]
end

subgraph group_data["Data and safeguards"]
  node_sql_safety["SQL validation<br/>[sql_validator.py]"]
  node_row_scope["Row permissions<br/>[row_scope.py]"]
  node_executor["Read-only execution<br/>[executor.py]"]
  node_database[("Company database")]
  node_semantic_index[("Search index<br/>[index.py]")]
end

node_user(("Analyst"))

node_user -->|"asks"| node_canvas
node_canvas -->|"sends question"| node_api
node_api -->|"invokes"| node_agent
node_api -->|"authenticates"| node_auth
node_api -->|"loads and saves"| node_conversations
node_api -->|"records activity"| node_audit
node_api -->|"serves settings"| node_workspace_admin
node_api -->|"serves evaluations"| node_eval_service
node_agent -->|"loads schema"| node_schema_context
node_agent -->|"selects tables"| node_retrieval
node_agent -.->|"uses definitions"| node_semantic
node_agent -->|"generates SQL"| node_llm
node_agent -->|"validates SQL"| node_sql_safety
node_agent -->|"runs query"| node_executor
node_executor -->|"reads"| node_database
node_executor -->|"applies scope"| node_row_scope
node_agent -->|"returns result"| node_answer
node_retrieval -->|"searches"| node_semantic_index
node_retrieval -->|"embeds query"| node_llm
node_user -->|"explores data"| node_explorer_ui
node_user -->|"reviews scores"| node_eval_ui
node_explorer_ui -.->|"requests data"| node_api
node_eval_ui -.->|"requests evaluations"| node_api

click node_canvas "https://github.com/mohamed-dahy/querymind/blob/main/web/src/canvas/CanvasProvider.tsx"
click node_explorer_ui "https://github.com/mohamed-dahy/querymind/blob/main/web/src/explorer/GlossaryPage.tsx"
click node_eval_ui "https://github.com/mohamed-dahy/querymind/blob/main/web/src/evals/EvalsFrame.tsx"
click node_api "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/api/routes.py"
click node_auth "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/auth/tokens.py"
click node_workspace_admin "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/api/connections.py"
click node_audit "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/store/audit.py"
click node_conversations "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/store/conversations.py"
click node_agent "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/agent/pipeline.py"
click node_schema_context "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/db/schema.py"
click node_semantic "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/semantic/dictionary.py"
click node_retrieval "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/semantic/retrieval.py"
click node_llm "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/llm/factory.py"
click node_answer "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/agent/schemas.py"
click node_sql_safety "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/safety/sql_validator.py"
click node_row_scope "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/safety/row_scope.py"
click node_executor "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/db/executor.py"
click node_semantic_index "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/semantic/index.py"
click node_eval_service "https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/api/evals.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_canvas,node_explorer_ui,node_eval_ui toneBlue
class node_api,node_auth,node_workspace_admin,node_audit,node_conversations,node_eval_service toneAmber
class node_agent,node_schema_context,node_semantic,node_retrieval,node_llm,node_answer toneMint
class node_sql_safety,node_row_scope,node_executor,node_database,node_semantic_index toneRose
class node_user toneIndigo
```

## Components

### User experience

- [Question canvas](https://github.com/mohamed-dahy/querymind/blob/main/web/src/canvas/CanvasProvider.tsx): `web/src/canvas/CanvasProvider.tsx`
- [Data explorer UI](https://github.com/mohamed-dahy/querymind/blob/main/web/src/explorer/GlossaryPage.tsx): `web/src/explorer/GlossaryPage.tsx`
- [Evaluation lab UI](https://github.com/mohamed-dahy/querymind/blob/main/web/src/evals/EvalsFrame.tsx): `web/src/evals/EvalsFrame.tsx`

### API and workspace

- [HTTP API](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/api/routes.py): `src/querymind/api/routes.py`
- [Login and identity](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/auth/tokens.py): `src/querymind/auth/tokens.py`
- [Workspace settings](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/api/connections.py): `src/querymind/api/connections.py`
- [Audit trail](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/store/audit.py): `src/querymind/store/audit.py`
- [Conversation history](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/store/conversations.py): `src/querymind/store/conversations.py`
- [Evaluation service](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/api/evals.py): `src/querymind/api/evals.py`

### Question answering

- [Agent pipeline](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/agent/pipeline.py): `src/querymind/agent/pipeline.py`
- [Schema context](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/db/schema.py): `src/querymind/db/schema.py`
- [Business definitions](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/semantic/dictionary.py): `src/querymind/semantic/dictionary.py`
- [Schema retrieval](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/semantic/retrieval.py): `src/querymind/semantic/retrieval.py`
- [LLM providers](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/llm/factory.py): `src/querymind/llm/factory.py`
- [Answer and confidence](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/agent/schemas.py): `src/querymind/agent/schemas.py`

### Data and safeguards

- [SQL validation](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/safety/sql_validator.py): `src/querymind/safety/sql_validator.py`
- [Row permissions](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/safety/row_scope.py): `src/querymind/safety/row_scope.py`
- [Read-only execution](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/db/executor.py): `src/querymind/db/executor.py`
- **Company database**
- [Search index](https://github.com/mohamed-dahy/querymind/blob/main/src/querymind/semantic/index.py): `src/querymind/semantic/index.py`

### Other components

- **Analyst**

## Connections

- Analyst → Question canvas: asks (evidence: `README.md`)
- Question canvas → HTTP API: sends question (evidence: `README.md`)
- HTTP API → Agent pipeline: invokes (evidence: `src/querymind/api/routes.py`)
- HTTP API → Login and identity: authenticates (evidence: `src/querymind/api/routes.py`)
- HTTP API → Conversation history: loads and saves (evidence: `src/querymind/api/routes.py`)
- HTTP API → Audit trail: records activity (evidence: `src/querymind/api/routes.py`)
- HTTP API → Workspace settings: serves settings (evidence: `src/querymind/api/main.py`)
- HTTP API → Evaluation service: serves evaluations (evidence: `src/querymind/api/main.py`)
- Agent pipeline → Schema context: loads schema (evidence: `src/querymind/agent/pipeline.py`)
- Agent pipeline → Schema retrieval: selects tables (evidence: `src/querymind/agent/pipeline.py`)
- Agent pipeline → Business definitions: uses definitions (evidence: `src/querymind/agent/pipeline.py`)
- Agent pipeline → LLM providers: generates SQL (evidence: `README.md`)
- Agent pipeline → SQL validation: validates SQL (evidence: `README.md`)
- Agent pipeline → Read-only execution: runs query (evidence: `src/querymind/agent/pipeline.py`)
- Read-only execution → Company database: reads
- Read-only execution → Row permissions: applies scope
- Agent pipeline → Answer and confidence: returns result (evidence: `src/querymind/agent/pipeline.py`)
- Schema retrieval → Search index: searches (evidence: `src/querymind/semantic/retrieval.py`)
- Schema retrieval → LLM providers: embeds query (evidence: `src/querymind/semantic/retrieval.py`)
- Analyst → Data explorer UI: explores data (evidence: `README.md`)
- Analyst → Evaluation lab UI: reviews scores (evidence: `README.md`)
- Data explorer UI → HTTP API: requests data
- Evaluation lab UI → HTTP API: requests evaluations
