# mudavathkalyan/customer-action-agent architecture

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

- Interactive diagram: https://gitdiagram.com/mudavathkalyan/customer-action-agent
- Repository: https://github.com/mudavathkalyan/customer-action-agent

## Overview

Customer Action Agent accepts customer support messages, extracts structured ticket data, validates and classifies the requested action, then executes it or pauses for manager approval. The graph owns the workflow and keeps resumable state in an in-memory checkpointer. The sampled source establishes the API, agent nodes, routing, and LLM client; the gateway node is supported by the configured base URL and the LiteLLM config path, but its runtime implementation was not sampled.

Main entry points: [`app/agent/graph.py`](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/graph.py) (Workflow graph), [`app/api/tickets.py`](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/api/tickets.py) (Ticket endpoints), [`app/agent/nodes/extraction.py`](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/nodes/extraction.py) (Ticket extraction), [`app/agent/nodes/approval.py`](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/nodes/approval.py) (Manager approval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_app["FastAPI app<br/>[main.py]"]
  node_ticket_api["Ticket endpoints<br/>[tickets.py]"]
end

subgraph group_workflow["Agent workflow"]
  node_graph["Workflow graph<br/>[graph.py]"]
  node_extract["Ticket extraction<br/>[extraction.py]"]
  node_validate["Ticket validation<br/>[validation.py]"]
  node_validation_router["Validation routing<br/>[routing.py]"]
  node_risk["Risk assessment<br/>[risk.py]"]
  node_action_router["Action routing<br/>[action_router.py]"]
  node_approval["Manager approval<br/>[approval.py]"]
  node_execution["Action execution<br/>[execution.py]"]
  node_state["Agent state<br/>[state.py]"]
end

subgraph group_domain["Ticket domain"]
  node_ticket_model["Ticket schema<br/>[ticket.py]"]
end

subgraph group_integrations["LLM and state"]
  node_llm_client["Structured LLM client<br/>[llm.py]"]
  node_gateway["LiteLLM gateway<br/>[config.yaml]"]
  node_checkpoint[("Memory checkpoint<br/>[graph.py]")]
end

node_customer(("Customer"))
node_manager(("Manager"))

node_customer -->|"submits message"| node_ticket_api
node_app -->|"mounts routes"| node_ticket_api
node_ticket_api -->|"invokes or resumes"| node_graph
node_graph -->|"returns state"| node_ticket_api
node_ticket_api -->|"reads snapshot"| node_checkpoint
node_graph -->|"saves workflow state"| node_checkpoint
node_graph -->|"dispatches"| node_extract
node_graph -->|"dispatches"| node_validate
node_graph -->|"checks route"| node_validation_router
node_graph -->|"dispatches"| node_risk
node_graph -->|"checks route"| node_action_router
node_graph -->|"dispatches"| node_approval
node_graph -->|"dispatches"| node_execution
node_extract -->|"requests extraction"| node_llm_client
node_llm_client -.->|"sends completion request"| node_gateway
node_llm_client -->|"structures output"| node_ticket_model
node_extract -->|"returns ticket data"| node_graph
node_validate -->|"provides errors"| node_validation_router
node_validation_router -->|"selects retry, risk, or stop"| node_graph
node_risk -->|"provides risk flag"| node_action_router
node_action_router -->|"selects approval or execution"| node_graph
node_graph -->|"retries on validation error"| node_extract
node_graph -->|"continues when valid"| node_risk
node_graph -->|"routes high-risk action"| node_approval
node_graph -->|"routes ordinary action"| node_execution
node_approval -->|"interrupts for decision"| node_manager
node_manager -->|"approves or rejects"| node_ticket_api
node_execution -->|"returns action result"| node_graph
node_approval -->|"returns decision result"| node_graph
node_ticket_api -->|"returns status and state"| node_customer

click node_app "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/main.py"
click node_ticket_api "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/api/tickets.py"
click node_graph "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/graph.py"
click node_extract "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/nodes/extraction.py"
click node_validate "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/nodes/validation.py"
click node_validation_router "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/routing.py"
click node_risk "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/nodes/risk.py"
click node_action_router "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/action_router.py"
click node_approval "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/nodes/approval.py"
click node_execution "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/nodes/execution.py"
click node_state "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/state.py"
click node_ticket_model "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/models/ticket.py"
click node_llm_client "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/services/llm.py"
click node_gateway "https://github.com/mudavathkalyan/customer-action-agent/blob/main/litellm/config.yaml"
click node_checkpoint "https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/graph.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_app,node_ticket_api toneBlue
class node_graph,node_extract,node_validate,node_validation_router,node_risk,node_action_router,node_approval,node_execution,node_state toneAmber
class node_ticket_model toneMint
class node_llm_client,node_gateway,node_checkpoint toneRose
class node_customer,node_manager toneIndigo
```

## Components

### API

- [FastAPI app](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/main.py): `app/main.py`
- [Ticket endpoints](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/api/tickets.py): `app/api/tickets.py`

### Agent workflow

- [Workflow graph](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/graph.py): `app/agent/graph.py`
- [Ticket extraction](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/nodes/extraction.py): `app/agent/nodes/extraction.py`
- [Ticket validation](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/nodes/validation.py): `app/agent/nodes/validation.py`
- [Validation routing](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/routing.py): `app/agent/routing.py`
- [Risk assessment](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/nodes/risk.py): `app/agent/nodes/risk.py`
- [Action routing](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/action_router.py): `app/agent/action_router.py`
- [Manager approval](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/nodes/approval.py): `app/agent/nodes/approval.py`
- [Action execution](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/nodes/execution.py): `app/agent/nodes/execution.py`
- [Agent state](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/state.py): `app/agent/state.py`

### Ticket domain

- [Ticket schema](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/models/ticket.py): `app/models/ticket.py`

### LLM and state

- [Structured LLM client](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/services/llm.py): `app/services/llm.py`
- [LiteLLM gateway](https://github.com/mudavathkalyan/customer-action-agent/blob/main/litellm/config.yaml): `litellm/config.yaml`
- [Memory checkpoint](https://github.com/mudavathkalyan/customer-action-agent/blob/main/app/agent/graph.py): `app/agent/graph.py`

### Other components

- **Customer**
- **Manager**

## Connections

- Customer → Ticket endpoints: submits message
- FastAPI app → Ticket endpoints: mounts routes
- Ticket endpoints → Workflow graph: invokes or resumes
- Workflow graph → Ticket endpoints: returns state
- Ticket endpoints → Memory checkpoint: reads snapshot
- Workflow graph → Memory checkpoint: saves workflow state
- Workflow graph → Ticket extraction: dispatches
- Workflow graph → Ticket validation: dispatches
- Workflow graph → Validation routing: checks route
- Workflow graph → Risk assessment: dispatches
- Workflow graph → Action routing: checks route
- Workflow graph → Manager approval: dispatches
- Workflow graph → Action execution: dispatches
- Ticket extraction → Structured LLM client: requests extraction
- Structured LLM client → LiteLLM gateway: sends completion request
- Structured LLM client → Ticket schema: structures output
- Ticket extraction → Workflow graph: returns ticket data
- Ticket validation → Validation routing: provides errors
- Validation routing → Workflow graph: selects retry, risk, or stop
- Risk assessment → Action routing: provides risk flag
- Action routing → Workflow graph: selects approval or execution
- Workflow graph → Ticket extraction: retries on validation error
- Workflow graph → Risk assessment: continues when valid
- Workflow graph → Manager approval: routes high-risk action
- Workflow graph → Action execution: routes ordinary action
- Manager approval → Manager: interrupts for decision
- Manager → Ticket endpoints: approves or rejects
- Action execution → Workflow graph: returns action result
- Manager approval → Workflow graph: returns decision result
- Ticket endpoints → Customer: returns status and state