Introduction
You can write a Python script that calls the OpenAI API in 20 lines of code. But when needed:
- Support 10 different LLM providers with automatic fallback?
- Multi-tenant — many organizations share the same platform but data isolated?
- Visual workflow builder so people who don't know how to code can create AI pipelines?
- Plugin system expands according to each industry (Healthcare, Finance, Legal)?
- Chat channels connect Telegram, Discord, Slack, Zalo at the same time?
Then you need an AI Agent Platform — not a script.
1. Why do we need Platform?
1.1 Script vs Platform
| Aspect | Single script | AI Agent Platform |
|---|---|---|
| LLM Provider | Hardcode 1 provider | 10+ providers, auto-fallback |
| Users | 1 developer | Multi-tenant, RBAC |
| Knowledge | None | RAG Pipeline + Knowledge Base |
| Automation | Manual triggers | Visual Workflow Engine |
| Extensibility | Edit code | Plugin system, Domain Packs |
| Channels | CLI / API | Telegram, Discord, Slack, Web... |
| Monitoring | console.log | Audit logs, metrics, dashboard |
1.2 Practical problems
Imagine you're building AI for a company:
CEO: "Tôi muốn chatbot hỗ trợ khách hàng trên Telegram và Zalo"
CTO: "Phải hỗ trợ nhiều LLM, có thể chuyển provider khi cần"
Dev: "Cần workflow automation cho quy trình nội bộ"
Legal: "Data giữa các phòng ban phải cách ly, có audit log"
Finance: "Agent phải hiểu domain tài chính"
One script cannot satisfy everything. You need a platform.
2. xClaw overview architecture
xClaw uses Gateway + Monorepo architecture:
┌─────────────────────────────────────────────────────┐
│ Clients │
│ Web App │ Telegram │ Discord │ Slack │ Zalo │ CLI │
└─────────────────┬───────────────────────────────────┘
│ HTTP / WebSocket / Bot APIs
▼
┌─────────────────────────────────────────────────────┐
│ API Gateway (@xclaw-ai/gateway) │
│ Hono — Port 3000 │
│ ┌──────┬──────┬──────┬──────┬──────┬──────┐ │
│ │ Auth │ RBAC │ Rate │ CORS │ Audit│ PII │ │
│ │ │ │Limit │ │ Log │Filter│ │
│ └──────┴──────┴──────┴──────┴──────┴──────┘ │
├─────────────────────────────────────────────────────┤
│ Core Engine (@xclaw-ai/core) │
│ ┌──────────┬────────────┬──────────┬────────────┐ │
│ │ Agent │ LLM │ RAG │ Workflow │ │
│ │ Engine │ Router │ Engine │ Engine │ │
│ ├──────────┼────────────┼──────────┼────────────┤ │
│ │ Tools │ Skills │ Memory │ Monitoring │ │
│ │ Registry│ Manager │ Manager │ Store │ │
│ └──────────┴────────────┴──────────┴────────────┘ │
├─────────────────────────────────────────────────────┤
│ Data Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │PostgreSQL│ │ MongoDB │ │ Redis │ │
│ │(Config) │ │(AI/Chat) │ │ (Cache) │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────┘
2.1 Why this architecture?
Gateway Pattern:
- A single entry point for all clients
- Middleware chain: Auth → RBAC → Rate Limit → Route Handler
- Easy to add new channels without affecting the core
Monorepo Pattern:
- Shared types between all packages
- Build order is clear with project references
- Atomic changes — edit type definition, all packages updated at the same time
3. Dual-Database Design
Most important architectural decision: separate database according to data nature.
3.1 PostgreSQL — Structured Config Data
tenants ──┬── tenantSettings
├── users ──── userRoles ──── roles ──── rolePermissions ──── permissions
├── oauthAccounts
├── workflows ──── workflowExecutions
├── integrationConnections
└── webhooks
Why PostgreSQL?
- ACID transactions — ensures consistency for user/role operations
- Relational joins — query user permissions across multiple tables
- Drizzle ORM — type-safe, compile-time SQL validation
- Schema migrations — version control database schema
3.2 MongoDB — Flexible AI Data
sessions ──── messages
agent_configs
memory_entries
audit_logs (TTL: 90 days)
system_logs (TTL: 30 days)
Why MongoDB?
- Flexible schema — AI messages have complex structures (tool calls, images, embeddings)
- Time-series TTL — auto-cleanup audit logs, system logs
- Document storage — no need to normalize chat history
- High write throughput — many concurrent chat sessions
3.3 Redis — In-Memory Cache
- Session cache — avoid database roundtrip per request
- Rate limiting counters
- Real-time metrics aggregation
4. Tech Stack Decisions
| Decision | Choice | Alternatives considered | Reason |
|---|---|---|---|
| Language | TypeScript | Python, Go, Rust | Full-stack (backend + frontend), good LLM SDK ecosystem |
| API Framework | Honor | Express, Fastify, Koa | Lightweight, Web Standards, edge-ready, good middleware |
| Frontend | React 19 + Vite | Next.js, Vue, Svelte | Vite HMR is fast, the largest React ecosystem |
| State Mgmt | Zustand | Redux, Jotai, MobX | Lightweight, no boilerplate |
| PG ORM | Drizzle | Prisma, TypeORM, Kysely | Type-safe SQL, no runtime overhead, easy custom queries |
| Auth | JWT + bcrypt | Passport.js, Auth0 | Self-hosted, simple, no 3rd party dependencies |
| Build | Docker | K8s, bare metal | Docker Compose for devs, easy to scale to K8s later |
| Modules | ESM | CommonJS | Standard, tree-shaking, top-level await |
5. Monorepo structure
xClaw/
├── packages/
│ ├── shared/ # Foundation types & constants
│ ├── core/ # Agent engine, LLM, RAG, workflow, monitoring
│ │ └── src/
│ │ ├── agent/ # Agent class, EventBus
│ │ ├── llm/ # LLM adapters, router
│ │ ├── rag/ # RAG engine, vector store, embeddings
│ │ ├── workflow/ # Workflow engine, node handlers
│ │ ├── tools/ # Tool registry
│ │ ├── skills/ # Skill manager
│ │ ├── memory/ # Memory manager
│ │ ├── streaming/ # Stream utilities
│ │ ├── monitoring/ # Metrics collection
│ │ ├── guardrails/ # Input/output safety
│ │ ├── tracing/ # Distributed tracing
│ │ └── plugins/ # Plugin loader
│ ├── db/ # Drizzle ORM (PG) + MongoDB driver
│ │ └── src/
│ │ ├── schema/ # Drizzle table definitions
│ │ ├── migrations/ # SQL migrations
│ │ ├── mongo.ts # MongoDB connection
│ │ ├── seed.ts # Initial data
│ │ └── monitoring-store.ts
│ ├── gateway/ # Hono HTTP server, all API routes
│ │ └── src/
│ │ ├── auth.ts # Login, register, JWT
│ │ ├── chat.ts # Chat endpoint
│ │ ├── knowledge.ts # RAG endpoints
│ │ ├── workflows.ts # Workflow CRUD + execute
│ │ ├── rbac.ts # RBAC management
│ │ ├── monitoring.ts
│ │ └── ... (30+ route files)
│ ├── server/ # Entry point, startup orchestration
│ ├── integrations/ # 11 service connectors
│ ├── domains/ # 13 industry domain packs
│ ├── skills/ # Built-in skills
│ ├── skill-hub/ # Marketplace, MCP adapters
│ ├── ml/ # 12 ML algorithms, AutoML
│ ├── cli/ # CLI interface
│ ├── sandbox/ # Sandboxed code execution
│ ├── web/ # React frontend
│ └── channels/ # Telegram, Discord, Slack, Zalo, MS Teams
├── docker-compose.yml
├── Dockerfile
└── package.json
Build Order (Project References)
shared → db → core → integrations → domains → ml → skills → skill-hub → gateway → server
Each package clearly declares its dependencies tsconfig.json project references. Build server will automatically build all dependencies in order.
6. Hands-on: Explore xClaw
6.1 Clone & run
git clone --recurse-submodules https://github.com/xdev-asia-labs/xClaw.git
cd xClaw
cp .env.example .env
docker compose up --build
6.2 Access
- Frontend: http://localhost:3001
- API: http://localhost:3000
- Health check: http://localhost:3000/health
# Login
curl -X POST http://localhost:3000/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "password": "password123"}'
# Kết quả: {"token": "eyJhbG..."}
6.3 Explore source code
Open the IDE and take a look at the main files:
| File | Function |
|---|---|
packages/shared/src/types/ | All TypeScript types |
packages/core/src/agent/agent.ts | Agent class — the heart of the platform |
packages/core/src/llm/llm-router.ts | LLM routing & fallback |
packages/core/src/rag/rag-engine.ts | Complete RAG pipeline |
packages/core/src/workflow/workflow-engine.ts | Workflow execution |
packages/gateway/src/gateway.ts | Hono server setup |
packages/db/src/schema/ | Database schema |
7. Summary
In this article you have understood:
- Why do we need AI Agent Platform instead of a single script
- Gateway + Monorepo Architecture — efficient code organization
- Dual-Database Design — PostgreSQL for config, MongoDB for AI data, Redis for cache
- Tech stack decisions — reasons for choosing TypeScript, Hono, Drizzle, React
- Source code structure of xClaw
Next article: We will start setting up TypeScript monorepo from scratch — npm workspaces, project references, shared types.