# shivamteotia/disha-hr architecture

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

- Interactive diagram: https://gitdiagram.com/shivamteotia/disha-hr
- Repository: https://github.com/shivamteotia/disha-hr

## Overview

DISHA HR is a mobile-friendly HR application with employee self-service and administration workflows, plus Disha, an assistant for policy and scoped HR-data questions. Users sign in through the Next.js app, which calls the FastAPI API for HR operations; chat requests are routed by the LangGraph agent and streamed back to the UI. The graph preserves the documented policy-RAG and guarded text-to-SQL branches. Some backend modules and frontend pages were not sampled, so their internal wiring is omitted where it cannot be established.

Main entry points: [`frontend/lib.js`](https://github.com/shivamteotia/disha-hr/blob/main/frontend/lib.js) (API client), [`backend/app/agent.py`](https://github.com/shivamteotia/disha-hr/blob/main/backend/app/agent.py) (LangGraph agent), [`backend/app/main.py`](https://github.com/shivamteotia/disha-hr/blob/main/backend/app/main.py) (FastAPI HR API), [`backend/app/knowledge.py`](https://github.com/shivamteotia/disha-hr/blob/main/backend/app/knowledge.py) (Policy retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_login["Sign in<br/>[page.js]"]
  node_shell["App shell<br/>[Shell.js]"]
  node_api_client["API client<br/>[lib.js]"]
  node_dashboard["Dashboard<br/>[page.js]"]
  node_employees_ui["Employee directory<br/>[page.js]"]
  node_leaves_ui["Leave requests<br/>[page.js]"]
  node_payslips_ui["Payslips<br/>[page.js]"]
  node_other_pages["HR pages"]
  node_chat_ui["Chat popup<br/>[DishaChat.js]"]
end

subgraph group_hr["HR operations"]
  node_api["FastAPI HR API<br/>[main.py]"]
  node_hr_records["HR records<br/>[main.py]"]
end

subgraph group_assistant["Disha assistant"]
  node_agent["LangGraph agent<br/>[agent.py]"]
  node_rails{{"Input and output rails<br/>[rails.py]"}}
  node_sql_guard["Scoped SQL guard<br/>[safe_sql.py]"]
  node_policy_search["Policy retrieval<br/>[knowledge.py]"]
end

subgraph group_data["Data and policy"]
  node_database[("HR database<br/>[db.py]")]
  node_policy_docs["Company policies"]
end

node_employee(("Employee or admin"))
node_qdrant[("Qdrant")]
node_openai(("OpenAI models"))

node_employee -->|"signs in"| node_login
node_login -->|"submits credentials"| node_api_client
node_shell -->|"loads session"| node_api_client
node_dashboard -->|"requests HR data"| node_api_client
node_employees_ui -->|"manages employees"| node_api_client
node_leaves_ui -->|"manages leave"| node_api_client
node_payslips_ui -->|"requests payslips"| node_api_client
node_other_pages -->|"uses HR API"| node_api_client
node_chat_ui -->|"streams chat"| node_api_client
node_api_client -->|"calls endpoints"| node_api
node_api -->|"handles HR workflows"| node_hr_records
node_api -->|"reads and writes"| node_database
node_api -->|"dispatches chat"| node_agent
node_agent -->|"checks input and output"| node_rails
node_agent -->|"retrieves policy"| node_policy_search
node_agent -->|"queries scoped data"| node_sql_guard
node_policy_search -->|"searches content"| node_policy_docs
node_policy_search -.->|"searches vectors"| node_qdrant
node_agent -.->|"plans and responds"| node_openai
node_policy_search -.->|"embeds and reranks"| node_openai
node_sql_guard -->|"reads scoped views"| node_database

click node_login "https://github.com/shivamteotia/disha-hr/blob/main/frontend/app/login/page.js"
click node_shell "https://github.com/shivamteotia/disha-hr/blob/main/frontend/components/Shell.js"
click node_api_client "https://github.com/shivamteotia/disha-hr/blob/main/frontend/lib.js"
click node_dashboard "https://github.com/shivamteotia/disha-hr/blob/main/frontend/app/(app)/page.js"
click node_employees_ui "https://github.com/shivamteotia/disha-hr/blob/main/frontend/app/(app)/employees/page.js"
click node_leaves_ui "https://github.com/shivamteotia/disha-hr/blob/main/frontend/app/(app)/leaves/page.js"
click node_payslips_ui "https://github.com/shivamteotia/disha-hr/blob/main/frontend/app/(app)/payslips/page.js"
click node_other_pages "https://github.com/shivamteotia/disha-hr/tree/main/frontend/app/(app)"
click node_chat_ui "https://github.com/shivamteotia/disha-hr/blob/main/frontend/components/DishaChat.js"
click node_api "https://github.com/shivamteotia/disha-hr/blob/main/backend/app/main.py"
click node_hr_records "https://github.com/shivamteotia/disha-hr/blob/main/backend/app/main.py"
click node_agent "https://github.com/shivamteotia/disha-hr/blob/main/backend/app/agent.py"
click node_rails "https://github.com/shivamteotia/disha-hr/blob/main/backend/app/rails.py"
click node_sql_guard "https://github.com/shivamteotia/disha-hr/blob/main/backend/app/safe_sql.py"
click node_policy_search "https://github.com/shivamteotia/disha-hr/blob/main/backend/app/knowledge.py"
click node_database "https://github.com/shivamteotia/disha-hr/blob/main/backend/app/db.py"
click node_policy_docs "https://github.com/shivamteotia/disha-hr/tree/main/data/policies"

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_login,node_shell,node_api_client,node_dashboard,node_employees_ui,node_leaves_ui,node_payslips_ui,node_other_pages,node_chat_ui toneBlue
class node_api,node_hr_records,node_qdrant toneAmber
class node_agent,node_rails,node_sql_guard,node_policy_search toneMint
class node_database,node_policy_docs toneRose
class node_employee,node_openai toneIndigo
```

## Components

### Web app

- [Sign in](https://github.com/shivamteotia/disha-hr/blob/main/frontend/app/login/page.js): `frontend/app/login/page.js`
- [App shell](https://github.com/shivamteotia/disha-hr/blob/main/frontend/components/Shell.js): `frontend/components/Shell.js`
- [API client](https://github.com/shivamteotia/disha-hr/blob/main/frontend/lib.js): `frontend/lib.js`
- [Dashboard](https://github.com/shivamteotia/disha-hr/blob/main/frontend/app/(app)/page.js): `frontend/app/(app)/page.js`
- [Employee directory](https://github.com/shivamteotia/disha-hr/blob/main/frontend/app/(app)/employees/page.js): `frontend/app/(app)/employees/page.js`
- [Leave requests](https://github.com/shivamteotia/disha-hr/blob/main/frontend/app/(app)/leaves/page.js): `frontend/app/(app)/leaves/page.js`
- [Payslips](https://github.com/shivamteotia/disha-hr/blob/main/frontend/app/(app)/payslips/page.js): `frontend/app/(app)/payslips/page.js`
- [HR pages](https://github.com/shivamteotia/disha-hr/tree/main/frontend/app/(app)): `frontend/app/(app)`
- [Chat popup](https://github.com/shivamteotia/disha-hr/blob/main/frontend/components/DishaChat.js): `frontend/components/DishaChat.js`

### HR operations

- [FastAPI HR API](https://github.com/shivamteotia/disha-hr/blob/main/backend/app/main.py): `backend/app/main.py`
- [HR records](https://github.com/shivamteotia/disha-hr/blob/main/backend/app/main.py): `backend/app/main.py`

### Disha assistant

- [LangGraph agent](https://github.com/shivamteotia/disha-hr/blob/main/backend/app/agent.py): `backend/app/agent.py`
- [Input and output rails](https://github.com/shivamteotia/disha-hr/blob/main/backend/app/rails.py): `backend/app/rails.py`
- [Scoped SQL guard](https://github.com/shivamteotia/disha-hr/blob/main/backend/app/safe_sql.py): `backend/app/safe_sql.py`
- [Policy retrieval](https://github.com/shivamteotia/disha-hr/blob/main/backend/app/knowledge.py): `backend/app/knowledge.py`

### Data and policy

- [HR database](https://github.com/shivamteotia/disha-hr/blob/main/backend/app/db.py): `backend/app/db.py`
- [Company policies](https://github.com/shivamteotia/disha-hr/tree/main/data/policies): `data/policies`

### Other components

- **Employee or admin**
- **Qdrant**
- **OpenAI models**

## Connections

- Employee or admin → Sign in: signs in
- Sign in → API client: submits credentials
- App shell → API client: loads session
- Dashboard → API client: requests HR data
- Employee directory → API client: manages employees
- Leave requests → API client: manages leave
- Payslips → API client: requests payslips
- HR pages → API client: uses HR API
- Chat popup → API client: streams chat
- API client → FastAPI HR API: calls endpoints
- FastAPI HR API → HR records: handles HR workflows
- FastAPI HR API → HR database: reads and writes
- FastAPI HR API → LangGraph agent: dispatches chat
- LangGraph agent → Input and output rails: checks input and output
- LangGraph agent → Policy retrieval: retrieves policy
- LangGraph agent → Scoped SQL guard: queries scoped data
- Policy retrieval → Company policies: searches content
- Policy retrieval → Qdrant: searches vectors
- LangGraph agent → OpenAI models: plans and responds
- Policy retrieval → OpenAI models: embeds and reranks
- Scoped SQL guard → HR database: reads scoped views