# System Design: AI Agent Phân Tích Doanh Thu BizFly Cloud
## 1. System Context (C4 Model - Level 1)
Tổng quan hệ thống trong bối cảnh tổ chức.
```mermaid
graph TB
subgraph External["👥 External Users"]
Sales[Sales Team]
Manager[Manager]
Analyst[Business Analyst]
end
subgraph System["🤖 AI Analytics System"]
Agent[AI Agent<br/>MCP Server]
end
subgraph External_Systems["📡 External Systems"]
Telegram[Telegram API]
Claude[Claude Desktop]
Cursor[Cursor IDE]
end
subgraph Data["🗄️ Data Sources"]
AnaDB[(postgres-ana)]
end
Sales -->|"Ask questions via"| Telegram
Manager -->|"Deep analysis via"| Claude
Analyst -->|"Query via"| Cursor
Telegram -->|"MCP Protocol"| Agent
Claude -->|"MCP Protocol"| Agent
Cursor -->|"MCP Protocol"| Agent
Agent -->|"Query reports"| AnaDB
Agent -->|"Send alerts"| Telegram
style Agent fill:#4A90E2,color:#fff
style AnaDB fill:#50C878,color:#fff
```
---
## 2. Container Diagram (C4 Model - Level 2)
Các containers chính trong hệ thống và cách chúng kết nối.
```mermaid
graph TB
subgraph Users["👥 Users"]
U1[Sales via Telegram]
U2[Manager via Claude]
end
subgraph Interface["🎨 Interface Layer"]
TBot[Telegram Bot<br/>Node.js]
ClaudeApp[Claude Desktop<br/>MCP Client]
end
subgraph Orchestration["⚙️ Orchestration Layer (Optional)"]
Airflow[Airflow DAG<br/>Existing System]
N8N[N8N Workflow<br/>Optional]
end
subgraph Agent["🤖 AI Agent Layer"]
MCP[MCP Server<br/>TypeScript/Python<br/>Port 3000]
end
subgraph Data["💾 Data Layer"]
AnaDB[(postgres-ana<br/>Analytics DB)]
end
U1 -->|"HTTP Webhook"| TBot
U2 -->|"stdio/HTTP"| ClaudeApp
TBot -.->|"REST API (optional)"| N8N
ClaudeApp -->|"MCP Protocol"| MCP
N8N -.->|"MCP Protocol"| MCP
Airflow -.->|"Scheduled jobs"| MCP
TBot -->|"Direct MCP"| MCP
MCP -->|"Query reports"| AnaDB
MCP -.->|"Send notification (optional)"| N8N
N8N -.->|"Telegram API"| TBot
MCP -->|"Direct notification"| TBot
style MCP fill:#4A90E2,color:#fff
style AnaDB fill:#50C878,color:#fff
style Airflow fill:#17BECF,color:#fff
style N8N fill:#FF6B6B,color:#fff,stroke-dasharray: 5 5
```
---
## 3. MCP Server Component Diagram (C4 Model - Level 3)
Chi tiết bên trong MCP Server.
```mermaid
graph TB
subgraph MCP["🤖 MCP Server (AI Agent)"]
API[API Layer<br/>HTTP/stdio server]
subgraph Tools["🛠️ Tools (Executable Functions)"]
T1[query_revenue]
T2[analyze_trend]
T3[get_customer_details]
T4[send_alert]
T5[export_report]
end
subgraph Resources["📚 Resources (Static Context)"]
R1[Revenue Schema]
R2[Service Mapping]
R3[Business Rules]
R4[SQL Templates]
end
subgraph Prompts["💬 Prompts (Pre-configured)"]
P1[analyze_revenue_trend]
P2[detect_churn_risk]
P3[generate_executive_report]
end
subgraph Core["⚙️ Core Logic"]
QueryBuilder[SQL Query Builder<br/>OLD REPORT LOGIC]
Analyzer[Trend Analyzer<br/>Calculate changes]
Formatter[Response Formatter<br/>Natural language]
end
DBClient[Database Client<br/>Connection Pool]
end
API --> Tools
API --> Resources
API --> Prompts
T1 --> QueryBuilder
T2 --> Analyzer
T3 --> QueryBuilder
T5 --> Formatter
QueryBuilder --> DBClient
Analyzer --> QueryBuilder
Resources -.->|"Provide context"| QueryBuilder
Resources -.->|"Provide rules"| Analyzer
DBClient -->|"Execute SQL"| DB[(Databases)]
style MCP fill:#E8F4F8
style Tools fill:#FFE5B4
style Resources fill:#D4F1D4
style Prompts fill:#FFD4E5
style Core fill:#E5E5FF
```
---
## 4. Sequence Diagram: Revenue Query Flow
Luồng xử lý từ khi user hỏi câu hỏi đến khi nhận kết quả.
```mermaid
sequenceDiagram
actor User as 👤 Sales (Telegram)
participant Bot as 🤖 Telegram Bot
participant MCP as 🧠 MCP Server
participant DB as 🗄️ postgres-ana
User->>Bot: "Có bao nhiêu KH active tháng 12?"
Bot->>MCP: MCP Protocol<br/>Call tool: query_revenue<br/>{cycle: "01-01-2026", filter: "public"}
MCP->>MCP: Validate params
MCP->>MCP: Build SQL query<br/>(Query report tables)
MCP->>DB: Execute SQL query
DB-->>MCP: Result set
MCP->>MCP: Aggregate & filter<br/>Format response
MCP-->>Bot: {total: 1303, test: 172, ...}
Bot-->>User: 📊 Kết quả:<br/>- Public: 1,303 KH<br/>- Test: 172 KH
```
---
## 5. Sequence Diagram: Trend Analysis & Alert Flow
Luồng phân tích xu hướng và gửi cảnh báo với human-in-the-loop.
```mermaid
sequenceDiagram
actor Scheduler as ⏰ Airflow/Scheduler
participant MCP as 🧠 MCP Server
participant DB as 🗄️ postgres-ana
participant Bot as 🤖 Telegram Bot
participant Manager as 👤 Manager
participant Sales as 👥 Sales Team
Scheduler->>MCP: Daily job (9 AM)<br/>analyze_trend({current: "01-01-2026"})
MCP->>MCP: Query current cycle
MCP->>DB: SELECT ... WHERE cycle='01-01-2026'
DB-->>MCP: Current revenue data
MCP->>MCP: Query previous 3 cycles
MCP->>DB: SELECT ... WHERE cycle IN (...)
DB-->>MCP: Historical data
MCP->>MCP: Calculate per customer:<br/>change% = (current - avg) / avg
MCP->>MCP: Filter anomalies:<br/>|change%| > 20%
alt No Anomalies
MCP-->>Scheduler: Status: OK<br/>No alerts needed
else Anomalies Detected
MCP->>MCP: Generate alert message
Note over MCP: Found:<br/>- 5 customers: +30% ↑<br/>- 3 customers: -35% ↓ (churn risk)
MCP->>Bot: Tool: send_alert<br/>{message: "...", approval_required: true}
Bot->>Manager: 🔔 Telegram notification:<br/>"Phát hiện 8 KH bất thường.<br/>Gửi alert đến Sales?"<br/>[Yes] [No]
Manager->>Bot: Click [Yes]
Bot->>MCP: Approval granted
MCP->>Bot: Prepare notification
Bot->>Sales: 📢 Telegram to sales group:<br/>"⚠️ ALERT: Churn Risk<br/>- customer1@: -35%<br/>- customer2@: -30%<br/>Action: Contact ASAP"
Bot->>MCP: Log alert sent
MCP->>DB: INSERT INTO alert_logs
end
```
---
## 6. Deployment Architecture
Kiến trúc triển khai với Docker Compose.
```mermaid
graph TB
subgraph Internet["🌐 Internet"]
TelegramAPI[Telegram API]
Users[Users]
end
subgraph DockerHost["🐳 Docker Host"]
subgraph Network["Docker Network: bizfly-analytics"]
TBot[telegram-bot<br/>Port: 8080]
MCP[mcp-server<br/>Port: 3000]
N8N[n8n optional<br/>Port: 5678]
end
subgraph Volumes["📦 Volumes"]
V1[mcp-config]
V2[n8n-data]
end
end
subgraph External["External Databases"]
AnaDB[(postgres-ana<br/>External host)]
end
Users -->|HTTPS| TelegramAPI
TelegramAPI -->|Webhook| TBot
TBot -->|MCP Protocol| MCP
N8N -.->|Optional| MCP
MCP -->|SQL Query| AnaDB
MCP -.->|Mount| V1
N8N -.->|Mount| V2
style MCP fill:#4A90E2,color:#fff
style AnaDB fill:#50C878,color:#fff
style N8N fill:#FF6B6B,color:#fff
```
---
## 7. Component Interaction: Query Execution
Chi tiết các thành phần tương tác khi thực thi một query.
```mermaid
flowchart LR
subgraph Client["🖥️ Client"]
User[User Query]
end
subgraph MCPServer["🧠 MCP Server"]
direction TB
API[API Handler]
subgraph ToolLayer["Tool Layer"]
ToolRegistry[Tool Registry]
QueryTool[query_revenue Tool]
end
subgraph CoreLayer["Core Layer"]
SQLBuilder[SQL Builder]
QueryExecutor[Query Executor]
ResultFormatter[Result Formatter]
end
subgraph ResourceLayer["Resource Layer"]
SchemaResource[Schema Resource]
TemplateResource[Template Resource]
end
end
subgraph DataLayer["💾 Data Layer"]
DBPool[Connection Pool]
DB[(postgres-ana)]
end
User --> API
API --> ToolRegistry
ToolRegistry --> QueryTool
QueryTool --> SQLBuilder
SQLBuilder -.->|Load context| SchemaResource
SQLBuilder -.->|Load template| TemplateResource
SQLBuilder --> QueryExecutor
QueryExecutor --> DBPool
DBPool --> DB
DB --> DBPool
DBPool --> QueryExecutor
QueryExecutor --> ResultFormatter
ResultFormatter --> API
API --> User
style MCPServer fill:#E8F4F8
style ToolLayer fill:#FFE5B4
style CoreLayer fill:#E5E5FF
style ResourceLayer fill:#D4F1D4
```
---
## 8. State Machine: Alert Processing
State machine cho quá trình xử lý alert.
```mermaid
stateDiagram-v2
[*] --> Monitoring: Scheduled job starts
Monitoring --> Analyzing: Query data
Analyzing --> NoAnomaly: Change < 20%
Analyzing --> AnomalyDetected: Change ≥ 20%
NoAnomaly --> [*]: End
AnomalyDetected --> PendingApproval: Generate alert message
PendingApproval --> Approved: Manager clicks [Yes]
PendingApproval --> Rejected: Manager clicks [No]
Approved --> Sending: Send Telegram notification
Sending --> Sent: Success
Sending --> Failed: Error
Sent --> Logged: Log to database
Failed --> Retry: Retry (max 3 times)
Retry --> Sending
Retry --> [*]: Max retries reached
Rejected --> Logged
Logged --> [*]
note right of AnomalyDetected
Detected changes:
- Revenue +/- 20%
- Churn risk
- Service spike
end note
note right of PendingApproval
Human-in-the-loop
Wait for approval
Timeout: 24 hours
end note
```
---
## 9. Network Flow: Request/Response Layers
Luồng request/response qua các tầng mạng.
```mermaid
graph LR
subgraph Layer1["L1: Presentation"]
UI1[Telegram Bot UI]
UI2[Claude Desktop]
end
subgraph Layer2["L2: Application"]
App1[Telegram Bot Server]
App2[MCP Client]
end
subgraph Layer3["L3: Business Logic"]
BL1[N8N Workflow]
BL2[MCP Server]
end
subgraph Layer4["L4: Data Access"]
DA1[Query Builder]
DA2[Connection Pool]
end
subgraph Layer5["L5: Data Storage"]
DB[(postgres-ana)]
end
UI1 <-->|HTTP| App1
UI2 <-->|MCP/stdio| App2
App1 <-->|MCP| BL2
App2 <-->|MCP/HTTP| BL2
BL1 -.->|Optional| BL2
BL2 <-->|SQL| DA1
DA1 <-->|Connection| DA2
DA2 <-->|Query| DB
style Layer1 fill:#FFE5B4
style Layer2 fill:#FFD4E5
style Layer3 fill:#D4F1D4
style Layer4 fill:#E5E5FF
style Layer5 fill:#FFE4E1
```
---
