Architecture
How the pieces fit together.
System Overview
┌────────────────────────────────────────────────────────────────┐
│ USER INTERFACES │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Yebo Chat │ │ Mobile App │ │ SMS │ │
│ │ (Web App) │ │ (Flutter) │ │ Fallback │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └─────────────────┼─────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ YEBO ORCHESTRATOR │ │
│ │ │ │
│ │ • Intent Recognition (Gemini) │ │
│ │ • Context Management (per-user state) │ │
│ │ • Product Router (which product handles what) │ │
│ │ • Action Executor (do the thing) │ │
│ │ • Response Formatter (cards, buttons, etc.) │ │
│ └────────────────────────┬────────────────────────────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ YeboID │ │Product APIs│ │ YeboSafe │ │
│ │ (Auth) │ │(Shops,Jobs)│ │ (Payments) │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │
└────────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────┐
│ EXTERNAL SERVICES │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Mobile │ │ Resend │ │ Gemini │ │ YeboLink │ │
│ │ Money │ │ (Email) │ │ (AI) │ │ (SMS) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└────────────────────────────────────────────────────────────────┘Core Components
1. User Interfaces
How users interact with Yebo:
| Interface | Use Case | Tech |
|---|---|---|
| Yebo Chat | Primary experience | React + Vite (app.hiyebo.com) |
| Mobile App | Native experience | Flutter |
| SMS | Fallback, basic commands | YeboLink SMS API |
2. Yebo Orchestrator
The brain that understands and routes:
javascript
// Simplified flow
async function handleMessage(userId, message) {
// 1. Load user context
const context = await getContext(userId);
// 2. Understand intent
const intent = await ai.classify(message, context);
// e.g., { action: 'sell', item: 'shoes', price: null }
// 3. Route to product
const product = router.getProduct(intent.action);
// e.g., YeboShops
// 4. Execute action
const result = await product.execute(intent, context);
// 5. Format response
const response = formatter.format(result);
// 6. Update context
await updateContext(userId, intent, result);
return response;
}3. Product APIs
Each product exposes API for orchestrator:
javascript
// YeboShops API
POST /listings // Create listing
GET /listings/:id // Get listing
POST /listings/:id/offer // Make offer
POST /orders // Create order
// YeboJobs API
POST /jobs/search // Search jobs
POST /jobs/:id/apply // Apply to job
GET /applications // List applications
// etc.4. Identity (YeboID)
Central authentication:
- Issues JWT tokens
- All products validate locally
- Shared secret across services
5. Payments (YeboSafe)
Central money layer:
- Wallet per user
- Escrow for transactions
- Mobile money integration
Data Flow Examples
Selling an Item
User: "Sell this jacket for 1500"
│
▼
┌─────────────────────────────┐
│ ORCHESTRATOR │
│ Intent: sell │
│ Item: jacket │
│ Price: 1500 │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ YEBOSHOPS API │
│ POST /listings │
│ { title, price, images } │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ ENEZA (optional) │
│ Distribute to WhatsApp │
│ Status ad network │
└──────────────┬──────────────┘
│
▼
Response to UserReceiving Payment
Buyer pays via M-Pesa
│
▼
┌─────────────────────────────┐
│ MOBILE MONEY API │
│ Webhook: payment received │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ YEBOSAFE │
│ Credit escrow │
│ Update order status │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ YEBOLINK │
│ Notify seller │
│ Notify buyer │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ ORCHESTRATOR │
│ Format notification │
│ Send to user │
└─────────────────────────────┘Tech Stack
| Layer | Technology |
|---|---|
| AI | Google Gemini 2.5 Flash |
| Backend | Node.js + Express + TypeScript |
| Database | Neon PostgreSQL |
| Auth | JWT + bcrypt |
| Real-time | Socket.io |
| Queue | Cloud Tasks |
| Hosting | Cloud Run |
| CDN | Cloudflare |
| Payments | Mobile Money APIs |
| Resend | |
| SMS | YeboLink (our own) |
Key Principles
1. Products Are Independent
Each product can run standalone:
- Own database
- Own API
- Own deployment
2. Orchestrator Connects
The agent layer connects products:
- Understands context
- Routes to right product
- Aggregates responses
3. Identity Is Central
YeboID is the one shared dependency:
- All products validate same token
- User is consistent everywhere
4. Payments Are Infrastructure
YeboSafe underlies all transactions:
- Not a product users see directly
- Powers escrow, wallet, payouts
Security Model
Authentication
- JWT tokens (15 min expiry)
- Refresh tokens (30 days)
- PIN for sensitive actions
Authorization
- Product-level permissions
- Action-specific confirmations
- Rate limiting everywhere
Data
- Encrypted at rest
- TLS 1.3 in transit
- No sensitive data in logs
Scaling Strategy
Phase 1: Monolith
- Single orchestrator service
- Products as separate services
- Works to 100K users
Phase 2: Distributed
- Orchestrator scales horizontally
- Database read replicas
- CDN for static content
Phase 3: Regional
- Multi-region deployment
- Data residency compliance
- Local mobile money integrations
Next: The Agent System — Deep dive into AI orchestration.