HR App

Where Everything Comes Together

Modules 1-4 built the infrastructure: data lake, encoding pipeline, retrieval system, AI gateway. Module 5 is where it becomes a product that employees actually use. The goal is deceptively simple: a chat interface where someone types "What's our parental leave policy in California?" and gets an accurate, cited answer in under 3 seconds.

But "simple" on the surface requires sophisticated orchestration underneath.

The Chat Architecture

Message Flow

Employee types query
    ↓
Frontend sends POST /api/chat
    ↓
API classifies query category
    ↓
Retrieval system searches (filtered by category)
    ↓
AI Gateway processes (guardrails → route → LLM)
    ↓
Response streams back via SSE
    ↓
Frontend renders with citations

Every step is visible in the code. There's no magic — just a pipeline where each stage does one thing well.

Server-Sent Events (SSE)

The chat uses SSE streaming, not WebSockets. Why?

Each SSE event carries a JSON payload:

data: {"content": "Based on our", "category": "Leave & PTO"}
data: {"content": "Based on our PTO policy", "category": "Leave & PTO"}
data: {"content": "Based on our PTO policy (POL-001,", "citations": [...], "category": "Leave & PTO"}
data: [DONE]

The frontend accumulates content and displays the growing response in real time. Citations arrive with the final chunk.

Query Routing

Not all HR questions should search the same data. The routing layer detects what kind of question is being asked and targets the search accordingly:

Category Detection

This isn't just for UI badges — it determines which source_type filter is applied during retrieval. A benefits question searches the benefits guide first, falling back to other sources only if needed.

Multi-Source Questions

Some questions span categories: "If I take parental leave, what happens to my health insurance?" This touches both Leave and Benefits. The router detects multi-category queries and searches across both, then merges and reranks the results.

Citations: The Trust Layer

Every response from the HR assistant includes citations. This isn't a nice-to-have — it's what makes employees trust the system over Googling or asking a coworker.

Citation Format

Source: PTO Policy (POL-001, v4.0, effective 2025-01-01)
Section: Carryover Rules

Each citation includes:

Why Effective Dates Matter

Imagine a policy was updated on March 1, 2025. An employee asks about something that happened in February 2025. The AI should cite the *old* version that was in effect at the time, not the current version. While the basic system always cites the latest version, the citation metadata enables auditing: "This answer is based on v4.0, effective 2025-01-01."

Employee Context

In a production deployment, the chat knows who's asking:

This context is passed to the retrieval system as filters and to the AI gateway for confidentiality enforcement. The same question from a California engineer and a Texas salesperson can produce different — and correct — answers.

Quick Actions

The UI includes pre-built query buttons for the most common HR questions:

These aren't just convenience — they're data collection. Tracking which quick actions get clicked tells HR which topics employees ask about most, informing which policies to clarify or simplify.

Conversation Persistence

Every conversation is saved:

{
  conversation_id: "conv_123",
  employee_id: "EMP-008",
  messages: [...],
  topic_tags: ["leave", "california"],
  started_at: "2025-11-15T10:30:00Z",
  satisfaction_rating: 4,  // optional post-chat rating
}

This data serves three purposes:

What You'll Build

Glossary