# sam-abishekraj/sutraops architecture

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

- Interactive diagram: https://gitdiagram.com/sam-abishekraj/sutraops
- Repository: https://github.com/sam-abishekraj/sutraops

## Overview

SutraOps is an enterprise support-operations agent that turns a user’s chat request into grounded answers or guarded actions in mock client systems. The main workflow enters through the Flask API, runs the tool-calling agent, and uses policy retrieval, SQL, or CRM/notification tools; risky actions wait for human approval. The web UI also exposes approvals and operational traces, and an MCP server offers the shared tools to external clients. Edges reflect README architecture statements and source-index references; unsampled implementation details are not inferred.

Main entry points: [`sutraops/web/app.py`](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/web/app.py) (Flask API), [`sutraops/tools.py`](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/tools.py) (Tool registry), [`sutraops/agent.py`](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/agent.py) (Agent loop), [`sutraops/db.py`](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/db.py) (Business database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User interfaces"]
  node_chat_ui["Chat console<br/>[chat.js]"]
  node_admin_ui["Admin console<br/>[admin.js]"]
  node_web_api["Flask API<br/>[app.py]"]
end

subgraph group_orchestration["Agent orchestration"]
  node_agent["Agent loop<br/>[agent.py]"]
  node_llm["Groq client<br/>[llm.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_tool_registry["Tool registry<br/>[tools.py]"]
end

subgraph group_safety["Safety and approvals"]
  node_guardrails["Guardrails<br/>[guardrails.py]"]
  node_approvals["Approval workflow<br/>[approvals.py]"]
end

subgraph group_integrations["Client systems"]
  node_systems_client["Systems HTTP client<br/>[client.py]"]
  node_crm_api["CRM and outbox API<br/>[crm_api.py]"]
  node_sql_tool["Guarded SQL<br/>[sqltool.py]"]
  node_knowledge["SOP retrieval<br/>[rag.py]"]
  node_policy_docs["SOP documents"]
end

subgraph group_operations["Operational data"]
  node_company_db[("Business database<br/>[db.py]")]
  node_ops_db[("Operations database<br/>[db.py]")]
  node_seed_data["Demo seed data<br/>[seed_data.py]"]
  node_tracing["Run tracing<br/>[tracing.py]"]
end

node_user(("Support user"))
node_approver(("Team lead"))
node_groq_service["Groq API"]
node_mcp_client(("MCP client"))

node_user -->|"asks"| node_chat_ui
node_chat_ui -->|"submits chat"| node_web_api
node_web_api -->|"runs request"| node_agent
node_web_api -->|"serves trace views"| node_tracing
node_admin_ui -->|"requests admin data"| node_web_api
node_agent -->|"requests completion"| node_llm
node_llm -->|"calls model API"| node_groq_service
node_agent -->|"executes tools"| node_tool_registry
node_agent -->|"checks and sanitizes"| node_guardrails
node_tool_registry -->|"calls CRM tools"| node_systems_client
node_tool_registry -->|"runs SQL tool"| node_sql_tool
node_tool_registry -->|"searches policies"| node_knowledge
node_knowledge -->|"indexes and searches"| node_policy_docs
node_sql_tool -->|"queries read-only"| node_company_db
node_systems_client -->|"sends HTTP requests"| node_crm_api
node_crm_api -->|"reads and writes"| node_company_db
node_tool_registry -->|"queues risky actions"| node_approvals
node_approver -->|"reviews requests"| node_admin_ui
node_admin_ui -->|"submits decision"| node_web_api
node_web_api -->|"routes decisions"| node_approvals
node_approvals -->|"executes approved action"| node_systems_client
node_agent -->|"records run steps"| node_tracing
node_tracing -->|"persists traces"| node_ops_db
node_web_api -->|"initializes storage"| node_company_db
node_company_db -->|"loads demo records"| node_seed_data
node_mcp_client -->|"connects over MCP"| node_mcp
node_mcp -->|"exposes shared tools"| node_tool_registry

click node_chat_ui "https://github.com/sam-abishekraj/sutraops/blob/main/static/js/chat.js"
click node_admin_ui "https://github.com/sam-abishekraj/sutraops/blob/main/static/js/admin.js"
click node_web_api "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/web/app.py"
click node_agent "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/agent.py"
click node_llm "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/llm.py"
click node_mcp "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/mcp_server.py"
click node_tool_registry "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/tools.py"
click node_guardrails "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/guardrails.py"
click node_approvals "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/approvals.py"
click node_systems_client "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/systems/client.py"
click node_crm_api "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/systems/crm_api.py"
click node_sql_tool "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/sqltool.py"
click node_knowledge "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/knowledge/rag.py"
click node_policy_docs "https://github.com/sam-abishekraj/sutraops/tree/main/sutraops/knowledge/docs"
click node_company_db "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/db.py"
click node_ops_db "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/db.py"
click node_seed_data "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/seed_data.py"
click node_tracing "https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/tracing.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_admin_ui,node_web_api,node_user,node_mcp_client toneBlue
class node_agent,node_llm,node_mcp,node_tool_registry toneAmber
class node_guardrails,node_approvals,node_groq_service toneMint
class node_systems_client,node_crm_api,node_sql_tool,node_knowledge,node_policy_docs toneRose
class node_company_db,node_ops_db,node_seed_data,node_tracing,node_approver toneIndigo
```

## Components

### User interfaces

- [Chat console](https://github.com/sam-abishekraj/sutraops/blob/main/static/js/chat.js): `static/js/chat.js`
- [Admin console](https://github.com/sam-abishekraj/sutraops/blob/main/static/js/admin.js): `static/js/admin.js`
- [Flask API](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/web/app.py): `sutraops/web/app.py`

### Agent orchestration

- [Agent loop](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/agent.py): `sutraops/agent.py`
- [Groq client](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/llm.py): `sutraops/llm.py`
- [MCP server](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/mcp_server.py): `sutraops/mcp_server.py`
- [Tool registry](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/tools.py): `sutraops/tools.py`

### Safety and approvals

- [Guardrails](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/guardrails.py): `sutraops/guardrails.py`
- [Approval workflow](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/approvals.py): `sutraops/approvals.py`

### Client systems

- [Systems HTTP client](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/systems/client.py): `sutraops/systems/client.py`
- [CRM and outbox API](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/systems/crm_api.py): `sutraops/systems/crm_api.py`
- [Guarded SQL](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/sqltool.py): `sutraops/sqltool.py`
- [SOP retrieval](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/knowledge/rag.py): `sutraops/knowledge/rag.py`
- [SOP documents](https://github.com/sam-abishekraj/sutraops/tree/main/sutraops/knowledge/docs): `sutraops/knowledge/docs`

### Operational data

- [Business database](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/db.py): `sutraops/db.py`
- [Operations database](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/db.py): `sutraops/db.py`
- [Demo seed data](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/seed_data.py): `sutraops/seed_data.py`
- [Run tracing](https://github.com/sam-abishekraj/sutraops/blob/main/sutraops/tracing.py): `sutraops/tracing.py`

### Other components

- **Support user**
- **Team lead**
- **Groq API**
- **MCP client**

## Connections

- Support user → Chat console: asks (evidence: `README.md`)
- Chat console → Flask API: submits chat (evidence: `README.md`)
- Flask API → Agent loop: runs request (evidence: `sutraops/web/app.py`)
- Flask API → Run tracing: serves trace views (evidence: `sutraops/web/app.py`)
- Admin console → Flask API: requests admin data (evidence: `README.md`)
- Agent loop → Groq client: requests completion (evidence: `sutraops/agent.py`)
- Groq client → Groq API: calls model API (evidence: `README.md`)
- Agent loop → Tool registry: executes tools (evidence: `sutraops/agent.py`)
- Agent loop → Guardrails: checks and sanitizes (evidence: `sutraops/agent.py`)
- Tool registry → Systems HTTP client: calls CRM tools (evidence: `sutraops/tools.py`)
- Tool registry → Guarded SQL: runs SQL tool (evidence: `sutraops/tools.py`)
- Tool registry → SOP retrieval: searches policies (evidence: `sutraops/tools.py`)
- SOP retrieval → SOP documents: indexes and searches (evidence: `README.md`)
- Guarded SQL → Business database: queries read-only (evidence: `README.md`)
- Systems HTTP client → CRM and outbox API: sends HTTP requests (evidence: `sutraops/systems/client.py`)
- CRM and outbox API → Business database: reads and writes (evidence: `sutraops/systems/crm_api.py`)
- Tool registry → Approval workflow: queues risky actions (evidence: `sutraops/tools.py`)
- Team lead → Admin console: reviews requests (evidence: `README.md`)
- Admin console → Flask API: submits decision (evidence: `README.md`)
- Flask API → Approval workflow: routes decisions (evidence: `sutraops/web/app.py`)
- Approval workflow → Systems HTTP client: executes approved action (evidence: `sutraops/approvals.py`)
- Agent loop → Run tracing: records run steps (evidence: `sutraops/agent.py`)
- Run tracing → Operations database: persists traces (evidence: `sutraops/tracing.py`)
- Flask API → Business database: initializes storage (evidence: `sutraops/web/app.py`)
- Business database → Demo seed data: loads demo records (evidence: `sutraops/db.py`)
- MCP client → MCP server: connects over MCP (evidence: `README.md`)
- MCP server → Tool registry: exposes shared tools (evidence: `sutraops/mcp_server.py`)
