# ghsaidi/employee-hr-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/ghsaidi/employee-hr-assistant
- Repository: https://github.com/ghsaidi/employee-hr-assistant

## Overview

Employees submit independent policy questions through the chat UI or backend CLI. The web request passes through a Next.js proxy to FastAPI, which applies concurrency and optional quota controls, retrieves indexed PDF passages, and asks OpenAI to produce a cited answer. The CLI also indexes PDFs and runs direct chat. The README documents production S3 index loading and DynamoDB quotas; infrastructure details are not mapped as repository components. Source excerpts show the core calls; broader deployment wiring is documented only in the README.

Main entry points: [`backend/src/employee_hr_assistant/rag/direct.py`](https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/rag/direct.py) (RAG engine), [`backend/src/employee_hr_assistant/api/app.py`](https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/api/app.py) (FastAPI chat), [`frontend/src/components/Chat.tsx`](https://github.com/ghsaidi/employee-hr-assistant/blob/main/frontend/src/components/Chat.tsx) (Chat UI), [`frontend/src/app/page.tsx`](https://github.com/ghsaidi/employee-hr-assistant/blob/main/frontend/src/app/page.tsx) (Chat page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Chat interface"]
  node_chat_ui["Chat UI<br/>[Chat.tsx]"]
  node_home["Chat page<br/>[page.tsx]"]
  node_proxy["Chat proxy<br/>[route.ts]"]
end

subgraph group_service["API service"]
  node_api["FastAPI chat<br/>[app.py]"]
  node_cli["CLI<br/>[main.py]"]
end

subgraph group_knowledge["Policy knowledge"]
  node_rag["RAG engine<br/>[direct.py]"]
  node_pdfs["Policy PDFs"]
  node_chroma[("Chroma index<br/>[direct.py]")]
  node_s3_loader["S3 index loader<br/>[index_storage.py]"]
end

subgraph group_limits["Usage controls"]
  node_quota["Quota guard<br/>[app.py]"]
  node_limiter["Usage limiter<br/>[rate_limits.py]"]
end

node_employee(("Employee"))
node_openai{{"OpenAI API"}}
node_dynamo[("DynamoDB counters")]
node_browser(("Browser"))

node_employee -->|"asks"| node_chat_ui
node_browser -->|"opens"| node_home
node_home -->|"renders"| node_chat_ui
node_chat_ui -->|"posts question"| node_proxy
node_proxy -->|"forwards request"| node_api
node_api -->|"reserves allowance"| node_quota
node_quota -->|"checks quota"| node_limiter
node_limiter -->|"updates counters"| node_dynamo
node_api -->|"answers question"| node_rag
node_rag -->|"queries index"| node_chroma
node_rag -->|"embeds and generates"| node_openai
node_rag -->|"extracts and chunks"| node_pdfs
node_rag -->|"writes embeddings"| node_chroma
node_s3_loader -->|"loads startup index"| node_chroma
node_cli -->|"indexes or chats"| node_rag
node_api -.->|"returns answer and sources"| node_chat_ui

click node_chat_ui "https://github.com/ghsaidi/employee-hr-assistant/blob/main/frontend/src/components/Chat.tsx"
click node_home "https://github.com/ghsaidi/employee-hr-assistant/blob/main/frontend/src/app/page.tsx"
click node_proxy "https://github.com/ghsaidi/employee-hr-assistant/blob/main/frontend/src/app/api/chat/route.ts"
click node_api "https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/api/app.py"
click node_cli "https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/main.py"
click node_rag "https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/rag/direct.py"
click node_pdfs "https://github.com/ghsaidi/employee-hr-assistant/tree/main/data/documents"
click node_chroma "https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/rag/direct.py"
click node_s3_loader "https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/api/index_storage.py"
click node_quota "https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/api/app.py"
click node_limiter "https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/api/rate_limits.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_chat_ui,node_home,node_proxy,node_browser toneBlue
class node_api,node_cli,node_dynamo toneAmber
class node_rag,node_pdfs,node_chroma,node_s3_loader,node_openai toneMint
class node_quota,node_limiter toneRose
class node_employee toneIndigo
```

## Components

### Chat interface

- [Chat UI](https://github.com/ghsaidi/employee-hr-assistant/blob/main/frontend/src/components/Chat.tsx): `frontend/src/components/Chat.tsx`
- [Chat page](https://github.com/ghsaidi/employee-hr-assistant/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Chat proxy](https://github.com/ghsaidi/employee-hr-assistant/blob/main/frontend/src/app/api/chat/route.ts): `frontend/src/app/api/chat/route.ts`

### API service

- [FastAPI chat](https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/api/app.py): `backend/src/employee_hr_assistant/api/app.py`
- [CLI](https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/main.py): `backend/src/employee_hr_assistant/main.py`

### Policy knowledge

- [RAG engine](https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/rag/direct.py): `backend/src/employee_hr_assistant/rag/direct.py`
- [Policy PDFs](https://github.com/ghsaidi/employee-hr-assistant/tree/main/data/documents): `data/documents`
- [Chroma index](https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/rag/direct.py): `backend/src/employee_hr_assistant/rag/direct.py`
- [S3 index loader](https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/api/index_storage.py): `backend/src/employee_hr_assistant/api/index_storage.py`

### Usage controls

- [Quota guard](https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/api/app.py): `backend/src/employee_hr_assistant/api/app.py`
- [Usage limiter](https://github.com/ghsaidi/employee-hr-assistant/blob/main/backend/src/employee_hr_assistant/api/rate_limits.py): `backend/src/employee_hr_assistant/api/rate_limits.py`

### Other components

- **Employee**
- **OpenAI API**
- **DynamoDB counters**
- **Browser**

## Connections

- Employee → Chat UI: asks (evidence: `frontend/src/components/Chat.tsx`)
- Browser → Chat page: opens (evidence: `README.md`)
- Chat page → Chat UI: renders (evidence: `frontend/src/app/page.tsx`)
- Chat UI → Chat proxy: posts question (evidence: `frontend/src/components/Chat.tsx`)
- Chat proxy → FastAPI chat: forwards request (evidence: `frontend/src/app/api/chat/route.ts`)
- FastAPI chat → Quota guard: reserves allowance (evidence: `backend/src/employee_hr_assistant/api/app.py`)
- Quota guard → Usage limiter: checks quota (evidence: `backend/src/employee_hr_assistant/api/app.py`)
- Usage limiter → DynamoDB counters: updates counters (evidence: `README.md`)
- FastAPI chat → RAG engine: answers question (evidence: `backend/src/employee_hr_assistant/api/app.py`)
- RAG engine → Chroma index: queries index (evidence: `backend/src/employee_hr_assistant/rag/direct.py`)
- RAG engine → OpenAI API: embeds and generates (evidence: `backend/src/employee_hr_assistant/rag/direct.py`)
- RAG engine → Policy PDFs: extracts and chunks (evidence: `README.md`)
- RAG engine → Chroma index: writes embeddings (evidence: `backend/src/employee_hr_assistant/rag/direct.py`)
- S3 index loader → Chroma index: loads startup index (evidence: `backend/src/employee_hr_assistant/api/app.py`)
- CLI → RAG engine: indexes or chats (evidence: `backend/src/employee_hr_assistant/main.py`)
- FastAPI chat → Chat UI: returns answer and sources (evidence: `README.md`)