# priyagaggar/hr-policy-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/priyagaggar/hr-policy-assistant
- Repository: https://github.com/priyagaggar/hr-policy-assistant

## Overview

HR Policy Assistant lets employees ask questions grounded in uploaded PDF/DOCX policies, with page-level citations and document downloads. Admins upload and remove policies; ingestion parses and chunks files, embeds chunks, and stores vectors in Pinecone, while the chat route embeds questions, retrieves matches, and asks Groq to compose cited answers. The README describes the product’s RAG workflow; the sampled chat route shows Groq as the answer model. Some UI-to-API behavior is documented rather than visible in the sampled page source.

Main entry points: [`src/app/api/upload/route.ts`](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/api/upload/route.ts) (Upload API), [`src/app/api/chat/route.ts`](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/api/chat/route.ts) (Chat API), [`src/app/api/document/route.ts`](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/api/document/route.ts) (Document download API), [`src/app/admin/page.tsx`](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/admin/page.tsx) (Admin panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_employee["Employee chat"]
  node_chatpage["Chat portal<br/>[page.tsx]"]
  node_message["Message display<br/>[MessageBubble.tsx]"]
  node_citation["Source citations<br/>[SourceCitation.tsx]"]
end

subgraph group_admin["Policy administration"]
  node_adminpage["Admin panel<br/>[page.tsx]"]
  node_uploadui["Upload panel<br/>[UploadPanel.tsx]"]
  node_doclist["Document list<br/>[DocumentList.tsx]"]
end

subgraph group_ingestion["Document ingestion"]
  node_uploadapi["Upload API<br/>[route.ts]"]
  node_pdfparser["PDF parsing<br/>[pdf-parser.ts]"]
  node_docxparser["DOCX parsing<br/>[docx-parser.ts]"]
end

subgraph group_rag["Retrieval and answers"]
  node_embeddings["Embedding service<br/>[embeddings.ts]"]
  node_chatapi["Chat API<br/>[route.ts]"]
  node_documentapi["Document download API<br/>[route.ts]"]
end

subgraph group_storage["External services"]
  node_pineconeclient["Pinecone client<br/>[pinecone.ts]"]
  node_pinecone[("Pinecone index")]
  node_blob[("Vercel Blob")]
  node_gemini["Google Gemini"]
  node_groq["Groq LLM"]
end

node_employee(("Employee"))
node_adminuser(("Administrator"))

node_employee -->|"asks policy questions"| node_chatpage
node_chatpage -->|"renders messages"| node_message
node_message -->|"renders references"| node_citation
node_chatpage -.->|"submits questions"| node_chatapi
node_adminuser -->|"manages policies"| node_adminpage
node_adminpage -->|"renders"| node_uploadui
node_adminpage -->|"renders"| node_doclist
node_uploadui -->|"uploads files"| node_uploadapi
node_adminpage -->|"deletes files"| node_uploadapi
node_uploadapi -->|"parses PDFs"| node_pdfparser
node_uploadapi -->|"parses DOCX"| node_docxparser
node_uploadapi -->|"stores originals"| node_blob
node_uploadapi -->|"embeds chunks"| node_embeddings
node_embeddings -->|"requests embeddings"| node_gemini
node_uploadapi -->|"gets index"| node_pineconeclient
node_pineconeclient -->|"connects to"| node_pinecone
node_uploadapi -->|"upserts vectors"| node_pinecone
node_chatapi -->|"embeds question"| node_embeddings
node_chatapi -->|"gets index"| node_pineconeclient
node_chatapi -->|"queries vectors"| node_pinecone
node_chatapi -->|"generates answer"| node_groq
node_chatapi -->|"includes download links"| node_documentapi
node_documentapi -->|"embeds filename"| node_embeddings
node_documentapi -->|"gets index"| node_pineconeclient
node_documentapi -->|"looks up blob URL"| node_pinecone
node_documentapi -->|"redirects download"| node_blob

click node_chatpage "https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/page.tsx"
click node_message "https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/components/MessageBubble.tsx"
click node_citation "https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/components/SourceCitation.tsx"
click node_adminpage "https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/admin/page.tsx"
click node_uploadui "https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/components/UploadPanel.tsx"
click node_doclist "https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/components/DocumentList.tsx"
click node_uploadapi "https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/api/upload/route.ts"
click node_pdfparser "https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/lib/pdf-parser.ts"
click node_docxparser "https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/lib/docx-parser.ts"
click node_embeddings "https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/lib/embeddings.ts"
click node_chatapi "https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/api/chat/route.ts"
click node_documentapi "https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/api/document/route.ts"
click node_pineconeclient "https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/lib/pinecone.ts"

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_chatpage,node_message,node_citation toneBlue
class node_adminpage,node_uploadui,node_doclist toneAmber
class node_uploadapi,node_pdfparser,node_docxparser toneMint
class node_embeddings,node_chatapi,node_documentapi toneRose
class node_pineconeclient,node_pinecone,node_blob,node_gemini,node_groq,node_employee,node_adminuser toneIndigo
```

## Components

### Employee chat

- [Chat portal](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Message display](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/components/MessageBubble.tsx): `src/components/MessageBubble.tsx`
- [Source citations](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/components/SourceCitation.tsx): `src/components/SourceCitation.tsx`

### Policy administration

- [Admin panel](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/admin/page.tsx): `src/app/admin/page.tsx`
- [Upload panel](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/components/UploadPanel.tsx): `src/components/UploadPanel.tsx`
- [Document list](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/components/DocumentList.tsx): `src/components/DocumentList.tsx`

### Document ingestion

- [Upload API](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/api/upload/route.ts): `src/app/api/upload/route.ts`
- [PDF parsing](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/lib/pdf-parser.ts): `src/lib/pdf-parser.ts`
- [DOCX parsing](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/lib/docx-parser.ts): `src/lib/docx-parser.ts`

### Retrieval and answers

- [Embedding service](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/lib/embeddings.ts): `src/lib/embeddings.ts`
- [Chat API](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Document download API](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/app/api/document/route.ts): `src/app/api/document/route.ts`

### External services

- [Pinecone client](https://github.com/priyagaggar/hr-policy-assistant/blob/main/src/lib/pinecone.ts): `src/lib/pinecone.ts`
- **Pinecone index**
- **Vercel Blob**
- **Google Gemini**
- **Groq LLM**

### Other components

- **Employee**
- **Administrator**

## Connections

- Employee → Chat portal: asks policy questions (evidence: `README.md`)
- Chat portal → Message display: renders messages (evidence: `src/app/page.tsx`)
- Message display → Source citations: renders references (evidence: `src/components/MessageBubble.tsx`)
- Chat portal → Chat API: submits questions (evidence: `README.md`)
- Administrator → Admin panel: manages policies (evidence: `README.md`)
- Admin panel → Upload panel: renders (evidence: `src/app/admin/page.tsx`)
- Admin panel → Document list: renders (evidence: `src/app/admin/page.tsx`)
- Upload panel → Upload API: uploads files (evidence: `src/components/UploadPanel.tsx`)
- Admin panel → Upload API: deletes files (evidence: `src/app/admin/page.tsx`)
- Upload API → PDF parsing: parses PDFs (evidence: `src/app/api/upload/route.ts`)
- Upload API → DOCX parsing: parses DOCX (evidence: `src/app/api/upload/route.ts`)
- Upload API → Vercel Blob: stores originals (evidence: `src/app/api/upload/route.ts`)
- Upload API → Embedding service: embeds chunks (evidence: `src/app/api/upload/route.ts`)
- Embedding service → Google Gemini: requests embeddings (evidence: `src/lib/embeddings.ts`)
- Upload API → Pinecone client: gets index (evidence: `src/app/api/upload/route.ts`)
- Pinecone client → Pinecone index: connects to (evidence: `src/lib/pinecone.ts`)
- Upload API → Pinecone index: upserts vectors (evidence: `src/app/api/upload/route.ts`)
- Chat API → Embedding service: embeds question (evidence: `src/app/api/chat/route.ts`)
- Chat API → Pinecone client: gets index (evidence: `src/app/api/chat/route.ts`)
- Chat API → Pinecone index: queries vectors (evidence: `src/app/api/chat/route.ts`)
- Chat API → Groq LLM: generates answer (evidence: `src/app/api/chat/route.ts`)
- Chat API → Document download API: includes download links (evidence: `src/app/api/chat/route.ts`)
- Document download API → Embedding service: embeds filename (evidence: `src/app/api/document/route.ts`)
- Document download API → Pinecone client: gets index (evidence: `src/app/api/document/route.ts`)
- Document download API → Pinecone index: looks up blob URL (evidence: `src/app/api/document/route.ts`)
- Document download API → Vercel Blob: redirects download (evidence: `src/app/api/document/route.ts`)