# hsmshubham007-code/capstone-agent architecture

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

- Interactive diagram: https://gitdiagram.com/hsmshubham007-code/capstone-agent
- Repository: https://github.com/hsmshubham007-code/capstone-agent

## Overview

Company Policy Agent accepts policy questions through a UI or API, applies safety and routing controls, retrieves supporting policy text, and returns an answer generated by a Groq-hosted model. Separate branches handle risky actions through human approval, document indexing, durable conversation state, and operational visibility. The README also documents automated quality evaluations. Several implementation files were not sampled, so the graph includes documented capabilities but omits uncertain internal call links.

Main entry points: [`app/graph.py`](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/graph.py) (LangGraph workflow), [`app/retrieval.py`](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/retrieval.py) (Document retrieval), [`app/router.py`](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/router.py) (Tool router), [`app/llm.py`](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/llm.py) (LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["User channels"]
  node_ui["Streamlit UI<br/>[ui.py]"]
  node_api["FastAPI API<br/>[api.py]"]
end

subgraph group_workflow["Agent workflow"]
  node_agent["Agent entry<br/>[agent.py]"]
  node_graph["LangGraph workflow<br/>[graph.py]"]
  node_router["Tool router<br/>[router.py]"]
  node_llm["LLM client<br/>[llm.py]"]
end

subgraph group_knowledge["Policy knowledge"]
  node_rag["RAG answering<br/>[rag.py]"]
  node_retrieval["Document retrieval<br/>[retrieval.py]"]
  node_indexing["PDF ingestion<br/>[ingest.py]"]
  node_embeddings["Local embeddings<br/>[retrieval.py]"]
  node_vectorstore[("Chroma index<br/>[vectorstore.py]")]
end

subgraph group_controls["Safety and approvals"]
  node_safety["Safety checks<br/>[safety.py]"]
  node_guardrails["Injection guardrails<br/>[guardrails.py]"]
  node_risky["Risky tools<br/>[risky_tools.py]"]
  node_approval["Human approval<br/>[approval.py]"]
end

subgraph group_operations["Operations"]
  node_state["Conversation state<br/>[state.py]"]
  node_checkpoint[("Durable checkpoints<br/>[checkpoint.py]")]
  node_audit["Audit logging<br/>[audit.py]"]
  node_metrics["Metrics<br/>[metrics.py]"]
  node_dashboard["Monitoring dashboard"]
  node_evaluation["Evaluation suite"]
end

node_user(("Questioner"))
node_groq{{"Groq endpoint"}}
node_human(("Approver"))

node_user -->|"asks"| node_ui
node_user -->|"submits"| node_api
node_ui -->|"calls"| node_api
node_api -->|"invokes"| node_agent
node_agent -->|"starts workflow"| node_graph
node_graph -->|"routes request"| node_router
node_graph -->|"validates"| node_safety
node_graph -->|"checks injection"| node_guardrails
node_graph -->|"updates"| node_state
node_graph -->|"persists state"| node_checkpoint
node_router -->|"selects search"| node_rag
node_rag -->|"searches"| node_retrieval
node_retrieval -->|"embeds query"| node_embeddings
node_retrieval -->|"queries"| node_vectorstore
node_indexing -->|"embeds chunks"| node_embeddings
node_indexing -->|"writes chunks"| node_vectorstore
node_rag -->|"generates answer"| node_llm
node_llm -->|"requests completion"| node_groq
node_router -->|"selects risky action"| node_risky
node_graph -->|"requests authorization"| node_approval
node_human -->|"reviews"| node_approval
node_approval -->|"authorizes execution"| node_risky
node_graph -->|"records operations"| node_audit
node_llm -->|"records usage"| node_metrics
node_retrieval -->|"records timing"| node_metrics
node_dashboard -->|"reads metrics"| node_metrics
node_evaluation -->|"evaluates answers"| node_agent
node_evaluation -->|"evaluates search"| node_retrieval

click node_ui "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/ui.py"
click node_api "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/api.py"
click node_agent "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/agent.py"
click node_graph "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/graph.py"
click node_router "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/router.py"
click node_rag "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/rag.py"
click node_retrieval "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/retrieval.py"
click node_indexing "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/ingest.py"
click node_embeddings "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/retrieval.py"
click node_vectorstore "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/vectorstore.py"
click node_llm "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/llm.py"
click node_safety "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/safety.py"
click node_guardrails "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/guardrails.py"
click node_risky "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/risky_tools.py"
click node_approval "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/approval.py"
click node_state "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/state.py"
click node_checkpoint "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/checkpoint.py"
click node_audit "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/audit.py"
click node_metrics "https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/metrics.py"
click node_dashboard "https://github.com/hsmshubham007-code/capstone-agent/blob/main/monitoring_dashboard.py"
click node_evaluation "https://github.com/hsmshubham007-code/capstone-agent/tree/main/evals"

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_ui,node_api toneBlue
class node_agent,node_graph,node_router,node_llm toneAmber
class node_rag,node_retrieval,node_indexing,node_embeddings,node_vectorstore toneMint
class node_safety,node_guardrails,node_risky,node_approval toneRose
class node_state,node_checkpoint,node_audit,node_metrics,node_dashboard,node_evaluation,node_user,node_groq,node_human toneIndigo
```

## Components

### User channels

- [Streamlit UI](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/ui.py): `app/ui.py`
- [FastAPI API](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/api.py): `app/api.py`

### Agent workflow

- [Agent entry](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/agent.py): `app/agent.py`
- [LangGraph workflow](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/graph.py): `app/graph.py`
- [Tool router](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/router.py): `app/router.py`
- [LLM client](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/llm.py): `app/llm.py`

### Policy knowledge

- [RAG answering](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/rag.py): `app/rag.py`
- [Document retrieval](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/retrieval.py): `app/retrieval.py`
- [PDF ingestion](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/ingest.py): `app/ingest.py`
- [Local embeddings](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/retrieval.py): `app/retrieval.py`
- [Chroma index](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/vectorstore.py): `app/vectorstore.py`

### Safety and approvals

- [Safety checks](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/safety.py): `app/safety.py`
- [Injection guardrails](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/guardrails.py): `app/guardrails.py`
- [Risky tools](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/risky_tools.py): `app/risky_tools.py`
- [Human approval](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/approval.py): `app/approval.py`

### Operations

- [Conversation state](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/state.py): `app/state.py`
- [Durable checkpoints](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/checkpoint.py): `app/checkpoint.py`
- [Audit logging](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/audit.py): `app/audit.py`
- [Metrics](https://github.com/hsmshubham007-code/capstone-agent/blob/main/app/metrics.py): `app/metrics.py`
- [Monitoring dashboard](https://github.com/hsmshubham007-code/capstone-agent/blob/main/monitoring_dashboard.py): `monitoring_dashboard.py`
- [Evaluation suite](https://github.com/hsmshubham007-code/capstone-agent/tree/main/evals): `evals`

### Other components

- **Questioner**
- **Groq endpoint**
- **Approver**

## Connections

- Questioner → Streamlit UI: asks
- Questioner → FastAPI API: submits
- Streamlit UI → FastAPI API: calls
- FastAPI API → Agent entry: invokes
- Agent entry → LangGraph workflow: starts workflow
- LangGraph workflow → Tool router: routes request
- LangGraph workflow → Safety checks: validates
- LangGraph workflow → Injection guardrails: checks injection
- LangGraph workflow → Conversation state: updates
- LangGraph workflow → Durable checkpoints: persists state
- Tool router → RAG answering: selects search
- RAG answering → Document retrieval: searches
- Document retrieval → Local embeddings: embeds query
- Document retrieval → Chroma index: queries
- PDF ingestion → Local embeddings: embeds chunks
- PDF ingestion → Chroma index: writes chunks
- RAG answering → LLM client: generates answer
- LLM client → Groq endpoint: requests completion
- Tool router → Risky tools: selects risky action
- LangGraph workflow → Human approval: requests authorization
- Approver → Human approval: reviews
- Human approval → Risky tools: authorizes execution
- LangGraph workflow → Audit logging: records operations
- LLM client → Metrics: records usage
- Document retrieval → Metrics: records timing
- Monitoring dashboard → Metrics: reads metrics
- Evaluation suite → Agent entry: evaluates answers
- Evaluation suite → Document retrieval: evaluates search