Architecture Overview

This section explains the high‑level flow from a user message to the final AI response with optional visualization data.

Sequence Summary

1. UI (ChatWindow component) captures user text and sends a request to the Chat API (POST /chat/send_message) including the active chat mode.
2. Chat API forwards the request into the Chat Orchestrator / MCP Tool layer.
3. Middleware validates the user token.
4. MCP Tool (Model Context Protocol) mediates tool usage and formats a prompt for the AI LLM.
5. LLM generates a response which may include structured directives (e.g., request to fetch balances).
6. Orchestrator invokes Data Manager service APIs to satisfy data retrieval / transformation.
7. Retrieved data is post‑processed (e.g., shaping visualization_data, trimming large payloads).
8. Response payload (text + optional visualization metadata) returns to the UI.
9. UI filters out internal tool_use / tool_result messages, keeping only user‑visible text.
10. UI sanitizes, renders markdown + chart, and updates conversation state.

API Endpoints

Method	Endpoint	Purpose
GET	/chat/conversations	List all conversations
GET	/chat/conversations/:id	Load a conversation with history
POST	/chat/conversations/:id	Update conversation (e.g., title)
DELETE	/chat/conversations/:id	Delete a conversation
POST	/chat/send_message	Send a message and get response

Payload Shape (Simplified)

{
  "id": "msg-uuid",
  "role": "assistant",
  "content": "Here is the balance distribution...",
  "visualization_type": "pie",
  "visualization_data": [
    { "account_name": "Operating", "available_balance": "12345.67" }
  ]
}

Visualization Generation

• The backend decides when to attach visualization_* fields (UI is passive)
• Unsupported chart types are ignored gracefully by the UI (text still renders)

Security & Safety Considerations

Concern	Mitigation
XSS in AI text	Strict markdown simplification + DOMPurify allow‑list
Oversized Data	Backend truncates / summarizes before sending
Sensitive API Access	MCP tool enforces scoped tool definitions
User Privacy	Conversations stored server‑side per tenant/user (no cross‑user sharing)

Extensibility Points

Layer	Future Opportunities
UI	Additional chart renderers, rich markdown, inline actions
API	Streaming responses, feedback analytics
MCP	More tools (search, schema retrieval, lineage)
LLM	Additional mode specializations, system prompts per mode

Continue to the Disclaimer or return to the Introduction.