# entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot architecture

> Architecture diagram of the GitHub repository entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot
- Repository: https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot

## Overview

This is an internal HR policy and employee-support copilot. Employees submit questions through the web interface; the API delegates to a LangGraph workflow that routes simple chat directly, otherwise checks private HR evidence before using web search as a fallback, and returns a grounded answer with citations and a decision trace. HR staff can upload documents for indexing, and chat decisions are audited. The workflow, API, ingestion, vector-store, and audit code were excerpted; UI-to-page and some deployment relationships are documented in the README.

Main entry points: [`app/api/routes.py`](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/api/routes.py) (HTTP API), [`app/rag/vectorstore.py`](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/vectorstore.py) (Vector store access), [`app/rag/workflow.py`](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py) (Question routing), [`static/js/app.js`](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/static/js/app.js) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web_ui["Chat interface<br/>[app.js]"]
  node_web_page["Web page<br/>[index.html]"]
end

subgraph group_service["API and operations"]
  node_api["HTTP API<br/>[routes.py]"]
  node_app_start["Application setup<br/>[main.py]"]
  node_settings["Configuration<br/>[config.py]"]
  node_logging["Logging setup<br/>[logging.py]"]
end

subgraph group_rag["Agent workflow"]
  node_workflow["RAG controller<br/>[workflow.py]"]
  node_state["Workflow state<br/>[state.py]"]
  node_route_question["Question routing<br/>[workflow.py]"]
  node_retrieve_kb["Private retrieval<br/>[workflow.py]"]
  node_grade_kb["Private evidence grade<br/>[workflow.py]"]
  node_search_web["Web fallback search<br/>[workflow.py]"]
  node_grade_web["Web evidence grade<br/>[workflow.py]"]
  node_rewrite["Query rewrite<br/>[workflow.py]"]
  node_answers["Answer generation<br/>[workflow.py]"]
end

subgraph group_knowledge["Knowledge and audit"]
  node_ingest["Document loading<br/>[ingestion.py]"]
  node_vectorstore["Vector store access<br/>[vectorstore.py]"]
  node_pinecone[("Pinecone HR index")]
  node_audit["Decision audit<br/>[audit.py]"]
  node_sqlite[("Audit database<br/>[audit.db]")]
end

node_employee(("Employee / HR"))
node_openai{{"OpenAI models"}}
node_tavily{{"Tavily search"}}

node_employee -->|"asks question"| node_web_ui
node_web_ui -->|"posts chat"| node_api
node_web_page -.->|"hosts interface"| node_web_ui
node_app_start -->|"registers routes"| node_api
node_app_start -->|"configures"| node_logging
node_app_start -->|"initializes database"| node_audit
node_api -->|"calls ask"| node_workflow
node_api -->|"writes decision"| node_audit
node_api -->|"loads and chunks"| node_ingest
node_api -->|"indexes chunks"| node_vectorstore
node_workflow -->|"dispatches"| node_route_question
node_route_question -->|"routes HR queries"| node_retrieve_kb
node_route_question -->|"answers simple chat"| node_answers
node_retrieve_kb -->|"retrieves evidence"| node_vectorstore
node_retrieve_kb -->|"passes documents"| node_grade_kb
node_grade_kb -->|"uses sufficient evidence"| node_answers
node_grade_kb -->|"falls back if weak"| node_search_web
node_search_web -->|"searches web"| node_tavily
node_search_web -->|"passes results"| node_grade_web
node_grade_web -->|"uses sufficient evidence"| node_answers
node_grade_web -->|"retries if weak"| node_rewrite
node_rewrite -->|"retries retrieval"| node_retrieve_kb
node_answers -->|"generates responses"| node_openai
node_route_question -->|"classifies question"| node_openai
node_grade_kb -->|"grades evidence"| node_openai
node_grade_web -->|"grades evidence"| node_openai
node_rewrite -->|"rewrites query"| node_openai
node_vectorstore -->|"reads and writes vectors"| node_pinecone
node_vectorstore -->|"embeds documents"| node_openai
node_audit -->|"stores traces"| node_sqlite
node_workflow -->|"uses typed state"| node_state
node_api -->|"returns answer and trace"| node_web_ui
node_settings -->|"configures service"| node_api
node_settings -->|"configures index"| node_vectorstore

