# shrutijagadale0725-rgb/escalai architecture

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

- Interactive diagram: https://gitdiagram.com/shrutijagadale0725-rgb/escalai
- Repository: https://github.com/shrutijagadale0725-rgb/escalai

## Overview

EscalAI takes a consumer complaint from intake through drafted correspondence, reply-window tracking, and—if needed—a filing decision and case file. Users interact through the web simulator or MCP tools; neither sends messages on the user's behalf. The service persists each case in SQLite and runs a resumable LangGraph workflow. The README documents the four escalation stages and simulator capabilities. Source excerpts show the main call paths; stage details are represented from the README, and the optional Groq integrations are shown separately.

Main entry points: [`escalation_agent/graph.py`](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/graph.py) (Resumable workflow), [`escalation_agent/service.py`](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/service.py) (Case service), [`escalation_agent/mcp_server.py`](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/mcp_server.py) (MCP and HTTP tools), [`web/simulator.html`](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/web/simulator.html) (Web simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_simulator["Web simulator<br/>[simulator.html]"]
  node_mcp["MCP and HTTP tools<br/>[mcp_server.py]"]
end

subgraph group_understanding["Intent and routing"]
  node_nlu["Intent extraction<br/>[nlu.py]"]
  node_groq_nlu["Groq NLU"]
end

subgraph group_casework["Case workflow"]
  node_service["Case service<br/>[service.py]"]
  node_workflow["Resumable workflow<br/>[graph.py]"]
  node_case_db[("SQLite checkpoints<br/>[service.py]")]
end

subgraph group_content["Drafting and policy"]
  node_seller["Seller support<br/>[rules.yaml]"]
  node_grievance["Grievance officer<br/>[rules.yaml]"]
  node_helpline["Consumer helpline<br/>[rules.yaml]"]
  node_commission["Consumer Commission<br/>[rules.yaml]"]
  node_drafting["Letters and case file<br/>[drafting.py]"]
  node_groq_polish["Groq polishing<br/>[drafting.py]"]
end

node_user(("Consumer"))

node_user -->|"uses"| node_simulator
node_simulator -->|"calls tools"| node_mcp
node_simulator -->|"posts text"| node_mcp
node_mcp -->|"routes text"| node_nlu
node_nlu -.->|"tries extraction"| node_groq_nlu
node_mcp -->|"invokes cases"| node_service
node_service -->|"builds and invokes"| node_workflow
node_service -->|"persists checkpoints"| node_case_db
node_service -->|"creates polisher"| node_drafting
node_workflow -->|"drafts letters"| node_drafting
node_workflow -->|"follows stage rules"| node_seller
node_workflow -->|"follows stage rules"| node_grievance
node_workflow -->|"follows stage rules"| node_helpline
node_workflow -->|"gates filing"| node_commission
node_drafting -.->|"optionally polishes"| node_groq_polish

click node_simulator "https://github.com/shrutijagadale0725-rgb/escalai/blob/main/web/simulator.html"
click node_mcp "https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/mcp_server.py"
click node_nlu "https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/nlu.py"
click node_service "https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/service.py"
click node_workflow "https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/graph.py"
click node_case_db "https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/service.py"
click node_seller "https://github.com/shrutijagadale0725-rgb/escalai/blob/main/rules.yaml"
click node_grievance "https://github.com/shrutijagadale0725-rgb/escalai/blob/main/rules.yaml"
click node_helpline "https://github.com/shrutijagadale0725-rgb/escalai/blob/main/rules.yaml"
click node_commission "https://github.com/shrutijagadale0725-rgb/escalai/blob/main/rules.yaml"
click node_drafting "https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/drafting.py"
click node_groq_polish "https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/drafting.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_simulator,node_mcp toneBlue
class node_nlu,node_groq_nlu toneAmber
class node_service,node_workflow,node_case_db toneMint
class node_seller,node_grievance,node_helpline,node_commission,node_drafting,node_groq_polish toneRose
class node_user toneIndigo
```

## Components

### User interaction

- [Web simulator](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/web/simulator.html): `web/simulator.html`
- [MCP and HTTP tools](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/mcp_server.py): `escalation_agent/mcp_server.py`

### Intent and routing

- [Intent extraction](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/nlu.py): `escalation_agent/nlu.py`
- **Groq NLU**

### Case workflow

- [Case service](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/service.py): `escalation_agent/service.py`
- [Resumable workflow](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/graph.py): `escalation_agent/graph.py`
- [SQLite checkpoints](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/service.py): `escalation_agent/service.py`

### Drafting and policy

- [Seller support](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/rules.yaml): `rules.yaml`
- [Grievance officer](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/rules.yaml): `rules.yaml`
- [Consumer helpline](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/rules.yaml): `rules.yaml`
- [Consumer Commission](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/rules.yaml): `rules.yaml`
- [Letters and case file](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/drafting.py): `escalation_agent/drafting.py`
- [Groq polishing](https://github.com/shrutijagadale0725-rgb/escalai/blob/main/escalation_agent/drafting.py): `escalation_agent/drafting.py`

### Other components

- **Consumer**

## Connections

- Consumer → Web simulator: uses (evidence: `README.md`)
- Web simulator → MCP and HTTP tools: calls tools (evidence: `README.md`)
- Web simulator → MCP and HTTP tools: posts text (evidence: `escalation_agent/mcp_server.py`)
- MCP and HTTP tools → Intent extraction: routes text (evidence: `escalation_agent/mcp_server.py`)
- Intent extraction → Groq NLU: tries extraction (evidence: `escalation_agent/nlu.py`)
- MCP and HTTP tools → Case service: invokes cases (evidence: `escalation_agent/mcp_server.py`)
- Case service → Resumable workflow: builds and invokes (evidence: `escalation_agent/service.py`)
- Case service → SQLite checkpoints: persists checkpoints (evidence: `escalation_agent/service.py`)
- Case service → Letters and case file: creates polisher (evidence: `escalation_agent/service.py`)
- Resumable workflow → Letters and case file: drafts letters (evidence: `escalation_agent/graph.py`)
- Resumable workflow → Seller support: follows stage rules (evidence: `README.md`)
- Resumable workflow → Grievance officer: follows stage rules (evidence: `README.md`)
- Resumable workflow → Consumer helpline: follows stage rules (evidence: `README.md`)
- Resumable workflow → Consumer Commission: gates filing (evidence: `README.md`)
- Letters and case file → Groq polishing: optionally polishes (evidence: `escalation_agent/drafting.py`)
