# bhagyesh-074/semantiq architecture

> Architecture diagram of the GitHub repository bhagyesh-074/semantiq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhagyesh-074/semantiq
- Repository: https://github.com/bhagyesh-074/semantiq

## Overview

SemantiQ is a governed text-to-SQL product: users ask warehouse questions, the agent resolves business terms, gates ambiguity, generates SQL through either governed semantics or schema-only fallback, then executes and validates it with bounded self-correction. Data owners can compile and review the semantic catalog; the React interface presents answers, citations, clarification prompts, failures, and retry traces. The README documents the main agent stages; source excerpts show API dispatch and UI submission. Some internal wiring and UI component behavior is supported only by the README or SOURCE INDEX, so unverified links are omitted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/App.jsx) (Question App), [`agent/executor.py`](https://github.com/bhagyesh-074/semantiq/blob/main/agent/executor.py) (Pipeline Executor), [`agent/sql_generation.py`](https://github.com/bhagyesh-074/semantiq/blob/main/agent/sql_generation.py) (SQL Generation), [`semantic_layer/compiler.py`](https://github.com/bhagyesh-074/semantiq/blob/main/semantic_layer/compiler.py) (Layer Compiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Question Interface"]
  node_app["Question App<br/>[App.jsx]"]
  node_question_input["Question Input<br/>[QuestionInput.jsx]"]
  node_resolved_terms["Resolved Terms<br/>[ResolvedTerms.jsx]"]
  node_sql_view["SQL View<br/>[SqlView.jsx]"]
  node_retry_trace["Retry Trace<br/>[RetryTrace.jsx]"]
  node_answer_card["Answer Card<br/>[AnswerCard.jsx]"]
  node_clarification_card["Clarification Card"]
  node_failure_card["Failure Card<br/>[FailureCard.jsx]"]
end

subgraph group_service["API Service"]
  node_api["Ask API<br/>[server.py]"]
end

subgraph group_agent["Text-to-SQL Agent"]
  node_executor["Pipeline Executor<br/>[executor.py]"]
  node_term_resolution["Term Resolution<br/>[term_resolution.py]"]
  node_ambiguity["Ambiguity Gate<br/>[ambiguity.py]"]
  node_schema_linking["Schema Linking<br/>[schema_linking.py]"]
  node_sql_generation["SQL Generation<br/>[sql_generation.py]"]
end

subgraph group_governance["Semantic Governance"]
  node_compiler["Layer Compiler<br/>[compiler.py]"]
  node_review["Layer Review<br/>[review.py]"]
  node_catalog["Semantic Catalog<br/>[layer.yaml]"]
end

node_user(("Warehouse User"))
node_warehouse[("DuckDB Warehouse")]
node_llm(("Groq LLM"))

node_user -->|"asks question"| node_app
node_app -->|"renders"| node_question_input
node_app -->|"submits question"| node_api
node_api -->|"runs pipeline"| node_executor
node_executor -->|"resolves terms"| node_term_resolution
node_executor -->|"gates ambiguity"| node_ambiguity
node_executor -->|"links schema"| node_schema_linking
node_executor -->|"generates SQL"| node_sql_generation
node_executor -->|"executes and validates"| node_warehouse
node_term_resolution -->|"matches definitions"| node_catalog
node_ambiguity -->|"phrases clarification"| node_llm
node_sql_generation -->|"requests SQL"| node_llm
node_sql_generation -->|"uses linked schema"| node_schema_linking
node_compiler -->|"profiles schema"| node_warehouse
node_compiler -->|"proposes definitions"| node_review
node_review -->|"writes reviewed layer"| node_catalog
node_app -->|"renders"| node_resolved_terms
node_app -->|"renders"| node_sql_view
node_app -->|"renders"| node_retry_trace
node_app -->|"renders"| node_answer_card
node_app -->|"renders"| node_clarification_card
node_app -->|"renders"| node_failure_card

click node_app "https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/App.jsx"
click node_question_input "https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/QuestionInput.jsx"
click node_resolved_terms "https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/ResolvedTerms.jsx"
click node_sql_view "https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/SqlView.jsx"
click node_retry_trace "https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/RetryTrace.jsx"
click node_answer_card "https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/AnswerCard.jsx"
click node_clarification_card "https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/ClarificationCard.jsx"
click node_failure_card "https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/FailureCard.jsx"
click node_api "https://github.com/bhagyesh-074/semantiq/blob/main/api/server.py"
click node_executor "https://github.com/bhagyesh-074/semantiq/blob/main/agent/executor.py"
click node_term_resolution "https://github.com/bhagyesh-074/semantiq/blob/main/agent/term_resolution.py"
click node_ambiguity "https://github.com/bhagyesh-074/semantiq/blob/main/agent/ambiguity.py"
click node_schema_linking "https://github.com/bhagyesh-074/semantiq/blob/main/agent/schema_linking.py"
click node_sql_generation "https://github.com/bhagyesh-074/semantiq/blob/main/agent/sql_generation.py"
click node_compiler "https://github.com/bhagyesh-074/semantiq/blob/main/semantic_layer/compiler.py"
click node_review "https://github.com/bhagyesh-074/semantiq/blob/main/semantic_layer/review.py"
click node_catalog "https://github.com/bhagyesh-074/semantiq/blob/main/semantic_layer/layer.yaml"

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_app,node_question_input,node_resolved_terms,node_sql_view,node_retry_trace,node_answer_card,node_clarification_card,node_failure_card,node_user toneBlue
class node_api,node_warehouse toneAmber
class node_executor,node_term_resolution,node_ambiguity,node_schema_linking,node_sql_generation toneMint
class node_compiler,node_review,node_catalog toneRose
class node_llm toneIndigo
```

## Components

### Question Interface

- [Question App](https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Question Input](https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/QuestionInput.jsx): `frontend/src/components/QuestionInput.jsx`
- [Resolved Terms](https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/ResolvedTerms.jsx): `frontend/src/components/ResolvedTerms.jsx`
- [SQL View](https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/SqlView.jsx): `frontend/src/components/SqlView.jsx`
- [Retry Trace](https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/RetryTrace.jsx): `frontend/src/components/RetryTrace.jsx`
- [Answer Card](https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/AnswerCard.jsx): `frontend/src/components/AnswerCard.jsx`
- [Clarification Card](https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/ClarificationCard.jsx): `frontend/src/components/ClarificationCard.jsx`
- [Failure Card](https://github.com/bhagyesh-074/semantiq/blob/main/frontend/src/components/FailureCard.jsx): `frontend/src/components/FailureCard.jsx`

### API Service

- [Ask API](https://github.com/bhagyesh-074/semantiq/blob/main/api/server.py): `api/server.py`

### Text-to-SQL Agent

- [Pipeline Executor](https://github.com/bhagyesh-074/semantiq/blob/main/agent/executor.py): `agent/executor.py`
- [Term Resolution](https://github.com/bhagyesh-074/semantiq/blob/main/agent/term_resolution.py): `agent/term_resolution.py`
- [Ambiguity Gate](https://github.com/bhagyesh-074/semantiq/blob/main/agent/ambiguity.py): `agent/ambiguity.py`
- [Schema Linking](https://github.com/bhagyesh-074/semantiq/blob/main/agent/schema_linking.py): `agent/schema_linking.py`
- [SQL Generation](https://github.com/bhagyesh-074/semantiq/blob/main/agent/sql_generation.py): `agent/sql_generation.py`

### Semantic Governance

- [Layer Compiler](https://github.com/bhagyesh-074/semantiq/blob/main/semantic_layer/compiler.py): `semantic_layer/compiler.py`
- [Layer Review](https://github.com/bhagyesh-074/semantiq/blob/main/semantic_layer/review.py): `semantic_layer/review.py`
- [Semantic Catalog](https://github.com/bhagyesh-074/semantiq/blob/main/semantic_layer/layer.yaml): `semantic_layer/layer.yaml`

### Other components

- **Warehouse User**
- **DuckDB Warehouse**
- **Groq LLM**

## Connections

- Warehouse User → Question App: asks question (evidence: `README.md`)
- Question App → Question Input: renders (evidence: `frontend/src/App.jsx`)
- Question App → Ask API: submits question (evidence: `frontend/src/App.jsx`)
- Ask API → Pipeline Executor: runs pipeline (evidence: `api/server.py`)
- Pipeline Executor → Term Resolution: resolves terms (evidence: `README.md`)
- Pipeline Executor → Ambiguity Gate: gates ambiguity (evidence: `README.md`)
- Pipeline Executor → Schema Linking: links schema (evidence: `README.md`)
- Pipeline Executor → SQL Generation: generates SQL (evidence: `README.md`)
- Pipeline Executor → DuckDB Warehouse: executes and validates (evidence: `README.md`)
- Term Resolution → Semantic Catalog: matches definitions (evidence: `README.md`)
- Ambiguity Gate → Groq LLM: phrases clarification (evidence: `agent/ambiguity.py`)
- SQL Generation → Groq LLM: requests SQL (evidence: `agent/sql_generation.py`)
- SQL Generation → Schema Linking: uses linked schema (evidence: `README.md`)
- Layer Compiler → DuckDB Warehouse: profiles schema (evidence: `semantic_layer/compiler.py`)
- Layer Compiler → Layer Review: proposes definitions (evidence: `semantic_layer/review.py`)
- Layer Review → Semantic Catalog: writes reviewed layer (evidence: `semantic_layer/review.py`)
- Question App → Resolved Terms: renders (evidence: `frontend/src/App.jsx`)
- Question App → SQL View: renders (evidence: `frontend/src/App.jsx`)
- Question App → Retry Trace: renders (evidence: `frontend/src/App.jsx`)
- Question App → Answer Card: renders (evidence: `frontend/src/App.jsx`)
- Question App → Clarification Card: renders (evidence: `frontend/src/App.jsx`)
- Question App → Failure Card: renders (evidence: `frontend/src/App.jsx`)
