# alyab16/employee-onboarding-agent architecture

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

- Interactive diagram: https://gitdiagram.com/alyab16/employee-onboarding-agent
- Repository: https://github.com/alyab16/employee-onboarding-agent

## Overview

An employee uses the chat UI to request onboarding actions or policy answers. The chat API streams a supervisor-led specialist workflow; write-capable actions pause for review, then resume through the API. Specialists use MCP integrations for HR, training, access approvals/tickets and related SaaS records, or the knowledge tools for hybrid policy retrieval. The README documents checkpointed conversation state and configurable model/tracing integrations; their implementations are not sampled here, so uncertain wiring is omitted. MCP and RAG capabilities are represented from the README and tree.

Main entry points: [`backend/agent/specialists.py`](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/agent/specialists.py) (Scoped Specialists), [`backend/agent/orchestrator.py`](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/agent/orchestrator.py) (Graph Orchestrator), [`backend/database/engine.py`](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/database/engine.py) (Mock SaaS Records), [`frontend/app/hooks/useChat.ts`](https://github.com/alyab16/employee-onboarding-agent/blob/main/frontend/app/hooks/useChat.ts) (Chat Streaming State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Employee UI"]
  node_chat_ui["Chat and Approval UI<br/>[ChatInterface.tsx]"]
  node_chat_state["Chat Streaming State<br/>[useChat.ts]"]
  node_approval_card["Editable Approval Card<br/>[MessageBubble.tsx]"]
end

subgraph group_service["Chat Service"]
  node_chat_api["Chat SSE API<br/>[chat.py]"]
  node_app["Application Startup<br/>[main.py]"]
end

subgraph group_agents["Agent Workflow"]
  node_orchestrator["Graph Orchestrator<br/>[orchestrator.py]"]
  node_supervisor["Supervisor Router<br/>[supervisor.py]"]
  node_specialists["Scoped Specialists<br/>[specialists.py]"]
  node_hitl["Write Approval Gate<br/>[hitl.py]"]
  node_checkpoints[("Graph Checkpoints")]
end

subgraph group_integrations["Onboarding Integrations"]
  node_hr["HR Profile Tools<br/>[hr_server.py]"]
  node_training["Training Tools<br/>[training_server.py]"]
  node_it["IT Access Tools<br/>[it_server.py]"]
  node_slack["Slack Tools<br/>[slack_server.py]"]
  node_salesforce["Salesforce Tools"]
  node_records[("Mock SaaS Records<br/>[engine.py]")]
end

subgraph group_knowledge["Policy Knowledge"]
  node_knowledge_tools["Knowledge Search Tools<br/>[knowledge_tools.py]"]
  node_vector_store[("Hybrid RAG Index<br/>[vector_store.py]")]
  node_policy_docs["Policy Documents"]
end

node_employee(("Employee"))
node_model{{"Language Model"}}
node_tracing(("LangSmith Tracing"))

node_employee -->|"requests onboarding"| node_chat_ui
node_chat_ui -->|"handles chat"| node_chat_state
node_chat_state -->|"POSTs chat or resume"| node_chat_api
node_chat_api -->|"streams or resumes"| node_orchestrator
node_orchestrator -->|"runs graph"| node_supervisor
node_supervisor -->|"routes turns"| node_specialists
node_orchestrator -->|"emits SSE events"| node_chat_api
node_chat_api -->|"streams SSE"| node_chat_state
node_chat_state -->|"renders approval"| node_approval_card
node_approval_card -->|"submits decision"| node_chat_state
node_orchestrator -->|"gates writes"| node_hitl
node_hitl -->|"interrupts or resumes"| node_orchestrator
node_orchestrator -.->|"reads and writes state"| node_checkpoints
node_specialists -.->|"requests completions"| node_model
node_supervisor -.->|"routes with structured output"| node_model
node_orchestrator -.->|"traces runs"| node_tracing
node_specialists -->|"calls profile tools"| node_hr
node_specialists -->|"calls training tools"| node_training
node_specialists -->|"calls access tools"| node_it
node_specialists -->|"calls profile tools"| node_slack
node_specialists -->|"calls profile tools"| node_salesforce
node_hr -->|"reads and writes"| node_records
node_training -->|"reads and writes"| node_records
node_it -->|"reads and writes"| node_records
node_slack -->|"reads and writes"| node_records
node_salesforce -->|"reads and writes"| node_records
node_specialists -->|"calls search tool"| node_knowledge_tools
node_knowledge_tools -->|"queries index"| node_vector_store
node_policy_docs -->|"indexed at startup"| node_vector_store
node_app -->|"creates runtime"| node_orchestrator
node_app -->|"initializes index"| node_vector_store
node_app -->|"initializes database"| node_records

click node_chat_ui "https://github.com/alyab16/employee-onboarding-agent/blob/main/frontend/app/components/ChatInterface.tsx"
click node_chat_state "https://github.com/alyab16/employee-onboarding-agent/blob/main/frontend/app/hooks/useChat.ts"
click node_approval_card "https://github.com/alyab16/employee-onboarding-agent/blob/main/frontend/app/components/MessageBubble.tsx"
click node_chat_api "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/api/chat.py"
click node_app "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/main.py"
click node_orchestrator "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/agent/orchestrator.py"
click node_supervisor "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/agent/supervisor.py"
click node_specialists "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/agent/specialists.py"
click node_hitl "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/agent/hitl.py"
click node_hr "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/mcp_servers/hr_server.py"
click node_training "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/mcp_servers/training_server.py"
click node_it "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/mcp_servers/it_server.py"
click node_slack "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/mcp_servers/slack_server.py"
click node_salesforce "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/mcp_servers/salesforce_server.py"
click node_records "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/database/engine.py"
click node_knowledge_tools "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/agent/knowledge_tools.py"
click node_vector_store "https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/knowledge/vector_store.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_chat_state,node_approval_card toneBlue
class node_chat_api,node_app toneAmber
class node_orchestrator,node_supervisor,node_specialists,node_hitl,node_checkpoints toneMint
class node_hr,node_training,node_it,node_slack,node_salesforce,node_records toneRose
class node_knowledge_tools,node_vector_store,node_policy_docs,node_employee,node_model,node_tracing toneIndigo
```

## Components

### Employee UI

- [Chat and Approval UI](https://github.com/alyab16/employee-onboarding-agent/blob/main/frontend/app/components/ChatInterface.tsx): `frontend/app/components/ChatInterface.tsx`
- [Chat Streaming State](https://github.com/alyab16/employee-onboarding-agent/blob/main/frontend/app/hooks/useChat.ts): `frontend/app/hooks/useChat.ts`
- [Editable Approval Card](https://github.com/alyab16/employee-onboarding-agent/blob/main/frontend/app/components/MessageBubble.tsx): `frontend/app/components/MessageBubble.tsx`

### Chat Service

- [Chat SSE API](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/api/chat.py): `backend/api/chat.py`
- [Application Startup](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/main.py): `backend/main.py`

### Agent Workflow

- [Graph Orchestrator](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/agent/orchestrator.py): `backend/agent/orchestrator.py`
- [Supervisor Router](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/agent/supervisor.py): `backend/agent/supervisor.py`
- [Scoped Specialists](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/agent/specialists.py): `backend/agent/specialists.py`
- [Write Approval Gate](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/agent/hitl.py): `backend/agent/hitl.py`
- **Graph Checkpoints**

### Onboarding Integrations

- [HR Profile Tools](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/mcp_servers/hr_server.py): `backend/mcp_servers/hr_server.py`
- [Training Tools](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/mcp_servers/training_server.py): `backend/mcp_servers/training_server.py`
- [IT Access Tools](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/mcp_servers/it_server.py): `backend/mcp_servers/it_server.py`
- [Slack Tools](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/mcp_servers/slack_server.py): `backend/mcp_servers/slack_server.py`
- [Salesforce Tools](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/mcp_servers/salesforce_server.py): `backend/mcp_servers/salesforce_server.py`
- [Mock SaaS Records](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/database/engine.py): `backend/database/engine.py`

### Policy Knowledge

- [Knowledge Search Tools](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/agent/knowledge_tools.py): `backend/agent/knowledge_tools.py`
- [Hybrid RAG Index](https://github.com/alyab16/employee-onboarding-agent/blob/main/backend/knowledge/vector_store.py): `backend/knowledge/vector_store.py`
- **Policy Documents**

### Other components

- **Employee**
- **Language Model**
- **LangSmith Tracing**

## Connections

- Employee → Chat and Approval UI: requests onboarding
- Chat and Approval UI → Chat Streaming State: handles chat
- Chat Streaming State → Chat SSE API: POSTs chat or resume
- Chat SSE API → Graph Orchestrator: streams or resumes
- Graph Orchestrator → Supervisor Router: runs graph
- Supervisor Router → Scoped Specialists: routes turns
- Graph Orchestrator → Chat SSE API: emits SSE events
- Chat SSE API → Chat Streaming State: streams SSE
- Chat Streaming State → Editable Approval Card: renders approval
- Editable Approval Card → Chat Streaming State: submits decision
- Graph Orchestrator → Write Approval Gate: gates writes
- Write Approval Gate → Graph Orchestrator: interrupts or resumes
- Graph Orchestrator → Graph Checkpoints: reads and writes state
- Scoped Specialists → Language Model: requests completions
- Supervisor Router → Language Model: routes with structured output
- Graph Orchestrator → LangSmith Tracing: traces runs
- Scoped Specialists → HR Profile Tools: calls profile tools
- Scoped Specialists → Training Tools: calls training tools
- Scoped Specialists → IT Access Tools: calls access tools
- Scoped Specialists → Slack Tools: calls profile tools
- Scoped Specialists → Salesforce Tools: calls profile tools
- HR Profile Tools → Mock SaaS Records: reads and writes
- Training Tools → Mock SaaS Records: reads and writes
- IT Access Tools → Mock SaaS Records: reads and writes
- Slack Tools → Mock SaaS Records: reads and writes
- Salesforce Tools → Mock SaaS Records: reads and writes
- Scoped Specialists → Knowledge Search Tools: calls search tool
- Knowledge Search Tools → Hybrid RAG Index: queries index
- Policy Documents → Hybrid RAG Index: indexed at startup
- Application Startup → Graph Orchestrator: creates runtime
- Application Startup → Hybrid RAG Index: initializes index
- Application Startup → Mock SaaS Records: initializes database