# rohiit7762-cloud/hcl_hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/rohiit7762-cloud/hcl_hackathon
- Repository: https://github.com/rohiit7762-cloud/hcl_hackathon

## Overview

The product is an enterprise knowledge assistant: employees submit questions through Streamlit, the backend resolves trusted identity, decomposes and authorizes tasks, retrieves documents and/or queries structured data, checks evidence, drafts cited answers, and validates them before release. A separate ingestion path accepts uploads and indexes document content or structured data. The README documents the main workflow and security guarantees; several implementation details below are represented only at subsystem level because their source was not sampled.

Main entry points: [`backend/app/graph/query_graph.py`](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/graph/query_graph.py) (Query workflow), [`backend/app/services/ingestion.py`](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/services/ingestion.py) (Ingestion service), [`backend/app/api/dependencies.py`](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/api/dependencies.py) (Service wiring), [`backend/app/graph/task_graph.py`](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/graph/task_graph.py) (Task execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interface"]
  node_streamlit["Streamlit UI<br/>[streamlit_app.py]"]
  node_upload_ui["Upload page"]
  node_api_client["HTTP client<br/>[api_client.py]"]
end

subgraph group_api["API and orchestration"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_query_routes["Query endpoint<br/>[query.py]"]
  node_ingest_routes["Ingest endpoint<br/>[ingest.py]"]
  node_dependencies["Service wiring<br/>[dependencies.py]"]
  node_orchestrator["Query service<br/>[orchestration.py]"]
  node_query_workflow["Query workflow<br/>[query_graph.py]"]
  node_planner["Planner and policy check<br/>[planner.py]"]
  node_task_workflow["Task execution<br/>[task_graph.py]"]
  node_evidence["Evidence assessment<br/>[evidence.py]"]
  node_answer["Cited answer drafting<br/>[answer.py]"]
  node_contracts["Shared contracts"]
  node_configuration["Runtime configuration<br/>[config.py]"]
  node_logging["Privacy-safe logging<br/>[logging.py]"]
end

subgraph group_knowledge["Knowledge ingestion and retrieval"]
  node_retrieval["Document retrieval<br/>[retrieval.py]"]
  node_sql_agent["Structured-data queries<br/>[sql.py]"]
  node_ingestion_service["Ingestion service<br/>[ingestion.py]"]
  node_parsers["Document parsers"]
  node_chunker["Semantic chunking"]
  node_ocr["Image OCR<br/>[ocr.py]"]
  node_structured_loader["Structured loader"]
end

subgraph group_trust["Security and data"]
  node_validation["Final validation<br/>[compliance.py]"]
  node_data_layer["Data-layer factory<br/>[data_layer.py]"]
  node_repositories["Persistence adapters"]
  node_policy["Access policy<br/>[policy.py]"]
  node_identity["Identity resolution<br/>[identity.py]"]
end

node_employee(("Employee"))

node_employee -->|"asks questions"| node_streamlit
node_streamlit -->|"uses"| node_api_client
node_upload_ui -->|"uploads through"| node_api_client
node_api_client -->|"HTTP requests"| node_fastapi
node_fastapi -->|"mounts routes"| node_query_routes
node_fastapi -->|"mounts routes"| node_ingest_routes
node_query_routes -->|"resolves services"| node_dependencies
node_ingest_routes -->|"resolves services"| node_dependencies
node_dependencies -->|"builds workflow"| node_query_workflow
node_dependencies -->|"loads factory"| node_data_layer
node_query_routes -.->|"submits query"| node_orchestrator
node_orchestrator -->|"runs workflow"| node_query_workflow
node_query_workflow -->|"plans tasks"| node_planner
node_query_workflow -->|"dispatches tasks"| node_task_workflow
node_task_workflow -->|"searches documents"| node_retrieval
node_task_workflow -->|"queries structured data"| node_sql_agent
node_task_workflow -->|"checks evidence"| node_evidence
node_query_workflow -->|"drafts answer"| node_answer
node_query_workflow -->|"validates response"| node_validation
node_planner -->|"checks access"| node_policy
node_retrieval -->|"filters evidence"| node_policy
node_ingest_routes -.->|"accepts ingestion"| node_ingestion_service
node_ingestion_service -->|"parses documents"| node_parsers
node_ingestion_service -->|"chunks content"| node_chunker
node_ingestion_service -->|"extracts image text"| node_ocr
node_ingestion_service -->|"loads structured data"| node_structured_loader
node_data_layer -.->|"provides data access"| node_repositories
node_dependencies -->|"resolves identity"| node_identity

click node_streamlit "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/frontend/streamlit_app.py"
click node_upload_ui "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/frontend/pages/1_Upload_documents.py"
click node_api_client "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/frontend/api_client.py"
click node_fastapi "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/main.py"
click node_query_routes "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/api/routes/query.py"
click node_ingest_routes "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/api/routes/ingest.py"
click node_dependencies "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/api/dependencies.py"
click node_orchestrator "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/services/orchestration.py"
click node_query_workflow "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/graph/query_graph.py"
click node_planner "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/agents/planner.py"
click node_task_workflow "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/graph/task_graph.py"
click node_retrieval "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/agents/retrieval.py"
click node_sql_agent "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/agents/sql.py"
click node_evidence "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/agents/evidence.py"
click node_answer "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/agents/answer.py"
click node_validation "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/agents/compliance.py"
click node_ingestion_service "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/services/ingestion.py"
click node_parsers "https://github.com/rohiit7762-cloud/hcl_hackathon/tree/main/backend/app/ingestion/parsers"
click node_chunker "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/ingestion/semantic_chunker.py"
click node_ocr "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/ingestion/ocr.py"
click node_structured_loader "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/ingestion/structured_loader.py"
click node_data_layer "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/services/data_layer.py"
click node_repositories "https://github.com/rohiit7762-cloud/hcl_hackathon/tree/main/backend/app/repositories"
click node_policy "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/security/policy.py"
click node_identity "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/security/identity.py"
click node_contracts "https://github.com/rohiit7762-cloud/hcl_hackathon/tree/main/backend/app/schemas"
click node_configuration "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/core/config.py"
click node_logging "https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/core/logging.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_streamlit,node_upload_ui,node_api_client toneBlue
class node_fastapi,node_query_routes,node_ingest_routes,node_dependencies,node_orchestrator,node_query_workflow,node_planner,node_task_workflow,node_evidence,node_answer,node_contracts,node_configuration,node_logging toneAmber
class node_retrieval,node_sql_agent,node_ingestion_service,node_parsers,node_chunker,node_ocr,node_structured_loader toneMint
class node_validation,node_data_layer,node_repositories,node_policy,node_identity toneRose
class node_employee toneIndigo
```

## Components

### User interface

- [Streamlit UI](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/frontend/streamlit_app.py): `frontend/streamlit_app.py`
- [Upload page](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/frontend/pages/1_Upload_documents.py): `frontend/pages/1_Upload_documents.py`
- [HTTP client](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/frontend/api_client.py): `frontend/api_client.py`

### API and orchestration

- [FastAPI application](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/main.py): `backend/app/main.py`
- [Query endpoint](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/api/routes/query.py): `backend/app/api/routes/query.py`
- [Ingest endpoint](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/api/routes/ingest.py): `backend/app/api/routes/ingest.py`
- [Service wiring](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/api/dependencies.py): `backend/app/api/dependencies.py`
- [Query service](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/services/orchestration.py): `backend/app/services/orchestration.py`
- [Query workflow](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/graph/query_graph.py): `backend/app/graph/query_graph.py`
- [Planner and policy check](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/agents/planner.py): `backend/app/agents/planner.py`
- [Task execution](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/graph/task_graph.py): `backend/app/graph/task_graph.py`
- [Evidence assessment](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/agents/evidence.py): `backend/app/agents/evidence.py`
- [Cited answer drafting](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/agents/answer.py): `backend/app/agents/answer.py`
- [Shared contracts](https://github.com/rohiit7762-cloud/hcl_hackathon/tree/main/backend/app/schemas): `backend/app/schemas`
- [Runtime configuration](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [Privacy-safe logging](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/core/logging.py): `backend/app/core/logging.py`

### Knowledge ingestion and retrieval

- [Document retrieval](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/agents/retrieval.py): `backend/app/agents/retrieval.py`
- [Structured-data queries](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/agents/sql.py): `backend/app/agents/sql.py`
- [Ingestion service](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/services/ingestion.py): `backend/app/services/ingestion.py`
- [Document parsers](https://github.com/rohiit7762-cloud/hcl_hackathon/tree/main/backend/app/ingestion/parsers): `backend/app/ingestion/parsers`
- [Semantic chunking](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/ingestion/semantic_chunker.py): `backend/app/ingestion/semantic_chunker.py`
- [Image OCR](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/ingestion/ocr.py): `backend/app/ingestion/ocr.py`
- [Structured loader](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/ingestion/structured_loader.py): `backend/app/ingestion/structured_loader.py`

### Security and data

- [Final validation](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/agents/compliance.py): `backend/app/agents/compliance.py`
- [Data-layer factory](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/services/data_layer.py): `backend/app/services/data_layer.py`
- [Persistence adapters](https://github.com/rohiit7762-cloud/hcl_hackathon/tree/main/backend/app/repositories): `backend/app/repositories`
- [Access policy](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/security/policy.py): `backend/app/security/policy.py`
- [Identity resolution](https://github.com/rohiit7762-cloud/hcl_hackathon/blob/main/backend/app/security/identity.py): `backend/app/security/identity.py`

### Other components

- **Employee**

## Connections

- Employee → Streamlit UI: asks questions (evidence: `README.md`)
- Streamlit UI → HTTP client: uses (evidence: `frontend/streamlit_app.py`)
- Upload page → HTTP client: uploads through (evidence: `frontend/pages/1_Upload_documents.py`)
- HTTP client → FastAPI application: HTTP requests (evidence: `frontend/api_client.py`)
- FastAPI application → Query endpoint: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Ingest endpoint: mounts routes (evidence: `backend/app/main.py`)
- Query endpoint → Service wiring: resolves services (evidence: `backend/app/api/routes/query.py`)
- Ingest endpoint → Service wiring: resolves services (evidence: `backend/app/api/routes/ingest.py`)
- Service wiring → Query workflow: builds workflow (evidence: `backend/app/api/dependencies.py`)
- Service wiring → Data-layer factory: loads factory (evidence: `backend/app/api/dependencies.py`)
- Query endpoint → Query service: submits query
- Query service → Query workflow: runs workflow (evidence: `backend/app/services/orchestration.py`)
- Query workflow → Planner and policy check: plans tasks (evidence: `README.md`)
- Query workflow → Task execution: dispatches tasks (evidence: `backend/app/graph/query_graph.py`)
- Task execution → Document retrieval: searches documents (evidence: `README.md`)
- Task execution → Structured-data queries: queries structured data (evidence: `README.md`)
- Task execution → Evidence assessment: checks evidence (evidence: `backend/app/graph/task_graph.py`)
- Query workflow → Cited answer drafting: drafts answer (evidence: `backend/app/graph/query_graph.py`)
- Query workflow → Final validation: validates response (evidence: `backend/app/graph/query_graph.py`)
- Planner and policy check → Access policy: checks access
- Document retrieval → Access policy: filters evidence (evidence: `backend/app/agents/retrieval.py`)
- Ingest endpoint → Ingestion service: accepts ingestion
- Ingestion service → Document parsers: parses documents (evidence: `backend/app/services/ingestion.py`)
- Ingestion service → Semantic chunking: chunks content (evidence: `backend/app/services/ingestion.py`)
- Ingestion service → Image OCR: extracts image text (evidence: `backend/app/services/ingestion.py`)
- Ingestion service → Structured loader: loads structured data (evidence: `backend/app/services/ingestion.py`)
- Data-layer factory → Persistence adapters: provides data access
- Service wiring → Identity resolution: resolves identity (evidence: `backend/app/api/dependencies.py`)
