# abhishsing/practo-support-agent architecture

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

- Interactive diagram: https://gitdiagram.com/abhishsing/practo-support-agent
- Repository: https://github.com/abhishsing/practo-support-agent

## Overview

Practo is an offline clinic-support application for policy questions and appointment-status queries. Requests enter through HTTP or WebSocket endpoints, pass privacy, injection, budget, and caching controls, then use a sequential agent crew to retrieve policy evidence and/or look up appointment records; grounded drafts may receive a separate review before schema-validated responses are returned. The repository also supports policy-document ingestion and indexing. Relationships reflect the excerpts and README; unsampled implementation details are represented only where documented.

Main entry points: [`agents/crew.py`](https://github.com/abhishsing/practo-support-agent/blob/main/agents/crew.py) (Sequential agent crew), [`api/main.py`](https://github.com/abhishsing/practo-support-agent/blob/main/api/main.py) (HTTP and chat API), [`rag/index.py`](https://github.com/abhishsing/practo-support-agent/blob/main/rag/index.py) (Policy indexer), [`api/logging_utils.py`](https://github.com/abhishsing/practo-support-agent/blob/main/api/logging_utils.py) (Masked event logging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request handling"]
  node_api["HTTP and chat API<br/>[main.py]"]
  node_logger["Masked event logging<br/>[logging_utils.py]"]
end

subgraph group_agents["Support workflow"]
  node_crew["Sequential agent crew<br/>[crew.py]"]
  node_mockllm["Offline language model<br/>[mock_llm.py]"]
  node_response["Response schema<br/>[schemas.py]"]
end

subgraph group_knowledge["Policy knowledge"]
  node_policytool["Policy lookup tool<br/>[tools.py]"]
  node_retrieval["Similarity retrieval<br/>[retrieve.py]"]
  node_kb["Clinic policy documents"]
  node_chunking["Chunk strategies<br/>[chunking.py]"]
  node_indexing["Policy indexer<br/>[index.py]"]
  node_vectorstore[("Chroma collections<br/>[index.py]")]
end

subgraph group_records["Appointment data"]
  node_appointmenttool["Appointment lookup<br/>[tools.py]"]
  node_dataset["Appointment records<br/>[dataset.py]"]
end

subgraph group_safety["Governance and review"]
  node_guards["Request guardrails<br/>[guardrails.py]"]
  node_budget["Query budget<br/>[policy.py]"]
  node_cache[("Generation cache<br/>[cache.py]")]
  node_review["Draft review<br/>[autogen_review.py]"]
end

node_client(("Clinic user"))

node_client -->|"submits query"| node_api
node_api -->|"runs query"| node_crew
node_api -->|"logs request"| node_logger
node_api -->|"maps budget errors"| node_budget
node_api -->|"appends documents"| node_kb
node_api -->|"indexes additions"| node_indexing
node_logger -->|"masks phones"| node_guards
node_crew -->|"checks requests"| node_guards
node_crew -->|"checks budget"| node_budget
node_crew -->|"caches generation"| node_cache
node_crew -->|"uses model"| node_mockllm
node_crew -->|"dispatches lookup"| node_policytool
node_crew -->|"dispatches lookup"| node_appointmenttool
node_crew -->|"reviews grounded drafts"| node_review
node_crew -->|"validates response"| node_response
node_policytool -->|"retrieves evidence"| node_retrieval
node_retrieval -->|"queries collection"| node_vectorstore
node_indexing -->|"loads documents"| node_kb
node_indexing -->|"creates chunks"| node_chunking
node_indexing -->|"upserts embeddings"| node_vectorstore
node_appointmenttool -->|"looks up records"| node_dataset

click node_api "https://github.com/abhishsing/practo-support-agent/blob/main/api/main.py"
click node_logger "https://github.com/abhishsing/practo-support-agent/blob/main/api/logging_utils.py"
click node_guards "https://github.com/abhishsing/practo-support-agent/blob/main/agents/guardrails.py"
click node_budget "https://github.com/abhishsing/practo-support-agent/blob/main/governance/policy.py"
click node_cache "https://github.com/abhishsing/practo-support-agent/blob/main/governance/cache.py"
click node_crew "https://github.com/abhishsing/practo-support-agent/blob/main/agents/crew.py"
click node_mockllm "https://github.com/abhishsing/practo-support-agent/blob/main/llm/mock_llm.py"
click node_response "https://github.com/abhishsing/practo-support-agent/blob/main/agents/schemas.py"
click node_policytool "https://github.com/abhishsing/practo-support-agent/blob/main/agents/tools.py"
click node_retrieval "https://github.com/abhishsing/practo-support-agent/blob/main/rag/retrieve.py"
click node_kb "https://github.com/abhishsing/practo-support-agent/tree/main/kb"
click node_chunking "https://github.com/abhishsing/practo-support-agent/blob/main/rag/chunking.py"
click node_indexing "https://github.com/abhishsing/practo-support-agent/blob/main/rag/index.py"
click node_vectorstore "https://github.com/abhishsing/practo-support-agent/blob/main/rag/index.py"
click node_appointmenttool "https://github.com/abhishsing/practo-support-agent/blob/main/agents/tools.py"
click node_dataset "https://github.com/abhishsing/practo-support-agent/blob/main/dataset.py"
click node_review "https://github.com/abhishsing/practo-support-agent/blob/main/review/autogen_review.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_api,node_logger,node_client toneBlue
class node_crew,node_mockllm,node_response toneAmber
class node_policytool,node_retrieval,node_kb,node_chunking,node_indexing,node_vectorstore toneMint
class node_appointmenttool,node_dataset toneRose
class node_guards,node_budget,node_cache,node_review toneIndigo
```

## Components

### Request handling

- [HTTP and chat API](https://github.com/abhishsing/practo-support-agent/blob/main/api/main.py): `api/main.py`
- [Masked event logging](https://github.com/abhishsing/practo-support-agent/blob/main/api/logging_utils.py): `api/logging_utils.py`

### Support workflow

- [Sequential agent crew](https://github.com/abhishsing/practo-support-agent/blob/main/agents/crew.py): `agents/crew.py`
- [Offline language model](https://github.com/abhishsing/practo-support-agent/blob/main/llm/mock_llm.py): `llm/mock_llm.py`
- [Response schema](https://github.com/abhishsing/practo-support-agent/blob/main/agents/schemas.py): `agents/schemas.py`

### Policy knowledge

- [Policy lookup tool](https://github.com/abhishsing/practo-support-agent/blob/main/agents/tools.py): `agents/tools.py`
- [Similarity retrieval](https://github.com/abhishsing/practo-support-agent/blob/main/rag/retrieve.py): `rag/retrieve.py`
- [Clinic policy documents](https://github.com/abhishsing/practo-support-agent/tree/main/kb): `kb`
- [Chunk strategies](https://github.com/abhishsing/practo-support-agent/blob/main/rag/chunking.py): `rag/chunking.py`
- [Policy indexer](https://github.com/abhishsing/practo-support-agent/blob/main/rag/index.py): `rag/index.py`
- [Chroma collections](https://github.com/abhishsing/practo-support-agent/blob/main/rag/index.py): `rag/index.py`

### Appointment data

- [Appointment lookup](https://github.com/abhishsing/practo-support-agent/blob/main/agents/tools.py): `agents/tools.py`
- [Appointment records](https://github.com/abhishsing/practo-support-agent/blob/main/dataset.py): `dataset.py`

### Governance and review

- [Request guardrails](https://github.com/abhishsing/practo-support-agent/blob/main/agents/guardrails.py): `agents/guardrails.py`
- [Query budget](https://github.com/abhishsing/practo-support-agent/blob/main/governance/policy.py): `governance/policy.py`
- [Generation cache](https://github.com/abhishsing/practo-support-agent/blob/main/governance/cache.py): `governance/cache.py`
- [Draft review](https://github.com/abhishsing/practo-support-agent/blob/main/review/autogen_review.py): `review/autogen_review.py`

### Other components

- **Clinic user**

## Connections

- Clinic user → HTTP and chat API: submits query (evidence: `README.md`)
- HTTP and chat API → Sequential agent crew: runs query (evidence: `api/main.py`)
- HTTP and chat API → Masked event logging: logs request (evidence: `api/main.py`)
- HTTP and chat API → Query budget: maps budget errors (evidence: `api/main.py`)
- HTTP and chat API → Clinic policy documents: appends documents (evidence: `api/main.py`)
- HTTP and chat API → Policy indexer: indexes additions (evidence: `api/main.py`)
- Masked event logging → Request guardrails: masks phones (evidence: `api/logging_utils.py`)
- Sequential agent crew → Request guardrails: checks requests (evidence: `agents/crew.py`)
- Sequential agent crew → Query budget: checks budget (evidence: `README.md`)
- Sequential agent crew → Generation cache: caches generation (evidence: `agents/crew.py`)
- Sequential agent crew → Offline language model: uses model (evidence: `agents/crew.py`)
- Sequential agent crew → Policy lookup tool: dispatches lookup (evidence: `README.md`)
- Sequential agent crew → Appointment lookup: dispatches lookup (evidence: `README.md`)
- Sequential agent crew → Draft review: reviews grounded drafts (evidence: `agents/crew.py`)
- Sequential agent crew → Response schema: validates response (evidence: `agents/crew.py`)
- Policy lookup tool → Similarity retrieval: retrieves evidence (evidence: `agents/tools.py`)
- Similarity retrieval → Chroma collections: queries collection (evidence: `rag/retrieve.py`)
- Policy indexer → Clinic policy documents: loads documents (evidence: `rag/index.py`)
- Policy indexer → Chunk strategies: creates chunks (evidence: `rag/index.py`)
- Policy indexer → Chroma collections: upserts embeddings (evidence: `rag/index.py`)
- Appointment lookup → Appointment records: looks up records (evidence: `agents/tools.py`)