# aarthireddyyy/rto-guardian architecture

> Architecture diagram of the GitHub repository aarthireddyyy/rto-guardian, 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/aarthireddyyy/rto-guardian
- Repository: https://github.com/aarthireddyyy/rto-guardian

## Overview

RTO Guardian is a pre-shipment COD risk-intervention system: an order is scored, routed to automatic approval or customer contact, then resolved or rescored into a final decision. The principal workflow is documented in the README and visible in the API and orchestrator excerpts. Chat and voice are separate interaction paths; voice additionally uses speech services and Groq parsing. The README also describes the ML training and explainability capabilities. Some subsystem paths and integrations are documented but their implementation was not sampled; those relationships cite the README or are omitted where evidence is insufficient.

Main entry points: [`backend/app/main.py`](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/main.py) (FastAPI), [`backend/app/agents/orchestrator.py`](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/orchestrator.py) (Risk Router), [`backend/app/agents/whatsapp.py`](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/whatsapp.py) (Chat Conversation), [`backend/app/agents/rescore.py`](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/rescore.py) (Outcome Rescoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Customer Demo"]
  node_demo_ui["Demo UI<br/>[app.js]"]
end

subgraph group_api["API Workflow"]
  node_api["FastAPI<br/>[main.py]"]
  node_order_schema["Order Contracts<br/>[schemas.py]"]
  node_order_state[("Order State Store<br/>[main.py]")]
  node_orchestrator["Risk Router<br/>[orchestrator.py]"]
end

subgraph group_risk["Risk Engine"]
  node_auto_approve["Auto Approval<br/>[auto_approve.py]"]
  node_ml_scorer["ML Risk Scoring<br/>[main.py]"]
  node_ml_model["Trained Model<br/>[rto_risk_model.pkl]"]
  node_ml_training["Model Training<br/>[train.py]"]
  node_data_generator["Synthetic Data<br/>[data_generator.py]"]
  node_rescore["Outcome Rescoring<br/>[rescore.py]"]
end

subgraph group_intervention["Customer Intervention"]
  node_whatsapp_agent["Chat Conversation<br/>[whatsapp.py]"]
  node_message_generator["Chat Messages"]
  node_chat_ws["Chat WebSocket<br/>[chat_handler.py]"]
  node_voice_ws["Voice WebSocket"]
  node_voice_agent["Voice Conversation<br/>[voice_agent.py]"]
  node_voice_prompt["Voice Workflow Prompt<br/>[voice.py]"]
  node_groq_parser["Intent And Landmark Parsing<br/>[groq_parser.py]"]
end

subgraph group_integrations["External AI Services"]
  node_sarvam["Speech Services<br/>[sarvam_service.py]"]
  node_groq["Groq LLM"]
  node_sarvam_service["Sarvam AI"]
end

node_customer(("Customer"))

node_customer -->|"uses"| node_demo_ui
node_demo_ui -->|"submits order"| node_api
node_api -->|"validates"| node_order_schema
node_api -->|"runs workflow"| node_orchestrator
node_api -->|"stores state"| node_order_state
node_api -->|"rescoring reply"| node_rescore
node_api -->|"registers route"| node_chat_ws
node_api -->|"registers route"| node_voice_ws
node_orchestrator -->|"requests score"| node_ml_scorer
node_ml_scorer -->|"scores with"| node_ml_model
node_orchestrator -->|"routes low risk"| node_auto_approve
node_orchestrator -->|"routes medium risk"| node_whatsapp_agent
node_orchestrator -->|"routes high risk"| node_voice_prompt
node_orchestrator -->|"routes after contact"| node_rescore
node_whatsapp_agent -->|"returns outcomes"| node_rescore
node_voice_prompt -->|"returns outcomes"| node_rescore
node_chat_ws -->|"handles conversation"| node_whatsapp_agent
node_chat_ws -->|"generates messages"| node_message_generator
node_whatsapp_agent -->|"generates nudge"| node_message_generator
node_voice_ws -->|"handles conversation"| node_voice_agent
node_voice_agent -->|"uses speech services"| node_sarvam
node_voice_agent -->|"parses replies"| node_groq_parser
node_groq_parser -->|"classifies and extracts"| node_groq
node_sarvam -->|"calls speech API"| node_sarvam_service
node_ml_training -.->|"produces model"| node_ml_model
node_data_generator -.->|"supplies training data"| node_ml_training

click node_demo_ui "https://github.com/aarthireddyyy/rto-guardian/blob/main/app.js"
click node_api "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/main.py"
click node_order_schema "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/models/schemas.py"
click node_order_state "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/main.py"
click node_orchestrator "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/orchestrator.py"
click node_auto_approve "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/auto_approve.py"
click node_ml_scorer "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/main.py"
click node_ml_model "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/ml/models/rto_risk_model.pkl"
click node_ml_training "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/ml/train.py"
click node_data_generator "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/ml/data_generator.py"
click node_rescore "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/rescore.py"
click node_whatsapp_agent "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/whatsapp.py"
click node_message_generator "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/message_generator.py"
click node_chat_ws "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/websockets/chat_handler.py"
click node_voice_ws "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/websockets/voice_ws_handler.py"
click node_voice_agent "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/voice_agent.py"
click node_voice_prompt "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/voice.py"
click node_groq_parser "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/groq_parser.py"
click node_sarvam "https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/services/sarvam_service.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_demo_ui toneBlue
class node_api,node_order_schema,node_order_state,node_orchestrator toneAmber
class node_auto_approve,node_ml_scorer,node_ml_model,node_ml_training,node_data_generator,node_rescore toneMint
class node_whatsapp_agent,node_message_generator,node_chat_ws,node_voice_ws,node_voice_agent,node_voice_prompt,node_groq_parser toneRose
class node_sarvam,node_groq,node_sarvam_service,node_customer toneIndigo
```

## Components

### Customer Demo

- [Demo UI](https://github.com/aarthireddyyy/rto-guardian/blob/main/app.js): `app.js`

### API Workflow

- [FastAPI](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/main.py): `backend/app/main.py`
- [Order Contracts](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/models/schemas.py): `backend/app/models/schemas.py`
- [Order State Store](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/main.py): `backend/app/main.py`
- [Risk Router](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/orchestrator.py): `backend/app/agents/orchestrator.py`

### Risk Engine

- [Auto Approval](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/auto_approve.py): `backend/app/agents/auto_approve.py`
- [ML Risk Scoring](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/main.py): `backend/app/main.py`
- [Trained Model](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/ml/models/rto_risk_model.pkl): `backend/ml/models/rto_risk_model.pkl`
- [Model Training](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/ml/train.py): `backend/ml/train.py`
- [Synthetic Data](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/ml/data_generator.py): `backend/ml/data_generator.py`
- [Outcome Rescoring](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/rescore.py): `backend/app/agents/rescore.py`

### Customer Intervention

- [Chat Conversation](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/whatsapp.py): `backend/app/agents/whatsapp.py`
- [Chat Messages](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/message_generator.py): `backend/app/agents/message_generator.py`
- [Chat WebSocket](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/websockets/chat_handler.py): `backend/app/websockets/chat_handler.py`
- [Voice WebSocket](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/websockets/voice_ws_handler.py): `backend/app/websockets/voice_ws_handler.py`
- [Voice Conversation](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/voice_agent.py): `backend/app/agents/voice_agent.py`
- [Voice Workflow Prompt](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/voice.py): `backend/app/agents/voice.py`
- [Intent And Landmark Parsing](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/agents/groq_parser.py): `backend/app/agents/groq_parser.py`

### External AI Services

- [Speech Services](https://github.com/aarthireddyyy/rto-guardian/blob/main/backend/app/services/sarvam_service.py): `backend/app/services/sarvam_service.py`
- **Groq LLM**
- **Sarvam AI**

### Other components

- **Customer**

## Connections

- Customer → Demo UI: uses (evidence: `README.md`)
- Demo UI → FastAPI: submits order (evidence: `README.md`)
- FastAPI → Order Contracts: validates (evidence: `backend/app/main.py`)
- FastAPI → Risk Router: runs workflow (evidence: `backend/app/main.py`)
- FastAPI → Order State Store: stores state (evidence: `backend/app/main.py`)
- FastAPI → Outcome Rescoring: rescoring reply (evidence: `backend/app/main.py`)
- FastAPI → Chat WebSocket: registers route (evidence: `backend/app/main.py`)
- FastAPI → Voice WebSocket: registers route (evidence: `backend/app/main.py`)
- Risk Router → ML Risk Scoring: requests score (evidence: `backend/app/agents/orchestrator.py`)
- ML Risk Scoring → Trained Model: scores with (evidence: `README.md`)
- Risk Router → Auto Approval: routes low risk (evidence: `backend/app/agents/orchestrator.py`)
- Risk Router → Chat Conversation: routes medium risk (evidence: `backend/app/agents/orchestrator.py`)
- Risk Router → Voice Workflow Prompt: routes high risk (evidence: `backend/app/agents/orchestrator.py`)
- Risk Router → Outcome Rescoring: routes after contact (evidence: `backend/app/agents/orchestrator.py`)
- Chat Conversation → Outcome Rescoring: returns outcomes (evidence: `backend/app/agents/orchestrator.py`)
- Voice Workflow Prompt → Outcome Rescoring: returns outcomes (evidence: `backend/app/agents/orchestrator.py`)
- Chat WebSocket → Chat Conversation: handles conversation (evidence: `backend/app/websockets/chat_handler.py`)
- Chat WebSocket → Chat Messages: generates messages (evidence: `backend/app/websockets/chat_handler.py`)
- Chat Conversation → Chat Messages: generates nudge (evidence: `backend/app/agents/whatsapp.py`)
- Voice WebSocket → Voice Conversation: handles conversation (evidence: `backend/app/websockets/voice_ws_handler.py`)
- Voice Conversation → Speech Services: uses speech services (evidence: `backend/app/agents/voice_agent.py`)
- Voice Conversation → Intent And Landmark Parsing: parses replies (evidence: `backend/app/agents/voice_agent.py`)
- Intent And Landmark Parsing → Groq LLM: classifies and extracts (evidence: `backend/app/agents/groq_parser.py`)
- Speech Services → Sarvam AI: calls speech API (evidence: `backend/app/services/sarvam_service.py`)
- Model Training → Trained Model: produces model (evidence: `README.md`)
- Synthetic Data → Model Training: supplies training data (evidence: `README.md`)
