# wtfmadrid/tcs-project architecture

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

- Interactive diagram: https://gitdiagram.com/wtfmadrid/tcs-project
- Repository: https://github.com/wtfmadrid/tcs-project

## Overview

SupportDesk AI is a read-only support investigation assistant: an executive asks a question in the chat UI, the backend runs a LangGraph workflow, and specialist tools retrieve customer records or policy passages for an evidence-backed response. The product also supports policy PDF upload, indexing, and document listing, plus reproducible synthetic customer data. The README and excerpts support the main runtime links; several workflow details and storage internals are documented but not fully excerpted.

Main entry points: [`ui.py`](https://github.com/wtfmadrid/tcs-project/blob/main/ui.py) (Chat and uploads), [`mcp_server.py`](https://github.com/wtfmadrid/tcs-project/blob/main/mcp_server.py) (MCP tool server), [`workflow.py`](https://github.com/wtfmadrid/tcs-project/blob/main/workflow.py) (Question router), [`policy_store.py`](https://github.com/wtfmadrid/tcs-project/blob/main/policy_store.py) (PDF indexing and search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Chat experience"]
  node_streamlit_ui["Chat and uploads<br/>[ui.py]"]
  node_backend["Async backend<br/>[app_backend.py]"]
end

subgraph group_orchestration["Query orchestration"]
  node_router["Question router<br/>[workflow.py]"]
  node_customer_specialist["Customer specialist<br/>[workflow.py]"]
  node_policy_specialist["Policy specialist<br/>[workflow.py]"]
  node_answer_finish["Answer synthesis<br/>[workflow.py]"]
  node_mcp_server["MCP tool server<br/>[mcp_server.py]"]
end

subgraph group_customer_data["Customer records"]
  node_customer_tools["Customer retrieval tools<br/>[mcp_server.py]"]
  node_sqlite_queries["SQLite retrieval<br/>[database.py]"]
  node_customer_db[("Customer database")]
  node_synthetic_data["Synthetic data generator<br/>[seed_db.py]"]
end

subgraph group_policy_data["Policy knowledge"]
  node_policy_tools["Policy tools<br/>[mcp_server.py]"]
  node_policy_store["PDF indexing and search<br/>[policy_store.py]"]
  node_policy_vectors[("Policy vector store")]
  node_policy_pdf["Policy PDFs"]
end

subgraph group_model_services["AI services"]
  node_llm{{"OpenAI model"}}
  node_local_embeddings["Local embeddings<br/>[policy_store.py]"]
end

node_executive(("Support executive"))

node_executive -->|"asks question"| node_streamlit_ui
node_streamlit_ui -->|"sends request"| node_backend
node_backend -->|"opens MCP session"| node_mcp_server
node_backend -->|"runs workflow"| node_router
node_router -->|"routes customer"| node_customer_specialist
node_router -->|"routes policy"| node_policy_specialist
node_customer_specialist -->|"uses customer tools"| node_mcp_server
node_policy_specialist -->|"uses policy tools"| node_mcp_server
node_customer_specialist -->|"returns evidence"| node_answer_finish
node_policy_specialist -->|"returns evidence"| node_answer_finish
node_answer_finish -->|"synthesizes answer"| node_llm
node_router -->|"classifies question"| node_llm
node_customer_specialist -->|"generates response"| node_llm
node_policy_specialist -->|"generates response"| node_llm
node_answer_finish -->|"returns result"| node_streamlit_ui
node_mcp_server -->|"registers tools"| node_customer_tools
node_customer_tools -->|"calls retrieval"| node_sqlite_queries
node_sqlite_queries -->|"reads records"| node_customer_db
node_synthetic_data -->|"seeds records"| node_customer_db
node_mcp_server -->|"registers tools"| node_policy_tools
node_policy_tools -->|"calls search and ingest"| node_policy_store
node_policy_store -->|"stores and searches"| node_policy_vectors
node_streamlit_ui -->|"requests indexing"| node_backend
node_policy_store -->|"embeds text"| node_local_embeddings
node_streamlit_ui -->|"saves uploaded PDF"| node_policy_pdf
node_policy_store -->|"extracts pages"| node_policy_pdf

click node_streamlit_ui "https://github.com/wtfmadrid/tcs-project/blob/main/ui.py"
click node_backend "https://github.com/wtfmadrid/tcs-project/blob/main/app_backend.py"
click node_router "https://github.com/wtfmadrid/tcs-project/blob/main/workflow.py"
click node_customer_specialist "https://github.com/wtfmadrid/tcs-project/blob/main/workflow.py"
click node_policy_specialist "https://github.com/wtfmadrid/tcs-project/blob/main/workflow.py"
click node_answer_finish "https://github.com/wtfmadrid/tcs-project/blob/main/workflow.py"
click node_mcp_server "https://github.com/wtfmadrid/tcs-project/blob/main/mcp_server.py"
click node_customer_tools "https://github.com/wtfmadrid/tcs-project/blob/main/mcp_server.py"
click node_sqlite_queries "https://github.com/wtfmadrid/tcs-project/blob/main/database.py"
click node_synthetic_data "https://github.com/wtfmadrid/tcs-project/blob/main/seed_db.py"
click node_policy_tools "https://github.com/wtfmadrid/tcs-project/blob/main/mcp_server.py"
click node_policy_store "https://github.com/wtfmadrid/tcs-project/blob/main/policy_store.py"
click node_policy_pdf "https://github.com/wtfmadrid/tcs-project/tree/main/policies"
click node_local_embeddings "https://github.com/wtfmadrid/tcs-project/blob/main/policy_store.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_streamlit_ui,node_backend toneBlue
class node_router,node_customer_specialist,node_policy_specialist,node_answer_finish,node_mcp_server toneAmber
class node_customer_tools,node_sqlite_queries,node_customer_db,node_synthetic_data toneMint
class node_policy_tools,node_policy_store,node_policy_vectors,node_policy_pdf toneRose
class node_llm,node_local_embeddings,node_executive toneIndigo
```

## Components

### Chat experience

- [Chat and uploads](https://github.com/wtfmadrid/tcs-project/blob/main/ui.py): `ui.py`
- [Async backend](https://github.com/wtfmadrid/tcs-project/blob/main/app_backend.py): `app_backend.py`

### Query orchestration

- [Question router](https://github.com/wtfmadrid/tcs-project/blob/main/workflow.py): `workflow.py`
- [Customer specialist](https://github.com/wtfmadrid/tcs-project/blob/main/workflow.py): `workflow.py`
- [Policy specialist](https://github.com/wtfmadrid/tcs-project/blob/main/workflow.py): `workflow.py`
- [Answer synthesis](https://github.com/wtfmadrid/tcs-project/blob/main/workflow.py): `workflow.py`
- [MCP tool server](https://github.com/wtfmadrid/tcs-project/blob/main/mcp_server.py): `mcp_server.py`

### Customer records

- [Customer retrieval tools](https://github.com/wtfmadrid/tcs-project/blob/main/mcp_server.py): `mcp_server.py`
- [SQLite retrieval](https://github.com/wtfmadrid/tcs-project/blob/main/database.py): `database.py`
- **Customer database**
- [Synthetic data generator](https://github.com/wtfmadrid/tcs-project/blob/main/seed_db.py): `seed_db.py`

### Policy knowledge

- [Policy tools](https://github.com/wtfmadrid/tcs-project/blob/main/mcp_server.py): `mcp_server.py`
- [PDF indexing and search](https://github.com/wtfmadrid/tcs-project/blob/main/policy_store.py): `policy_store.py`
- **Policy vector store**
- [Policy PDFs](https://github.com/wtfmadrid/tcs-project/tree/main/policies): `policies`

### AI services

- **OpenAI model**
- [Local embeddings](https://github.com/wtfmadrid/tcs-project/blob/main/policy_store.py): `policy_store.py`

### Other components

- **Support executive**

## Connections

- Support executive → Chat and uploads: asks question (evidence: `README.md`)
- Chat and uploads → Async backend: sends request (evidence: `README.md`)
- Async backend → MCP tool server: opens MCP session (evidence: `app_backend.py`)
- Async backend → Question router: runs workflow (evidence: `app_backend.py`)
- Question router → Customer specialist: routes customer (evidence: `README.md`)
- Question router → Policy specialist: routes policy (evidence: `README.md`)
- Customer specialist → MCP tool server: uses customer tools (evidence: `README.md`)
- Policy specialist → MCP tool server: uses policy tools (evidence: `README.md`)
- Customer specialist → Answer synthesis: returns evidence (evidence: `README.md`)
- Policy specialist → Answer synthesis: returns evidence (evidence: `README.md`)
- Answer synthesis → OpenAI model: synthesizes answer (evidence: `workflow.py`)
- Question router → OpenAI model: classifies question (evidence: `workflow.py`)
- Customer specialist → OpenAI model: generates response
- Policy specialist → OpenAI model: generates response
- Answer synthesis → Chat and uploads: returns result (evidence: `README.md`)
- MCP tool server → Customer retrieval tools: registers tools (evidence: `mcp_server.py`)
- Customer retrieval tools → SQLite retrieval: calls retrieval (evidence: `mcp_server.py`)
- SQLite retrieval → Customer database: reads records (evidence: `database.py`)
- Synthetic data generator → Customer database: seeds records (evidence: `README.md`)
- MCP tool server → Policy tools: registers tools (evidence: `mcp_server.py`)
- Policy tools → PDF indexing and search: calls search and ingest (evidence: `mcp_server.py`)
- PDF indexing and search → Policy vector store: stores and searches (evidence: `policy_store.py`)
- Chat and uploads → Async backend: requests indexing (evidence: `ui.py`)
- PDF indexing and search → Local embeddings: embeds text (evidence: `policy_store.py`)
- Chat and uploads → Policy PDFs: saves uploaded PDF (evidence: `ui.py`)
- PDF indexing and search → Policy PDFs: extracts pages (evidence: `policy_store.py`)