click node_web_ui "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/static/js/app.js"
click node_web_page "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/templates/index.html"
click node_api "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/api/routes.py"
click node_app_start "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/main.py"
click node_settings "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/core/config.py"
click node_logging "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/core/logging.py"
click node_ingest "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/services/ingestion.py"
click node_workflow "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py"
click node_state "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/state.py"
click node_route_question "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py"
click node_retrieve_kb "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py"
click node_grade_kb "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py"
click node_search_web "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py"
click node_grade_web "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py"
click node_rewrite "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py"
click node_answers "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py"
click node_vectorstore "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/vectorstore.py"
click node_audit "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/services/audit.py"
click node_sqlite "https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/data/audit.db"

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_web_ui,node_web_page toneBlue
class node_api,node_app_start,node_settings,node_logging toneAmber
class node_workflow,node_state,node_route_question,node_retrieve_kb,node_grade_kb,node_search_web,node_grade_web,node_rewrite,node_answers toneMint
class node_ingest,node_vectorstore,node_pinecone,node_audit,node_sqlite toneRose
class node_employee,node_openai,node_tavily toneIndigo
```

## Components

### User experience

- [Chat interface](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/static/js/app.js): `static/js/app.js`
- [Web page](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/templates/index.html): `templates/index.html`

### API and operations

- [HTTP API](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/api/routes.py): `app/api/routes.py`
- [Application setup](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/main.py): `app/main.py`
- [Configuration](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/core/config.py): `app/core/config.py`
- [Logging setup](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/core/logging.py): `app/core/logging.py`

### Agent workflow

- [RAG controller](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py): `app/rag/workflow.py`
- [Workflow state](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/state.py): `app/rag/state.py`
- [Question routing](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py): `app/rag/workflow.py`
- [Private retrieval](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py): `app/rag/workflow.py`
- [Private evidence grade](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py): `app/rag/workflow.py`
- [Web fallback search](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py): `app/rag/workflow.py`
- [Web evidence grade](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py): `app/rag/workflow.py`
- [Query rewrite](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py): `app/rag/workflow.py`
- [Answer generation](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/workflow.py): `app/rag/workflow.py`

### Knowledge and audit

- [Document loading](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/services/ingestion.py): `app/services/ingestion.py`
- [Vector store access](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/rag/vectorstore.py): `app/rag/vectorstore.py`
- **Pinecone HR index**
- [Decision audit](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/app/services/audit.py): `app/services/audit.py`
- [Audit database](https://github.com/entbappy/enterprise-hr-policy-employee-support-agentic-rag-copilot/blob/main/data/audit.db): `data/audit.db`

### Other components

- **Employee / HR**
- **OpenAI models**
- **Tavily search**

## Connections

- Employee / HR → Chat interface: asks question (evidence: `README.md`)
- Chat interface → HTTP API: posts chat (evidence: `static/js/app.js`)
- Web page → Chat interface: hosts interface (evidence: `README.md`)
- Application setup → HTTP API: registers routes (evidence: `app/main.py`)
- Application setup → Logging setup: configures (evidence: `app/main.py`)
- Application setup → Decision audit: initializes database (evidence: `app/main.py`)
- HTTP API → RAG controller: calls ask (evidence: `app/api/routes.py`)
- HTTP API → Decision audit: writes decision (evidence: `app/api/routes.py`)
- HTTP API → Document loading: loads and chunks (evidence: `app/api/routes.py`)
- HTTP API → Vector store access: indexes chunks (evidence: `app/api/routes.py`)
- RAG controller → Question routing: dispatches (evidence: `app/rag/workflow.py`)
- Question routing → Private retrieval: routes HR queries (evidence: `app/rag/workflow.py`)
- Question routing → Answer generation: answers simple chat (evidence: `app/rag/workflow.py`)
- Private retrieval → Vector store access: retrieves evidence (evidence: `app/rag/workflow.py`)
- Private retrieval → Private evidence grade: passes documents (evidence: `app/rag/workflow.py`)
- Private evidence grade → Answer generation: uses sufficient evidence (evidence: `app/rag/workflow.py`)
- Private evidence grade → Web fallback search: falls back if weak (evidence: `app/rag/workflow.py`)
- Web fallback search → Tavily search: searches web (evidence: `app/rag/workflow.py`)
- Web fallback search → Web evidence grade: passes results (evidence: `app/rag/workflow.py`)
- Web evidence grade → Answer generation: uses sufficient evidence (evidence: `app/rag/workflow.py`)
- Web evidence grade → Query rewrite: retries if weak (evidence: `app/rag/workflow.py`)
- Query rewrite → Private retrieval: retries retrieval (evidence: `app/rag/workflow.py`)
- Answer generation → OpenAI models: generates responses (evidence: `app/rag/workflow.py`)
- Question routing → OpenAI models: classifies question (evidence: `app/rag/workflow.py`)
- Private evidence grade → OpenAI models: grades evidence (evidence: `app/rag/workflow.py`)
- Web evidence grade → OpenAI models: grades evidence (evidence: `app/rag/workflow.py`)
- Query rewrite → OpenAI models: rewrites query (evidence: `app/rag/workflow.py`)
- Vector store access → Pinecone HR index: reads and writes vectors (evidence: `app/rag/vectorstore.py`)
- Vector store access → OpenAI models: embeds documents (evidence: `app/rag/vectorstore.py`)
- Decision audit → Audit database: stores traces (evidence: `app/services/audit.py`)
- RAG controller → Workflow state: uses typed state (evidence: `app/rag/workflow.py`)
- HTTP API → Chat interface: returns answer and trace (evidence: `static/js/app.js`)
- Configuration → HTTP API: configures service (evidence: `app/api/routes.py`)
- Configuration → Vector store access: configures index (evidence: `app/rag/vectorstore.py`)
