# rajmohandp/workassistai architecture

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

- Interactive diagram: https://gitdiagram.com/rajmohandp/workassistai
- Repository: https://github.com/rajmohandp/workassistai

## Overview

WorkAssist AI serves employee support through a Streamlit chat and a FastAPI backend. Requests are classified and routed to PTO balance assistance, document retrieval, or combined answers; administrators can synchronize S3 documents into Pinecone. The graph preserves the documented ingestion, conversational RAG, guardrail, citation, and handoff capabilities. Several service and UI links are based on the README or SOURCE INDEX rather than complete source excerpts; those limits are reflected by omitting uncertain edges or marking them unverified.

Main entry points: [`src/vector_store.py`](https://github.com/rajmohandp/workassistai/blob/main/src/vector_store.py) (Index and sync), [`app/api/routes.py`](https://github.com/rajmohandp/workassistai/blob/main/app/api/routes.py) (HTTP routes), [`app/agent/nodes.py`](https://github.com/rajmohandp/workassistai/blob/main/app/agent/nodes.py) (Agent actions), [`app/agent/graph.py`](https://github.com/rajmohandp/workassistai/blob/main/app/agent/graph.py) (Request graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interfaces"]
  node_streamlit["Streamlit chat<br/>[app.py]"]
  node_ui_client["API client<br/>[frontend_client.py]"]
end

subgraph group_api["API and agent orchestration"]
  node_api_routes["HTTP routes<br/>[routes.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_agent_graph["Request graph<br/>[graph.py]"]
  node_agent_router["Intent router<br/>[router.py]"]
  node_agent_nodes["Agent actions<br/>[nodes.py]"]
  node_agent_state["Conversation state<br/>[state.py]"]
end

subgraph group_knowledge["Document knowledge"]
  node_rag_service["RAG service<br/>[rag_service.py]"]
  node_rag_chain["RAG answer chain<br/>[rag_chain.py]"]
  node_retriever["Semantic retrieval<br/>[retriever.py]"]
  node_guardrails["RAG guardrails<br/>[guardrails.py]"]
  node_s3_loader["S3 document loader<br/>[s3_loader.py]"]
  node_processor["Chunk processor"]
  node_embeddings["Embedding provider<br/>[embeddings.py]"]
  node_vector_store["Index and sync<br/>[vector_store.py]"]
end

subgraph group_pto["PTO and support"]
  node_pto_tool["PTO tool<br/>[pto_tool.py]"]
  node_pto_repo["PTO repository<br/>[pto_repository.py]"]
  node_handoff["Human handoff<br/>[handoff_service.py]"]
end

subgraph group_platform["Identity and operations"]
  node_auth["Authentication<br/>[security.py]"]
  node_logging["Structured logging<br/>[logging_config.py]"]
end

node_employee(("Employee"))
node_admin(("Administrator"))
node_s3[("Amazon S3")]
node_pinecone[("Pinecone index")]
node_database[("Employee database")]

node_employee -->|"asks question"| node_streamlit
node_admin -->|"manages sync"| node_streamlit
node_streamlit -->|"uses"| node_ui_client
node_ui_client -.->|"sends requests"| node_api_routes
node_api_routes -->|"validates requests"| node_schemas
node_api_routes -->|"authenticates"| node_auth
node_api_routes -->|"executes"| node_agent_graph
node_agent_graph -->|"classifies"| node_agent_router
node_agent_graph -->|"dispatches"| node_agent_nodes
node_agent_graph -->|"carries state"| node_agent_state
node_agent_nodes -->|"invokes"| node_pto_tool
node_agent_nodes -->|"invokes"| node_rag_service
node_agent_nodes -->|"requests support"| node_handoff
node_pto_tool -->|"reads balances"| node_pto_repo
node_pto_repo -->|"queries"| node_database
node_rag_service -->|"runs answer flow"| node_rag_chain
node_rag_chain -->|"retrieves evidence"| node_retriever
node_rag_chain -->|"checks content"| node_guardrails
node_retriever -->|"searches index"| node_vector_store
node_vector_store -->|"indexes and deletes vectors"| node_pinecone
node_vector_store -->|"scans documents"| node_s3_loader
node_vector_store -->|"chunks documents"| node_processor
node_vector_store -->|"embeds chunks"| node_embeddings
node_s3_loader -->|"lists and loads"| node_s3
node_admin -->|"initiates synchronization"| node_vector_store
node_api_routes -->|"requests sync"| node_vector_store
node_agent_nodes -->|"looks up balances"| node_pto_repo
node_api_routes -.->|"logs operations"| node_logging

click node_streamlit "https://github.com/rajmohandp/workassistai/blob/main/app.py"
click node_ui_client "https://github.com/rajmohandp/workassistai/blob/main/app/frontend_client.py"
click node_api_routes "https://github.com/rajmohandp/workassistai/blob/main/app/api/routes.py"
click node_schemas "https://github.com/rajmohandp/workassistai/blob/main/app/api/schemas.py"
click node_agent_graph "https://github.com/rajmohandp/workassistai/blob/main/app/agent/graph.py"
click node_agent_router "https://github.com/rajmohandp/workassistai/blob/main/app/agent/router.py"
click node_agent_nodes "https://github.com/rajmohandp/workassistai/blob/main/app/agent/nodes.py"
click node_agent_state "https://github.com/rajmohandp/workassistai/blob/main/app/agent/state.py"
click node_rag_service "https://github.com/rajmohandp/workassistai/blob/main/app/services/rag_service.py"
click node_rag_chain "https://github.com/rajmohandp/workassistai/blob/main/src/rag_chain.py"
click node_retriever "https://github.com/rajmohandp/workassistai/blob/main/src/retriever.py"
click node_guardrails "https://github.com/rajmohandp/workassistai/blob/main/src/guardrails.py"
click node_s3_loader "https://github.com/rajmohandp/workassistai/blob/main/src/s3_loader.py"
click node_processor "https://github.com/rajmohandp/workassistai/blob/main/src/document_processor.py"
click node_embeddings "https://github.com/rajmohandp/workassistai/blob/main/src/embeddings.py"
click node_vector_store "https://github.com/rajmohandp/workassistai/blob/main/src/vector_store.py"
click node_pto_tool "https://github.com/rajmohandp/workassistai/blob/main/app/tools/pto_tool.py"
click node_pto_repo "https://github.com/rajmohandp/workassistai/blob/main/app/repositories/pto_repository.py"
click node_handoff "https://github.com/rajmohandp/workassistai/blob/main/app/services/handoff_service.py"
click node_auth "https://github.com/rajmohandp/workassistai/blob/main/app/core/security.py"
click node_logging "https://github.com/rajmohandp/workassistai/blob/main/src/logging_config.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_streamlit,node_ui_client toneBlue
class node_api_routes,node_schemas,node_agent_graph,node_agent_router,node_agent_nodes,node_agent_state,node_s3,node_pinecone,node_database toneAmber
class node_rag_service,node_rag_chain,node_retriever,node_guardrails,node_s3_loader,node_processor,node_embeddings,node_vector_store toneMint
class node_pto_tool,node_pto_repo,node_handoff toneRose
class node_auth,node_logging,node_employee,node_admin toneIndigo
```

## Components

### User interfaces

- [Streamlit chat](https://github.com/rajmohandp/workassistai/blob/main/app.py): `app.py`
- [API client](https://github.com/rajmohandp/workassistai/blob/main/app/frontend_client.py): `app/frontend_client.py`

### API and agent orchestration

- [HTTP routes](https://github.com/rajmohandp/workassistai/blob/main/app/api/routes.py): `app/api/routes.py`
- [API schemas](https://github.com/rajmohandp/workassistai/blob/main/app/api/schemas.py): `app/api/schemas.py`
- [Request graph](https://github.com/rajmohandp/workassistai/blob/main/app/agent/graph.py): `app/agent/graph.py`
- [Intent router](https://github.com/rajmohandp/workassistai/blob/main/app/agent/router.py): `app/agent/router.py`
- [Agent actions](https://github.com/rajmohandp/workassistai/blob/main/app/agent/nodes.py): `app/agent/nodes.py`
- [Conversation state](https://github.com/rajmohandp/workassistai/blob/main/app/agent/state.py): `app/agent/state.py`

### Document knowledge

- [RAG service](https://github.com/rajmohandp/workassistai/blob/main/app/services/rag_service.py): `app/services/rag_service.py`
- [RAG answer chain](https://github.com/rajmohandp/workassistai/blob/main/src/rag_chain.py): `src/rag_chain.py`
- [Semantic retrieval](https://github.com/rajmohandp/workassistai/blob/main/src/retriever.py): `src/retriever.py`
- [RAG guardrails](https://github.com/rajmohandp/workassistai/blob/main/src/guardrails.py): `src/guardrails.py`
- [S3 document loader](https://github.com/rajmohandp/workassistai/blob/main/src/s3_loader.py): `src/s3_loader.py`
- [Chunk processor](https://github.com/rajmohandp/workassistai/blob/main/src/document_processor.py): `src/document_processor.py`
- [Embedding provider](https://github.com/rajmohandp/workassistai/blob/main/src/embeddings.py): `src/embeddings.py`
- [Index and sync](https://github.com/rajmohandp/workassistai/blob/main/src/vector_store.py): `src/vector_store.py`

### PTO and support

- [PTO tool](https://github.com/rajmohandp/workassistai/blob/main/app/tools/pto_tool.py): `app/tools/pto_tool.py`
- [PTO repository](https://github.com/rajmohandp/workassistai/blob/main/app/repositories/pto_repository.py): `app/repositories/pto_repository.py`
- [Human handoff](https://github.com/rajmohandp/workassistai/blob/main/app/services/handoff_service.py): `app/services/handoff_service.py`

### Identity and operations

- [Authentication](https://github.com/rajmohandp/workassistai/blob/main/app/core/security.py): `app/core/security.py`
- [Structured logging](https://github.com/rajmohandp/workassistai/blob/main/src/logging_config.py): `src/logging_config.py`

### Other components

- **Employee**
- **Administrator**
- **Amazon S3**
- **Pinecone index**
- **Employee database**

## Connections

- Employee → Streamlit chat: asks question (evidence: `README.md`)
- Administrator → Streamlit chat: manages sync (evidence: `README.md`)
- Streamlit chat → API client: uses (evidence: `app.py`)
- API client → HTTP routes: sends requests
- HTTP routes → API schemas: validates requests (evidence: `app/api/routes.py`)
- HTTP routes → Authentication: authenticates (evidence: `app/api/routes.py`)
- HTTP routes → Request graph: executes (evidence: `app/api/routes.py`)
- Request graph → Intent router: classifies (evidence: `app/agent/graph.py`)
- Request graph → Agent actions: dispatches (evidence: `app/agent/graph.py`)
- Request graph → Conversation state: carries state (evidence: `app/agent/graph.py`)
- Agent actions → PTO tool: invokes (evidence: `app/agent/nodes.py`)
- Agent actions → RAG service: invokes (evidence: `app/agent/nodes.py`)
- Agent actions → Human handoff: requests support (evidence: `app/agent/nodes.py`)
- PTO tool → PTO repository: reads balances (evidence: `app/tools/pto_tool.py`)
- PTO repository → Employee database: queries (evidence: `app/repositories/pto_repository.py`)
- RAG service → RAG answer chain: runs answer flow (evidence: `app/services/rag_service.py`)
- RAG answer chain → Semantic retrieval: retrieves evidence (evidence: `src/rag_chain.py`)
- RAG answer chain → RAG guardrails: checks content (evidence: `src/rag_chain.py`)
- Semantic retrieval → Index and sync: searches index (evidence: `src/retriever.py`)
- Index and sync → Pinecone index: indexes and deletes vectors (evidence: `README.md`)
- Index and sync → S3 document loader: scans documents (evidence: `src/vector_store.py`)
- Index and sync → Chunk processor: chunks documents (evidence: `src/vector_store.py`)
- Index and sync → Embedding provider: embeds chunks (evidence: `src/vector_store.py`)
- S3 document loader → Amazon S3: lists and loads (evidence: `README.md`)
- Administrator → Index and sync: initiates synchronization (evidence: `README.md`)
- HTTP routes → Index and sync: requests sync (evidence: `app/api/routes.py`)
- Agent actions → PTO repository: looks up balances (evidence: `app/agent/nodes.py`)
- HTTP routes → Structured logging: logs operations
