# bhanikki28/complaint-triage-copilot architecture

> Architecture diagram of the GitHub repository bhanikki28/complaint-triage-copilot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhanikki28/complaint-triage-copilot
- Repository: https://github.com/bhanikki28/complaint-triage-copilot

## Overview

Complaint Triage Copilot accepts analyst complaints and returns a cited, confidence-scored recommendation, or abstains/escalates; high-risk cases pause for team-lead approval. The documented workflow passes through authenticated API handling, input guards, orchestration, classification and agent retrieval/forecast/risk work, then output validation and persistence. The README also documents MCP tool boundaries, A2A delegation, memory, and audit. Some subsystem details are documented but unsampled; their paths and links are included only where README or source-index references support them.

Main entry points: [`src/triage/agents/orchestrator.py`](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/orchestrator.py) (Orchestrator), [`src/triage/api/app.py`](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/api/app.py) (FastAPI routes), [`src/triage/memory/db.py`](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/memory/db.py) (Postgres), [`src/triage/mcp_server/server.py`](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/mcp_server/server.py) (MCP tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["API and access"]
  node_api["FastAPI routes<br/>[app.py]"]
  node_auth["JWT and RBAC<br/>[rbac.py]"]
  node_middleware["Request controls<br/>[middleware.py]"]
end

subgraph group_workflow["Triage workflow"]
  node_orchestrator["Orchestrator<br/>[orchestrator.py]"]
  node_preguards["Input guards<br/>[injection.py]"]
  node_pseudonym["Pseudonymization<br/>[pseudonym.py]"]
  node_classifier["Complaint classifier<br/>[classifier.py]"]
  node_postguards["Output validation<br/>[output.py]"]
  node_redaction["PII redaction<br/>[redact.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_agents["Agents and tools"]
  node_ragagent["Retrieval agent<br/>[rag.py]"]
  node_retriever["Policy retriever<br/>[rag.py]"]
  node_forecast["Volume forecast<br/>[lstm.py]"]
  node_timeseries["Forecast data<br/>[timeseries.py]"]
  node_risk["Risk assessment<br/>[risk.py]"]
  node_a2aclient["A2A client<br/>[a2a_client.py]"]
  node_a2aserver["A2A agent server<br/>[a2a_server.py]"]
  node_mcpclient["MCP client<br/>[client.py]"]
  node_mcpserver["MCP tools<br/>[server.py]"]
  node_llm["LLM provider<br/>[factory.py]"]
end

subgraph group_state["Persistence"]
  node_memory["Memory and repositories<br/>[repositories.py]"]
  node_models["Data models<br/>[models.py]"]
  node_postgres[("Postgres<br/>[db.py]")]
end

node_analyst(("Analyst / lead"))

node_analyst -->|"submits case"| node_api
node_api -->|"handles request"| node_middleware
node_api -->|"checks access"| node_auth
node_api -->|"runs triage"| node_orchestrator
node_orchestrator -->|"screens input"| node_preguards
node_orchestrator -->|"pseudonymizes"| node_pseudonym
node_orchestrator -->|"classifies case"| node_classifier
node_orchestrator -->|"delegates tasks"| node_a2aclient
node_a2aclient -->|"sends task"| node_a2aserver
node_a2aserver -->|"calls tools"| node_mcpclient
node_orchestrator -->|"accesses memory"| node_mcpclient
node_mcpclient -->|"calls tools"| node_mcpserver
node_mcpserver -->|"searches policy"| node_retriever
node_retriever -->|"reads chunks"| node_postgres
node_mcpserver -->|"gets forecast"| node_forecast
node_forecast -->|"uses series"| node_timeseries
node_orchestrator -->|"assesses risk"| node_risk
node_orchestrator -->|"validates result"| node_postguards
node_postguards -->|"redacts output"| node_redaction
node_orchestrator -->|"builds agent"| node_llm
node_api -->|"persists cases"| node_memory
node_memory -->|"queries entities"| node_models
node_api -->|"opens sessions"| node_postgres
node_memory -.->|"stores records"| node_postgres
node_orchestrator -->|"checkpoints runs"| node_postgres
node_orchestrator -->|"reads settings"| node_config

click node_api "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/api/app.py"
click node_auth "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/api/rbac.py"
click node_middleware "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/api/middleware.py"
click node_orchestrator "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/orchestrator.py"
click node_preguards "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/guards/injection.py"
click node_pseudonym "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/guards/pseudonym.py"
click node_classifier "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/classifier.py"
click node_postguards "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/guards/output.py"
click node_redaction "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/guards/redact.py"
click node_ragagent "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/rag.py"
click node_retriever "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/rag.py"
click node_forecast "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/lstm.py"
click node_timeseries "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/timeseries.py"
click node_risk "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/risk.py"
click node_a2aclient "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/a2a_client.py"
click node_a2aserver "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/a2a_server.py"
click node_mcpclient "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/mcp_server/client.py"
click node_mcpserver "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/mcp_server/server.py"
click node_memory "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/memory/repositories.py"
click node_models "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/memory/models.py"
click node_postgres "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/memory/db.py"
click node_llm "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/llm/factory.py"
click node_config "https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/config.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_api,node_auth,node_middleware toneBlue
class node_orchestrator,node_preguards,node_pseudonym,node_classifier,node_postguards,node_redaction,node_config toneAmber
class node_ragagent,node_retriever,node_forecast,node_timeseries,node_risk,node_a2aclient,node_a2aserver,node_mcpclient,node_mcpserver,node_llm toneMint
class node_memory,node_models,node_postgres toneRose
class node_analyst toneIndigo
```

## Components

### API and access

- [FastAPI routes](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/api/app.py): `src/triage/api/app.py`
- [JWT and RBAC](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/api/rbac.py): `src/triage/api/rbac.py`
- [Request controls](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/api/middleware.py): `src/triage/api/middleware.py`

### Triage workflow

- [Orchestrator](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/orchestrator.py): `src/triage/agents/orchestrator.py`
- [Input guards](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/guards/injection.py): `src/triage/guards/injection.py`
- [Pseudonymization](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/guards/pseudonym.py): `src/triage/guards/pseudonym.py`
- [Complaint classifier](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/classifier.py): `src/triage/agents/classifier.py`
- [Output validation](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/guards/output.py): `src/triage/guards/output.py`
- [PII redaction](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/guards/redact.py): `src/triage/guards/redact.py`
- [Runtime settings](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/config.py): `src/triage/config.py`

### Agents and tools

- [Retrieval agent](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/rag.py): `src/triage/agents/rag.py`
- [Policy retriever](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/rag.py): `src/triage/agents/rag.py`
- [Volume forecast](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/lstm.py): `src/triage/agents/lstm.py`
- [Forecast data](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/timeseries.py): `src/triage/timeseries.py`
- [Risk assessment](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/risk.py): `src/triage/agents/risk.py`
- [A2A client](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/a2a_client.py): `src/triage/agents/a2a_client.py`
- [A2A agent server](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/agents/a2a_server.py): `src/triage/agents/a2a_server.py`
- [MCP client](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/mcp_server/client.py): `src/triage/mcp_server/client.py`
- [MCP tools](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/mcp_server/server.py): `src/triage/mcp_server/server.py`
- [LLM provider](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/llm/factory.py): `src/triage/llm/factory.py`

### Persistence

- [Memory and repositories](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/memory/repositories.py): `src/triage/memory/repositories.py`
- [Data models](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/memory/models.py): `src/triage/memory/models.py`
- [Postgres](https://github.com/bhanikki28/complaint-triage-copilot/blob/main/src/triage/memory/db.py): `src/triage/memory/db.py`

### Other components

- **Analyst / lead**

## Connections

- Analyst / lead → FastAPI routes: submits case (evidence: `README.md`)
- FastAPI routes → Request controls: handles request (evidence: `src/triage/api/app.py`)
- FastAPI routes → JWT and RBAC: checks access (evidence: `src/triage/api/app.py`)
- FastAPI routes → Orchestrator: runs triage (evidence: `src/triage/api/app.py`)
- Orchestrator → Input guards: screens input (evidence: `src/triage/agents/orchestrator.py`)
- Orchestrator → Pseudonymization: pseudonymizes (evidence: `src/triage/agents/orchestrator.py`)
- Orchestrator → Complaint classifier: classifies case (evidence: `src/triage/agents/orchestrator.py`)
- Orchestrator → A2A client: delegates tasks (evidence: `src/triage/agents/orchestrator.py`)
- A2A client → A2A agent server: sends task (evidence: `src/triage/agents/a2a_client.py`)
- A2A agent server → MCP client: calls tools (evidence: `src/triage/agents/services.py`)
- Orchestrator → MCP client: accesses memory (evidence: `src/triage/agents/orchestrator.py`)
- MCP client → MCP tools: calls tools (evidence: `src/triage/mcp_server/client.py`)
- MCP tools → Policy retriever: searches policy (evidence: `src/triage/mcp_server/server.py`)
- Policy retriever → Postgres: reads chunks
- MCP tools → Volume forecast: gets forecast (evidence: `src/triage/mcp_server/server.py`)
- Volume forecast → Forecast data: uses series (evidence: `src/triage/training.py`)
- Orchestrator → Risk assessment: assesses risk (evidence: `src/triage/agents/orchestrator.py`)
- Orchestrator → Output validation: validates result (evidence: `src/triage/agents/orchestrator.py`)
- Output validation → PII redaction: redacts output (evidence: `src/triage/guards/output.py`)
- Orchestrator → LLM provider: builds agent (evidence: `src/triage/agents/orchestrator.py`)
- FastAPI routes → Memory and repositories: persists cases (evidence: `src/triage/api/app.py`)
- Memory and repositories → Data models: queries entities (evidence: `src/triage/memory/repositories.py`)
- FastAPI routes → Postgres: opens sessions (evidence: `src/triage/api/app.py`)
- Memory and repositories → Postgres: stores records
- Orchestrator → Postgres: checkpoints runs (evidence: `README.md`)
- Orchestrator → Runtime settings: reads settings (evidence: `src/triage/agents/orchestrator.py`)
