1. Architecture Philosophy
Một enterprise AI chatbot platform không phải là "gọi API OpenAI rồi trả response". Nó là một distributed system phức tạp với nhiều thành phần cần phối hợp real-time. Ba nguyên tắc kiến trúc:
- Modularity — Mỗi capability là một bounded context độc lập, có thể thay thế/upgrade riêng
- Event-Driven — Các service giao tiếp qua events, giảm coupling, hỗ trợ audit trail
- AI-First — Architecture optimize cho AI workloads: streaming, long-running inference, GPU-aware scaling
2. Bounded Contexts — DDD cho AI Chatbot
Áp dụng Domain-Driven Design để chia platform thành 8 bounded contexts:
┌───────────────────────────────────────────────────────────────────┐
│ AI CHATBOT PLATFORM │
├───────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ CONVERSATION │ │ KNOWLEDGE │ │ AGENT │ │
│ │ CONTEXT │ │ CONTEXT │ │ CONTEXT │ │
│ │ │ │ │ │ │ │
│ │ • Session │ │ • Documents │ │ • Tools │ │
│ │ • Messages │ │ • Embeddings │ │ • Functions │ │
│ │ • Memory │ │ • Search │ │ • Workflows │ │
│ │ • Context │ │ • Sync │ │ • Planning │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ┌──────┴───────┐ ┌──────┴───────┐ ┌──────┴───────┐ │
│ │ CHANNEL │ │ AI ENGINE │ │ GUARDRAIL │ │
│ │ CONTEXT │ │ CONTEXT │ │ CONTEXT │ │
│ │ │ │ │ │ │ │
│ │ • Web Widget │ │ • LLM Router │ │ • Input Gate │ │
│ │ • Slack Bot │ │ • Streaming │ │ • Output Gate│ │
│ │ • WhatsApp │ │ • Prompt Eng │ │ • PII Mask │ │
│ │ • Mobile SDK │ │ • Model Mgmt │ │ • Toxicity │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ┌──────┴───────┐ ┌──────┴───────┐ │
│ │ ANALYTICS │ │ BILLING │ │
│ │ CONTEXT │ │ CONTEXT │ │
│ │ │ │ │ │
│ │ • Metrics │ │ • Usage │ │
│ │ • Tracing │ │ • Plans │ │
│ │ • Feedback │ │ • Invoicing │ │
│ │ • Evals │ │ • Quotas │ │
│ └──────────────┘ └──────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────┘
3. Context Map — Service Interactions
// Domain Events flowing between bounded contexts
type DomainEvent =
| { type: 'conversation.started'; payload: { sessionId: string; channelType: string; tenantId: string } }
| { type: 'message.received'; payload: { sessionId: string; content: string; role: 'user' | 'assistant' } }
| { type: 'knowledge.searched'; payload: { query: string; results: number; latencyMs: number } }
| { type: 'tool.invoked'; payload: { toolName: string; params: Record<string, unknown>; success: boolean } }
| { type: 'agent.planned'; payload: { plan: string[]; model: string } }
| { type: 'guardrail.triggered'; payload: { type: string; severity: 'low' | 'medium' | 'high' | 'critical' } }
| { type: 'response.generated'; payload: { sessionId: string; tokensUsed: number; latencyMs: number } }
| { type: 'human.escalated'; payload: { sessionId: string; reason: string } }
| { type: 'feedback.submitted'; payload: { messageId: string; rating: 'positive' | 'negative'; comment?: string } };
4. High-Level Architecture — C4 Level 1 (System Context)
┌─────────────┐
│ End User │
└──────┬──────┘
│
┌────────────┼────────────┐
│ │ │
┌─────▼────┐ ┌────▼─────┐ ┌───▼──────┐
│ Web Chat │ │ Slack │ │ WhatsApp │
│ Widget │ │ Bot │ │ Bot │
└─────┬────┘ └────┬─────┘ └───┬──────┘
│ │ │
└────────────┼────────────┘
│
┌───────▼───────┐
│ API Gateway │
│ (Kong/Nginx) │
└───────┬───────┘
│
┌────────────┼────────────┐
│ │
┌────────▼─────────┐ ┌─────────▼──────────┐
│ Chatbot Platform │ │ Admin Dashboard │
│ (Core API) │ │ (Management UI) │
└────────┬─────────┘ └─────────┬──────────┘
│ │
┌─────────┼──────────┐ │
│ │ │ │
┌───▼──┐ ┌───▼──┐ ┌────▼───┐ ┌─────▼─────┐
│OpenAI│ │Claude│ │ Self- │ │PostgreSQL │
│ API │ │ API │ │ Hosted │ │ Qdrant │
│ │ │ │ │ (vLLM) │ │ Redis │
└──────┘ └──────┘ └────────┘ └───────────┘
5. C4 Level 2 — Container Diagram
┌─────────────────────────────────────────────────────────────────────┐
│ CHATBOT PLATFORM │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌────────────────┐ │
│ │ Channel Gateway │───▶│ Conversation Svc │───▶│ AI Engine Svc │ │
│ │ (NestJS) │ │ (NestJS) │ │ (Python/FastAPI│ │
│ │ │ │ │ │ + TypeScript) │ │
│ │ • WebSocket │ │ • Session mgmt │ │ • LLM Router │ │
│ │ • REST API │ │ • Context build │ │ • RAG Pipeline│ │
│ │ • Webhook recv │ │ • Memory mgmt │ │ • Prompt Eng │ │
│ └─────────────────┘ └──────────────────┘ │ • Streaming │ │
│ └────────────────┘ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌────────────────┐ │
│ │ Agent Service │ │ Knowledge Service│ │ Guardrail Svc │ │
│ │ (Python) │ │ (Python) │ │ (Python) │ │
│ │ │ │ │ │ │ │
│ │ • Tool Registry │ │ • Doc Ingestion │ │ • Input check │ │
│ │ • Executor │ │ • Embedding │ │ • Output check│ │
│ │ • Planner │ │ • Search │ │ • PII masking │ │
│ └─────────────────┘ └──────────────────┘ └────────────────┘ │
│ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌────────────────┐ │
│ │ Analytics Svc │ │ Billing Service │ │ Admin API │ │
│ │ (Python) │ │ (NestJS) │ │ (NestJS) │ │
│ │ │ │ │ │ │ │
│ │ • Tracing │ │ • Usage meter │ │ • Tenant mgmt │ │
│ │ • Metrics │ │ • Subscription │ │ • Config │ │
│ │ • Evals │ │ • Invoicing │ │ • Prompt mgmt │ │
│ └─────────────────┘ └──────────────────┘ └────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
6. Event-Driven Architecture
Tại sao event-driven cho AI chatbot?
- Audit Trail — Mọi conversation event được log, crucial cho compliance
- Async Processing — Knowledge ingestion, analytics, billing chạy async
- Decoupling — AI Engine không cần biết về Billing; chỉ emit token usage events
- Replay — Replay events để debug conversation flow, retrain models
// Event Bus implementation với Kafka
import { Kafka, Producer, Consumer } from 'kafkajs';
interface EventBus {
publish(topic: string, event: DomainEvent): Promise<void>;
subscribe(topic: string, handler: (event: DomainEvent) => Promise<void>): Promise<void>;
}
class KafkaEventBus implements EventBus {
private producer: Producer;
private consumers: Map<string, Consumer> = new Map();
constructor(private kafka: Kafka) {
this.producer = kafka.producer();
}
async publish(topic: string, event: DomainEvent): Promise<void> {
await this.producer.send({
topic,
messages: [{
key: event.payload.sessionId ?? crypto.randomUUID(),
value: JSON.stringify({
...event,
timestamp: new Date().toISOString(),
eventId: crypto.randomUUID(),
}),
headers: {
'event-type': event.type,
'tenant-id': event.payload.tenantId ?? 'system',
},
}],
});
}
async subscribe(
topic: string,
handler: (event: DomainEvent) => Promise<void>,
): Promise<void> {
const consumer = this.kafka.consumer({ groupId: `${topic}-consumer` });
await consumer.connect();
await consumer.subscribe({ topic, fromBeginning: false });
await consumer.run({
eachMessage: async ({ message }) => {
const event = JSON.parse(message.value!.toString()) as DomainEvent;
await handler(event);
},
});
this.consumers.set(topic, consumer);
}
}
7. Request Flow — Từ User Message đến Response
User Message
│
▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Channel │────▶│ Input │────▶│Conversa- │
│ Gateway │ │ Guardrail│ │tion Svc │
└──────────┘ └──────────┘ └────┬─────┘
│
┌──────────────────┤
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ Memory │ │ Knowledge│
│ Retrieve │ │ Search │
└────┬─────┘ └────┬─────┘
│ │
└────────┬─────────┘
│
▼
┌──────────┐
│ Prompt │
│ Assembly │
└────┬─────┘
│
▼
┌──────────┐
│ AI Engine│──── Tool Calls? ───▶ Agent Svc
│ (LLM) │◀──── Results ──────┘
└────┬─────┘
│
▼
┌──────────┐ ┌──────────┐
│ Output │────▶│ Channel │──▶ User
│ Guardrail│ │ Delivery │
└──────────┘ └──────────┘
│
▼
┌──────────────┐
│ Event Bus │
│ (Analytics, │
│ Billing, │
│ Logging) │
└──────────────┘
8. Core Data Model
// Core domain entities
interface Tenant {
id: string;
name: string;
plan: 'free' | 'pro' | 'enterprise';
config: TenantConfig;
createdAt: Date;
}
interface TenantConfig {
defaultModel: string; // e.g., 'gpt-4o'
fallbackModels: string[]; // e.g., ['claude-3-sonnet', 'gpt-4o-mini']
maxTokensPerRequest: number; // e.g., 4096
maxConversationsPerDay: number; // e.g., 10000
enabledChannels: ChannelType[]; // e.g., ['web', 'slack']
guardrailConfig: GuardrailConfig;
ragConfig: RAGConfig;
}
interface Conversation {
id: string;
tenantId: string;
channelType: ChannelType;
channelUserId: string;
status: 'active' | 'closed' | 'escalated';
metadata: Record<string, unknown>;
startedAt: Date;
lastMessageAt: Date;
}
interface Message {
id: string;
conversationId: string;
role: 'user' | 'assistant' | 'system' | 'tool';
content: string;
toolCalls?: ToolCall[];
metadata: {
model?: string;
tokensUsed?: { input: number; output: number };
latencyMs?: number;
sources?: Citation[];
};
createdAt: Date;
}
interface Citation {
documentId: string;
chunkId: string;
content: string;
score: number;
metadata: Record<string, unknown>;
}
type ChannelType = 'web' | 'slack' | 'teams' | 'whatsapp' | 'discord' | 'email' | 'api';
9. Deployment Topology
┌─────────────────────────── Kubernetes Cluster ──────────────────────┐
│ │
│ ┌─── Namespace: chatbot-platform ──────────────────────────────┐ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │Channel │ │Conversa- │ │AI Engine │ │Agent Svc │ │ │
│ │ │Gateway │ │tion Svc │ │(2 replicas│ │ │ │ │
│ │ │(3 rep.) │ │(2 rep.) │ │+ GPU pod)│ │(2 rep.) │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │Knowledge │ │Guardrail │ │Analytics │ │Billing │ │ │
│ │ │ Svc │ │ Svc │ │ Svc │ │ Svc │ │ │
│ │ │(2 rep.) │ │(2 rep.) │ │(1 rep.) │ │(1 rep.) │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─── Namespace: data ──────────────────────────────────────────┐ │
│ │ PostgreSQL (HA) │ Qdrant │ Redis Cluster │ Kafka │ MinIO │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─── Namespace: monitoring ────────────────────────────────────┐ │
│ │ Langfuse │ Prometheus │ Grafana │ AlertManager │ Loki │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘
10. API Design Principles
// REST API structure
// POST /api/v1/conversations — Start conversation
// POST /api/v1/conversations/:id/messages — Send message (returns stream)
// GET /api/v1/conversations/:id/messages — Get message history
// POST /api/v1/conversations/:id/feedback — Submit feedback
// POST /api/v1/conversations/:id/escalate — Escalate to human
// GET /api/v1/conversations/:id — Get conversation details
// WebSocket for real-time
// ws://api/v1/ws?token=xxx
// Admin API
// POST /api/v1/admin/knowledge-bases — Create knowledge base
// POST /api/v1/admin/knowledge-bases/:id/documents — Upload document
// GET /api/v1/admin/analytics/conversations — Analytics dashboard
// PUT /api/v1/admin/prompts/:id — Update prompt template
// POST /api/v1/admin/tools — Register tool
Tổng kết Bài 2
- 8 bounded contexts: Conversation, Knowledge, Agent, Channel, AI Engine, Guardrail, Analytics, Billing
- Event-driven architecture với Kafka cho audit trail + async processing + decoupling
- Request flow qua 7 stages: Channel → Input Guard → Context Build → RAG + Memory → Prompt → LLM → Output Guard
- Mỗi service là independently deployable trên Kubernetes
- Core entities: Tenant → Conversation → Message → Citation
Bài tiếp theo: Multi-Model Gateway — cách route requests giữa OpenAI/Claude/Gemini/self-hosted models, fallback chain, cost optimization, và token budget management.