# pr0xiuss/hypoquery architecture

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

- Interactive diagram: https://gitdiagram.com/pr0xiuss/hypoquery
- Repository: https://github.com/pr0xiuss/hypoquery

## Overview

HypoQuery appears to be a SQL optimization platform with a database-connection UI and backend optimization, ingestion, knowledge, and assistant capabilities. The clearest documented runtime workflow is optimization-pipeline construction: a builder registers processing nodes and defines their order. Ingestion separately collects executions, queues them, and dispatches workers. The README gives no capability details, and many central modules are indexed but unsampled; their nodes are included where the tree supports them, but relationships are omitted when the evidence does not establish them.

Main entry points: [`backend/ingestion/services/ingestion_service.py`](https://github.com/pr0xiuss/hypoquery/blob/main/backend/ingestion/services/ingestion_service.py) (Ingestion service), [`backend/optimization/pipeline/optimization_pipeline_builder.py`](https://github.com/pr0xiuss/hypoquery/blob/main/backend/optimization/pipeline/optimization_pipeline_builder.py) (Pipeline builder), [`backend/execution/pipeline/pipeline.py`](https://github.com/pr0xiuss/hypoquery/blob/main/backend/execution/pipeline/pipeline.py) (Pipeline runtime), [`frontend/src/hooks/useDatabaseConnections.js`](https://github.com/pr0xiuss/hypoquery/blob/main/frontend/src/hooks/useDatabaseConnections.js) (Connection hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and connections"]
  node_frontend["Application UI<br/>[App.jsx]"]
  node_connection_hooks["Connection hooks"]
  node_connection_service["Connection service"]
  node_connection_api["Connection API"]
end

subgraph group_optimization["SQL optimization"]
  node_optimization_builder["Pipeline builder"]
  node_analysis["Plan analysis"]
  node_recommendation["Recommendations"]
  node_validation["Validation"]
  node_ranking["Ranking"]
  node_reporting["Reporting"]
  node_history["Execution history"]
end

subgraph group_execution["Execution and ingestion"]
  node_pipeline_builder["Execution builder<br/>[builder.py]"]
  node_pipeline["Pipeline runtime<br/>[pipeline.py]"]
  node_ingestion_service["Ingestion service"]
  node_collector["Execution collector<br/>[base_collector.py]"]
  node_queue["Execution queue<br/>[base_queue.py]"]
  node_dispatcher["Worker dispatcher<br/>[dispatcher.py]"]
  node_worker["Worker<br/>[worker.py]"]
end

subgraph group_intelligence["Knowledge and assistant"]
  node_context_engine["Context assembly<br/>[engine.py]"]
  node_retrieval_engine["Evidence retrieval<br/>[engine.py]"]
  node_assistant_engine["AI generation<br/>[engine.py]"]
end

node_user(("User"))

node_user -.->|"uses"| node_frontend
node_connection_hooks -->|"calls"| node_connection_service
node_optimization_builder -->|"builds with"| node_pipeline_builder
node_optimization_builder -->|"builds"| node_pipeline
node_ingestion_service -->|"collects from"| node_collector
node_ingestion_service -->|"enqueues"| node_queue
node_ingestion_service -->|"requests worker"| node_dispatcher
node_ingestion_service -->|"processes with"| node_pipeline
node_ingestion_service -->|"processes via"| node_worker

click node_frontend "https://github.com/pr0xiuss/hypoquery/blob/main/frontend/src/App.jsx"
click node_connection_hooks "https://github.com/pr0xiuss/hypoquery/blob/main/frontend/src/hooks/useDatabaseConnections.js"
click node_connection_service "https://github.com/pr0xiuss/hypoquery/blob/main/frontend/src/services/databaseConnectionService.js"
click node_connection_api "https://github.com/pr0xiuss/hypoquery/blob/main/backend/platform/databases/api/db_connection_router.py"
click node_optimization_builder "https://github.com/pr0xiuss/hypoquery/blob/main/backend/optimization/pipeline/optimization_pipeline_builder.py"
click node_pipeline_builder "https://github.com/pr0xiuss/hypoquery/blob/main/backend/execution/pipeline/builder.py"
click node_pipeline "https://github.com/pr0xiuss/hypoquery/blob/main/backend/execution/pipeline/pipeline.py"
click node_analysis "https://github.com/pr0xiuss/hypoquery/tree/main/backend/optimization/analysis"
click node_recommendation "https://github.com/pr0xiuss/hypoquery/tree/main/backend/optimization/recommendation"
click node_validation "https://github.com/pr0xiuss/hypoquery/tree/main/backend/optimization/validation"
click node_ranking "https://github.com/pr0xiuss/hypoquery/tree/main/backend/optimization/ranking"
click node_reporting "https://github.com/pr0xiuss/hypoquery/tree/main/backend/optimization/reporting"
click node_history "https://github.com/pr0xiuss/hypoquery/tree/main/backend/optimization/history"
click node_ingestion_service "https://github.com/pr0xiuss/hypoquery/blob/main/backend/ingestion/services/ingestion_service.py"
click node_collector "https://github.com/pr0xiuss/hypoquery/blob/main/backend/ingestion/collectors/base_collector.py"
click node_queue "https://github.com/pr0xiuss/hypoquery/blob/main/backend/execution/queue/base_queue.py"
click node_dispatcher "https://github.com/pr0xiuss/hypoquery/blob/main/backend/execution/workers/dispatcher.py"
click node_worker "https://github.com/pr0xiuss/hypoquery/blob/main/backend/execution/workers/worker.py"
click node_context_engine "https://github.com/pr0xiuss/hypoquery/blob/main/backend/knowledge/engine.py"
click node_retrieval_engine "https://github.com/pr0xiuss/hypoquery/blob/main/backend/knowledge/retrieval/engine.py"
click node_assistant_engine "https://github.com/pr0xiuss/hypoquery/blob/main/backend/assistant/engine.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_frontend,node_connection_hooks,node_connection_service,node_connection_api,node_user toneBlue
class node_optimization_builder,node_analysis,node_recommendation,node_validation,node_ranking,node_reporting,node_history toneAmber
class node_pipeline_builder,node_pipeline,node_ingestion_service,node_collector,node_queue,node_dispatcher,node_worker toneMint
class node_context_engine,node_retrieval_engine,node_assistant_engine toneRose
```

## Components

### API and connections

- [Application UI](https://github.com/pr0xiuss/hypoquery/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Connection hooks](https://github.com/pr0xiuss/hypoquery/blob/main/frontend/src/hooks/useDatabaseConnections.js): `frontend/src/hooks/useDatabaseConnections.js`
- [Connection service](https://github.com/pr0xiuss/hypoquery/blob/main/frontend/src/services/databaseConnectionService.js): `frontend/src/services/databaseConnectionService.js`
- [Connection API](https://github.com/pr0xiuss/hypoquery/blob/main/backend/platform/databases/api/db_connection_router.py): `backend/platform/databases/api/db_connection_router.py`

### SQL optimization

- [Pipeline builder](https://github.com/pr0xiuss/hypoquery/blob/main/backend/optimization/pipeline/optimization_pipeline_builder.py): `backend/optimization/pipeline/optimization_pipeline_builder.py`
- [Plan analysis](https://github.com/pr0xiuss/hypoquery/tree/main/backend/optimization/analysis): `backend/optimization/analysis`
- [Recommendations](https://github.com/pr0xiuss/hypoquery/tree/main/backend/optimization/recommendation): `backend/optimization/recommendation`
- [Validation](https://github.com/pr0xiuss/hypoquery/tree/main/backend/optimization/validation): `backend/optimization/validation`
- [Ranking](https://github.com/pr0xiuss/hypoquery/tree/main/backend/optimization/ranking): `backend/optimization/ranking`
- [Reporting](https://github.com/pr0xiuss/hypoquery/tree/main/backend/optimization/reporting): `backend/optimization/reporting`
- [Execution history](https://github.com/pr0xiuss/hypoquery/tree/main/backend/optimization/history): `backend/optimization/history`

### Execution and ingestion

- [Execution builder](https://github.com/pr0xiuss/hypoquery/blob/main/backend/execution/pipeline/builder.py): `backend/execution/pipeline/builder.py`
- [Pipeline runtime](https://github.com/pr0xiuss/hypoquery/blob/main/backend/execution/pipeline/pipeline.py): `backend/execution/pipeline/pipeline.py`
- [Ingestion service](https://github.com/pr0xiuss/hypoquery/blob/main/backend/ingestion/services/ingestion_service.py): `backend/ingestion/services/ingestion_service.py`
- [Execution collector](https://github.com/pr0xiuss/hypoquery/blob/main/backend/ingestion/collectors/base_collector.py): `backend/ingestion/collectors/base_collector.py`
- [Execution queue](https://github.com/pr0xiuss/hypoquery/blob/main/backend/execution/queue/base_queue.py): `backend/execution/queue/base_queue.py`
- [Worker dispatcher](https://github.com/pr0xiuss/hypoquery/blob/main/backend/execution/workers/dispatcher.py): `backend/execution/workers/dispatcher.py`
- [Worker](https://github.com/pr0xiuss/hypoquery/blob/main/backend/execution/workers/worker.py): `backend/execution/workers/worker.py`

### Knowledge and assistant

- [Context assembly](https://github.com/pr0xiuss/hypoquery/blob/main/backend/knowledge/engine.py): `backend/knowledge/engine.py`
- [Evidence retrieval](https://github.com/pr0xiuss/hypoquery/blob/main/backend/knowledge/retrieval/engine.py): `backend/knowledge/retrieval/engine.py`
- [AI generation](https://github.com/pr0xiuss/hypoquery/blob/main/backend/assistant/engine.py): `backend/assistant/engine.py`

### Other components

- **User**

## Connections

- User → Application UI: uses
- Connection hooks → Connection service: calls (evidence: `frontend/src/hooks/useDatabaseConnections.js`)
- Pipeline builder → Execution builder: builds with (evidence: `backend/optimization/pipeline/optimization_pipeline_builder.py`)
- Pipeline builder → Pipeline runtime: builds (evidence: `backend/optimization/pipeline/optimization_pipeline_builder.py`)
- Ingestion service → Execution collector: collects from (evidence: `backend/ingestion/services/ingestion_service.py`)
- Ingestion service → Execution queue: enqueues (evidence: `backend/ingestion/services/ingestion_service.py`)
- Ingestion service → Worker dispatcher: requests worker (evidence: `backend/ingestion/services/ingestion_service.py`)
- Ingestion service → Pipeline runtime: processes with (evidence: `backend/ingestion/services/ingestion_service.py`)
- Ingestion service → Worker: processes via (evidence: `backend/ingestion/services/ingestion_service.py`)