# surjithk73/hpe_49 architecture

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

- Interactive diagram: https://gitdiagram.com/surjithk73/hpe_49
- Repository: https://github.com/surjithk73/hpe_49

## Overview

QueryCraft turns analyst questions into validated SQL, executes them against a selected HPE NonStop database, and presents results with charts and downloadable reports. The README documents a planner/metric-verification clarification stage before SQL generation; the backend entry point owns the broader request pipeline. The graph also includes database/cache management and audit capabilities. Some subsystem wiring is based on the README because the relevant source excerpts were not provided.

Main entry points: [`backend/main.py`](https://github.com/surjithk73/hpe_49/blob/main/backend/main.py) (REST API), [`frontend/src/pages/Dashboard.tsx`](https://github.com/surjithk73/hpe_49/blob/main/frontend/src/pages/Dashboard.tsx) (Query dashboard), [`frontend/src/lib/api.ts`](https://github.com/surjithk73/hpe_49/blob/main/frontend/src/lib/api.ts) (API client), [`frontend/src/components/QueryInput.tsx`](https://github.com/surjithk73/hpe_49/blob/main/frontend/src/components/QueryInput.tsx) (Query input)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Analyst experience"]
  node_dashboard["Query dashboard<br/>[Dashboard.tsx]"]
  node_query_input["Query input<br/>[QueryInput.tsx]"]
  node_results["Results and charts<br/>[ResultsTable.tsx]"]
  node_sql_preview["SQL preview<br/>[SQLPreview.tsx]"]
  node_report_download["Report download<br/>[ReportDownload.tsx]"]
  node_database_ui["Database manager"]
  node_cache_ui["Cache management"]
end

subgraph group_api["API orchestration"]
  node_api_client["API client<br/>[api.ts]"]
  node_api["REST API<br/>[main.py]"]
end

subgraph group_query["Query pipeline"]
  node_normalizer["Query normalizer<br/>[normalizer.py]"]
  node_planner["Intent planner<br/>[planner.py]"]
  node_intent_spec["Intent verifier<br/>[intent_spec.py]"]
  node_schema_linker["Schema linker<br/>[schema_linker.py]"]
  node_schema_loader["Schema loader<br/>[schema_loader.py]"]
  node_few_shot["Example retrieval"]
  node_prompt_builder["Instruction builder<br/>[prompt_builder.py]"]
  node_sql_generator["SQL generator<br/>[sql_generator.py]"]
  node_validator["SQL validator<br/>[validator.py]"]
  node_executor["Query executor<br/>[executor.py]"]
  node_report_generator["Report generator"]
end

subgraph group_data["Data and operations"]
  node_cache[("Query cache<br/>[cache.py]")]
  node_audit[("Audit log<br/>[query_log.py]")]
end

node_analyst(("Analyst"))
node_database[("PostgreSQL")]
node_llm_service["LLM providers"]

node_analyst -->|"uses"| node_dashboard
node_dashboard -->|"accepts query"| node_query_input
node_query_input -->|"submits query"| node_api_client
node_api_client -->|"HTTP request"| node_api
node_api -->|"normalizes"| node_normalizer
node_api -->|"plans intent"| node_planner
node_planner -->|"requests plan"| node_llm_service
node_api -->|"checks completeness"| node_intent_spec
node_api -->|"links schema"| node_schema_linker
node_schema_linker -->|"reads schema"| node_schema_loader
node_api -->|"retrieves examples"| node_few_shot
node_api -->|"builds instructions"| node_prompt_builder
node_api -->|"generates SQL"| node_sql_generator
node_sql_generator -->|"requests SQL"| node_llm_service
node_api -->|"validates SQL"| node_validator
node_api -->|"executes SQL"| node_executor
node_executor -->|"queries"| node_database
node_api -->|"checks and stores"| node_cache
node_api -->|"logs query"| node_audit
node_api -->|"generates export"| node_report_generator
node_api -->|"returns results"| node_dashboard
node_dashboard -->|"shows rows"| node_results
node_dashboard -->|"shows SQL"| node_sql_preview
node_dashboard -->|"offers export"| node_report_download
node_analyst -->|"manages databases"| node_database_ui
node_database_ui -->|"calls database API"| node_api_client
node_analyst -->|"manages cache"| node_cache_ui
node_cache_ui -->|"calls cache API"| node_api_client
node_api -->|"manages selected data"| node_database

click node_dashboard "https://github.com/surjithk73/hpe_49/blob/main/frontend/src/pages/Dashboard.tsx"
click node_query_input "https://github.com/surjithk73/hpe_49/blob/main/frontend/src/components/QueryInput.tsx"
click node_results "https://github.com/surjithk73/hpe_49/blob/main/frontend/src/components/ResultsTable.tsx"
click node_sql_preview "https://github.com/surjithk73/hpe_49/blob/main/frontend/src/components/SQLPreview.tsx"
click node_report_download "https://github.com/surjithk73/hpe_49/blob/main/frontend/src/components/ReportDownload.tsx"
click node_database_ui "https://github.com/surjithk73/hpe_49/blob/main/frontend/src/pages/DatabaseManager.tsx"
click node_cache_ui "https://github.com/surjithk73/hpe_49/blob/main/frontend/src/pages/CacheManagement.tsx"
click node_api_client "https://github.com/surjithk73/hpe_49/blob/main/frontend/src/lib/api.ts"
click node_api "https://github.com/surjithk73/hpe_49/blob/main/backend/main.py"
click node_normalizer "https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/normalizer.py"
click node_planner "https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/planner.py"
click node_intent_spec "https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/intent_spec.py"
click node_schema_linker "https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/schema_linker.py"
click node_schema_loader "https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/schema_loader.py"
click node_few_shot "https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/few_shot_retriever.py"
click node_prompt_builder "https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/prompt_builder.py"
click node_sql_generator "https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/sql_generator.py"
click node_validator "https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/validator.py"
click node_executor "https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/executor.py"
click node_report_generator "https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/report_generator.py"
click node_cache "https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/cache.py"
click node_audit "https://github.com/surjithk73/hpe_49/blob/main/backend/audit/query_log.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_dashboard,node_query_input,node_results,node_sql_preview,node_report_download,node_database_ui,node_cache_ui toneBlue
class node_api_client,node_api,node_database toneAmber
class node_normalizer,node_planner,node_intent_spec,node_schema_linker,node_schema_loader,node_few_shot,node_prompt_builder,node_sql_generator,node_validator,node_executor,node_report_generator toneMint
class node_cache,node_audit toneRose
class node_analyst,node_llm_service toneIndigo
```

## Components

### Analyst experience

- [Query dashboard](https://github.com/surjithk73/hpe_49/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Query input](https://github.com/surjithk73/hpe_49/blob/main/frontend/src/components/QueryInput.tsx): `frontend/src/components/QueryInput.tsx`
- [Results and charts](https://github.com/surjithk73/hpe_49/blob/main/frontend/src/components/ResultsTable.tsx): `frontend/src/components/ResultsTable.tsx`
- [SQL preview](https://github.com/surjithk73/hpe_49/blob/main/frontend/src/components/SQLPreview.tsx): `frontend/src/components/SQLPreview.tsx`
- [Report download](https://github.com/surjithk73/hpe_49/blob/main/frontend/src/components/ReportDownload.tsx): `frontend/src/components/ReportDownload.tsx`
- [Database manager](https://github.com/surjithk73/hpe_49/blob/main/frontend/src/pages/DatabaseManager.tsx): `frontend/src/pages/DatabaseManager.tsx`
- [Cache management](https://github.com/surjithk73/hpe_49/blob/main/frontend/src/pages/CacheManagement.tsx): `frontend/src/pages/CacheManagement.tsx`

### API orchestration

- [API client](https://github.com/surjithk73/hpe_49/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [REST API](https://github.com/surjithk73/hpe_49/blob/main/backend/main.py): `backend/main.py`

### Query pipeline

- [Query normalizer](https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/normalizer.py): `backend/pipeline/normalizer.py`
- [Intent planner](https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/planner.py): `backend/pipeline/planner.py`
- [Intent verifier](https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/intent_spec.py): `backend/pipeline/intent_spec.py`
- [Schema linker](https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/schema_linker.py): `backend/pipeline/schema_linker.py`
- [Schema loader](https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/schema_loader.py): `backend/pipeline/schema_loader.py`
- [Example retrieval](https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/few_shot_retriever.py): `backend/pipeline/few_shot_retriever.py`
- [Instruction builder](https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/prompt_builder.py): `backend/pipeline/prompt_builder.py`
- [SQL generator](https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/sql_generator.py): `backend/pipeline/sql_generator.py`
- [SQL validator](https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/validator.py): `backend/pipeline/validator.py`
- [Query executor](https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/executor.py): `backend/pipeline/executor.py`
- [Report generator](https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/report_generator.py): `backend/pipeline/report_generator.py`

### Data and operations

- [Query cache](https://github.com/surjithk73/hpe_49/blob/main/backend/pipeline/cache.py): `backend/pipeline/cache.py`
- [Audit log](https://github.com/surjithk73/hpe_49/blob/main/backend/audit/query_log.py): `backend/audit/query_log.py`

### Other components

- **Analyst**
- **PostgreSQL**
- **LLM providers**

## Connections

- Analyst → Query dashboard: uses
- Query dashboard → Query input: accepts query
- Query input → API client: submits query
- API client → REST API: HTTP request
- REST API → Query normalizer: normalizes
- REST API → Intent planner: plans intent
- Intent planner → LLM providers: requests plan
- REST API → Intent verifier: checks completeness
- REST API → Schema linker: links schema
- Schema linker → Schema loader: reads schema
- REST API → Example retrieval: retrieves examples
- REST API → Instruction builder: builds instructions
- REST API → SQL generator: generates SQL
- SQL generator → LLM providers: requests SQL
- REST API → SQL validator: validates SQL
- REST API → Query executor: executes SQL
- Query executor → PostgreSQL: queries
- REST API → Query cache: checks and stores
- REST API → Audit log: logs query
- REST API → Report generator: generates export
- REST API → Query dashboard: returns results
- Query dashboard → Results and charts: shows rows
- Query dashboard → SQL preview: shows SQL
- Query dashboard → Report download: offers export
- Analyst → Database manager: manages databases
- Database manager → API client: calls database API
- Analyst → Cache management: manages cache
- Cache management → API client: calls cache API
- REST API → PostgreSQL: manages selected data