# ys-pundir/cartmind-agentic-ecommerce-support architecture

> Architecture diagram of the GitHub repository ys-pundir/cartmind-agentic-ecommerce-support, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ys-pundir/cartmind-agentic-ecommerce-support
- Repository: https://github.com/ys-pundir/cartmind-agentic-ecommerce-support

## Overview

Cartmind is an e-commerce support agent: a user submits a question through the chat UI or terminal, the agent guards and classifies it, dispatches to policy retrieval, order lookup, feedback, or human deferral, then generates and validates a structured response. The README documents thread-scoped SQLite checkpointing and API/MCP entry points; sampled HTTP code also shows persisted conversation history and document uploads. The graph follows documented routing where implementation excerpts are absent; those links are not inferred beyond the stated flow.

Main entry points: [`src/agent/graph.py`](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/graph.py) (LangGraph flow), [`src/agent/nodes.py`](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/nodes.py) (Generate response), [`src/agent/main.py`](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/main.py) (HTTP API), [`src/agent/agent.py`](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/agent.py) (Agent runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_chat_ui["Chat frontend<br/>[app.js]"]
  node_api["HTTP API<br/>[main.py]"]
  node_terminal["Terminal app"]
  node_mcp_client["MCP client<br/>[client.py]"]
  node_mcp_server["Order MCP server<br/>[server.py]"]
end

subgraph group_agent["Agent workflow"]
  node_agent_run["Agent runner<br/>[agent.py]"]
  node_graph["LangGraph flow<br/>[graph.py]"]
  node_intent["Guard and classify<br/>[nodes.py]"]
  node_response["Generate response<br/>[nodes.py]"]
end

subgraph group_knowledge["Policy knowledge"]
  node_rag_tool["Policy tool<br/>[rag_tool.py]"]
  node_retrieval["Retrieve passages<br/>[retrieval.py]"]
  node_embeddings["Embedding model<br/>[embeddings.py]"]
  node_vector_store[("Policy vectors<br/>[vector_store.py]")]
  node_generation["Grounded generation<br/>[generation.py]"]
end

subgraph group_records["Support actions"]
  node_sql_tool["Order lookup<br/>[sql_tool.py]"]
  node_orders_db[("Orders database<br/>[seed.py]")]
  node_feedback["Feedback tool<br/>[feedback_tool.py]"]
  node_defer["Human deferral<br/>[deffered_tool.py]"]
end

subgraph group_runtime["State and safeguards"]
  node_pii["PII masking<br/>[pii.py]"]
  node_injection["Injection detection<br/>[injection.py]"]
  node_validation["Ticket validation<br/>[validate_ticket.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
  node_checkpoint[("Graph checkpoint<br/>[agent.py]")]
  node_conversation[("Conversation history<br/>[conversation.py]")]
end

node_user(("Customer"))
node_external_llm(("Groq service"))

node_user -->|"sends message"| node_chat_ui
node_chat_ui -->|"HTTP requests"| node_api
node_user -->|"enters query"| node_terminal
node_terminal -->|"runs agent"| node_agent_run
node_mcp_client -->|"calls tool"| node_mcp_server
node_mcp_server -->|"queries"| node_orders_db
node_api -->|"runs or resumes"| node_agent_run
node_api -->|"reads and updates"| node_conversation
node_agent_run -->|"invokes"| node_graph
node_graph -->|"starts at"| node_intent
node_intent -->|"masks text"| node_pii
node_intent -->|"checks text"| node_injection
node_graph -->|"routes policy"| node_rag_tool
node_graph -->|"routes order"| node_sql_tool
node_graph -->|"routes feedback"| node_feedback
node_graph -->|"routes escalation"| node_defer
node_rag_tool -->|"requests answer"| node_generation
node_generation -->|"retrieves context"| node_retrieval
node_retrieval -->|"searches"| node_vector_store
node_retrieval -->|"embeds query"| node_embeddings
node_api -->|"indexes uploads"| node_embeddings
node_sql_tool -->|"queries"| node_orders_db
node_graph -->|"continues to"| node_response
node_rag_tool -->|"returns tool result"| node_response
node_sql_tool -->|"returns tool result"| node_response
node_feedback -->|"returns tool result"| node_response
node_defer -->|"returns tool result"| node_response
node_response -->|"requests generation"| node_llm
node_llm -.->|"calls when enabled"| node_external_llm
node_response -->|"validates ticket"| node_validation
node_agent_run -->|"checkpoints state"| node_checkpoint
node_agent_run -->|"persists turns"| node_conversation
node_api -->|"returns answer"| node_chat_ui

click node_chat_ui "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/frontend/app.js"
click node_api "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/main.py"
click node_terminal "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/terminal_application.py"
click node_mcp_client "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/mcp_server/client.py"
click node_mcp_server "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/mcp_server/server.py"
click node_agent_run "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/agent.py"
click node_graph "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/graph.py"
click node_intent "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/nodes.py"
click node_response "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/nodes.py"
click node_pii "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/guardrails/pii.py"
click node_injection "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/guardrails/injection.py"
click node_rag_tool "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/tools/rag_tool.py"
click node_retrieval "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/rag/retrieval.py"
click node_embeddings "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/rag/embeddings.py"
click node_vector_store "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/rag/vector_store.py"
click node_generation "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/rag/generation.py"
click node_sql_tool "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/tools/sql_tool.py"
click node_orders_db "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/scripts/seed.py"
click node_feedback "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/tools/feedback_tool.py"
click node_defer "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/tools/deffered_tool.py"
click node_validation "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/structured_output/validate_ticket.py"
click node_llm "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/llm_client.py"
click node_checkpoint "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/agent.py"
click node_conversation "https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/memory/conversation.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_chat_ui,node_api,node_terminal,node_mcp_client,node_mcp_server toneBlue
class node_agent_run,node_graph,node_intent,node_response toneAmber
class node_rag_tool,node_retrieval,node_embeddings,node_vector_store,node_generation toneMint
class node_sql_tool,node_orders_db,node_feedback,node_defer toneRose
class node_pii,node_injection,node_validation,node_llm,node_checkpoint,node_conversation,node_user,node_external_llm toneIndigo
```

## Components

### User interfaces

- [Chat frontend](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/frontend/app.js): `frontend/app.js`
- [HTTP API](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/main.py): `src/agent/main.py`
- [Terminal app](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/terminal_application.py): `src/agent/terminal_application.py`
- [MCP client](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/mcp_server/client.py): `mcp_server/client.py`
- [Order MCP server](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/mcp_server/server.py): `mcp_server/server.py`

### Agent workflow

- [Agent runner](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/agent.py): `src/agent/agent.py`
- [LangGraph flow](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/graph.py): `src/agent/graph.py`
- [Guard and classify](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/nodes.py): `src/agent/nodes.py`
- [Generate response](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/nodes.py): `src/agent/nodes.py`

### Policy knowledge

- [Policy tool](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/tools/rag_tool.py): `src/tools/rag_tool.py`
- [Retrieve passages](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/rag/retrieval.py): `src/rag/retrieval.py`
- [Embedding model](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/rag/embeddings.py): `src/rag/embeddings.py`
- [Policy vectors](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/rag/vector_store.py): `src/rag/vector_store.py`
- [Grounded generation](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/rag/generation.py): `src/rag/generation.py`

### Support actions

- [Order lookup](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/tools/sql_tool.py): `src/tools/sql_tool.py`
- [Orders database](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/scripts/seed.py): `scripts/seed.py`
- [Feedback tool](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/tools/feedback_tool.py): `src/tools/feedback_tool.py`
- [Human deferral](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/tools/deffered_tool.py): `src/tools/deffered_tool.py`

### State and safeguards

- [PII masking](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/guardrails/pii.py): `src/guardrails/pii.py`
- [Injection detection](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/guardrails/injection.py): `src/guardrails/injection.py`
- [Ticket validation](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/structured_output/validate_ticket.py): `src/structured_output/validate_ticket.py`
- [LLM client](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/llm_client.py): `src/llm_client.py`
- [Graph checkpoint](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/agent/agent.py): `src/agent/agent.py`
- [Conversation history](https://github.com/ys-pundir/cartmind-agentic-ecommerce-support/blob/main/src/memory/conversation.py): `src/memory/conversation.py`

### Other components

- **Customer**
- **Groq service**

## Connections

- Customer → Chat frontend: sends message
- Chat frontend → HTTP API: HTTP requests
- Customer → Terminal app: enters query
- Terminal app → Agent runner: runs agent
- MCP client → Order MCP server: calls tool
- Order MCP server → Orders database: queries
- HTTP API → Agent runner: runs or resumes
- HTTP API → Conversation history: reads and updates
- Agent runner → LangGraph flow: invokes
- LangGraph flow → Guard and classify: starts at
- Guard and classify → PII masking: masks text
- Guard and classify → Injection detection: checks text
- LangGraph flow → Policy tool: routes policy
- LangGraph flow → Order lookup: routes order
- LangGraph flow → Feedback tool: routes feedback
- LangGraph flow → Human deferral: routes escalation
- Policy tool → Grounded generation: requests answer
- Grounded generation → Retrieve passages: retrieves context
- Retrieve passages → Policy vectors: searches
- Retrieve passages → Embedding model: embeds query
- HTTP API → Embedding model: indexes uploads
- Order lookup → Orders database: queries
- LangGraph flow → Generate response: continues to
- Policy tool → Generate response: returns tool result
- Order lookup → Generate response: returns tool result
- Feedback tool → Generate response: returns tool result
- Human deferral → Generate response: returns tool result
- Generate response → LLM client: requests generation
- LLM client → Groq service: calls when enabled
- Generate response → Ticket validation: validates ticket
- Agent runner → Graph checkpoint: checkpoints state
- Agent runner → Conversation history: persists turns
- HTTP API → Chat frontend: returns answer