Phase 1: Foundation

Build the infrastructure everything else depends on.

Timeline: Q1 2026 (8-10 weeks) Goal: Identity, payments, and basic agent working

Why This First

Every product needs:
├── Authentication → YeboID
├── Payments → YeboSafe  
└── Agent access → Core Orchestrator

Build once. Use everywhere.

Without Phase 1, every product would need its own auth, its own payments, its own chat handling. That's fragmented — the opposite of what we're building.

1.1 YeboID — Identity Layer

What We're Building

Component	Description	Priority
Auth API	Phone + PIN signup/signin	P0
Token System	JWT access + refresh tokens	P0
Handle System	@username registration	P0
Profile API	Basic profile CRUD	P0
Node SDK	Middleware for other products	P0
Hub UI	Login/signup web interface	P1
React SDK	Frontend components	P1

Technical Spec

Database (Neon PostgreSQL)

sql

-- Core tables
users (id, phone, pin_hash, handle, name, avatar_url, kyc_status, created_at)
otp_codes (id, phone, code, purpose, expires_at, verified_at)
sessions (id, user_id, refresh_token_hash, device_info, expires_at)
reserved_handles (id, handle, reason)

API Endpoints

POST /auth/otp/send          Send OTP to phone
POST /auth/otp/verify        Verify OTP
POST /auth/signup            Create account
POST /auth/signin            Login with phone + PIN
POST /auth/pin/reset         Reset PIN
POST /auth/refresh           Refresh tokens
POST /auth/logout            Logout

GET  /users/me               Get current user
PATCH /users/me              Update profile
GET  /users/@:handle         Public profile
GET  /users/handle/check     Check availability

Security

PIN: bcrypt hash, cost 12
Tokens: Access (15min JWT), Refresh (30 days, hashed)
Rate limits: 3 OTP/hour, 5 signin attempts/15min
Lockout: 5 failed PINs → 15min lock

Timeline

Week	Tasks
1	Database schema, basic API structure
2	Auth endpoints (signup, signin, OTP)
3	Token system, refresh flow
4	Handle system, profile API
5	Node SDK, testing
6	Hub UI, deployment

Definition of Done

[ ] User can sign up with phone + OTP + PIN
[ ] User can sign in with phone + PIN
[ ] User can choose/change @handle
[ ] Other products can validate tokens via SDK
[ ] Hub UI live at id.yebo.com (or staging)

1.2 YeboSafe — Payment Layer

What We're Building

Component	Description	Priority
Wallet API	Balance, transactions	P0
Deposit Flow	Mobile money → Wallet	P0
Withdrawal Flow	Wallet → Mobile money	P0
Escrow Logic	Hold, release, refund	P0
M-Pesa Integration	Kenya/Tanzania	P0
MTN Money	West Africa	P1
Transaction History	Ledger, statements	P1

Technical Spec

Database

sql

-- Wallet
wallets (id, user_id, balance, currency, created_at)
transactions (id, wallet_id, type, amount, reference, status, created_at)

-- Escrow
escrows (id, order_id, buyer_wallet, seller_wallet, amount, status, created_at)
escrow_events (id, escrow_id, event, actor_id, created_at)

-- Mobile Money
mm_deposits (id, wallet_id, provider, phone, amount, reference, status)
mm_withdrawals (id, wallet_id, provider, phone, amount, reference, status)

Transaction Types

deposit      Mobile money → Wallet
withdrawal   Wallet → Mobile money
escrow_hold  Wallet → Escrow
escrow_release  Escrow → Seller wallet
escrow_refund   Escrow → Buyer wallet
transfer     Wallet → Wallet
fee          System fee deduction

Escrow Flow

CREATED → FUNDED → SHIPPED → DELIVERED → RELEASED
                          ↓
                      DISPUTED → REFUNDED

M-Pesa Integration

Daraja API (Safaricom)
STK Push for deposits
B2C for withdrawals
Webhook for confirmations

Timeline

Week	Tasks
1	Database schema, wallet API
2	Transaction ledger, balance logic
3	M-Pesa deposit (STK Push)
4	M-Pesa withdrawal (B2C)
5	Escrow logic
6	Testing, edge cases

Definition of Done

[ ] User has wallet with balance
[ ] User can deposit via M-Pesa
[ ] User can withdraw to M-Pesa
[ ] Escrow can hold/release/refund
[ ] All transactions logged

1.3 Core Agent — Chat Orchestrator

What We're Building

Component	Description	Priority
Intent Recognition	Understand what user wants	P0
Product Router	Route to correct product	P0
Context Manager	Remember conversation state	P0
Response Formatter	Cards, buttons, rich UI	P0
Chat UI	Yebo Chat web app	P0
Web Chat Adapter	React chat component	P1
SMS Adapter	Fallback	P2

Technical Spec

Intent Recognition (Gemini)

javascript

const intents = {
  // Commerce
  'sell': { product: 'yeboshops', action: 'create_listing' },
  'buy': { product: 'yeboshops', action: 'search' },
  
  // Jobs
  'find_job': { product: 'yebojobs', action: 'search' },
  'apply': { product: 'yebojobs', action: 'apply' },
  
  // Payments
  'send_money': { product: 'yebosafe', action: 'transfer' },
  'check_balance': { product: 'yebosafe', action: 'balance' },
  
  // Communications
  'send_invoice': { product: 'yebolink', action: 'invoice' },
  'send_message': { product: 'yebolink', action: 'send' },
  
  // Meta
  'help': { product: 'core', action: 'help' },
  'profile': { product: 'yeboid', action: 'profile' },
};

Context Structure

javascript

{
  userId: 'uuid',
  handle: '@laslie',
  
  // Current conversation
  currentIntent: 'sell',
  currentProduct: 'yeboshops',
  currentState: 'awaiting_photos',
  
  // Collected data
  pendingListing: {
    photos: [],
    title: null,
    price: null
  },
  
  // History
  recentIntents: ['sell', 'check_balance'],
  lastActive: timestamp
}

Product Router

javascript

async function route(intent, context) {
  const { product, action } = intents[intent.type];
  
  switch (product) {
    case 'yeboshops':
      return await yeboshopsAdapter.execute(action, intent, context);
    case 'yebojobs':
      return await yebojobsAdapter.execute(action, intent, context);
    case 'yebosafe':
      return await yebosafeAdapter.execute(action, intent, context);
    // ...
  }
}

Response Format

javascript

{
  type: 'card',
  content: {
    title: 'Nike Air Max',
    subtitle: 'KES 3,500',
    image: 'https://...',
    buttons: [
      { label: 'Buy Now', action: 'buy', data: { listingId: '...' } },
      { label: 'Make Offer', action: 'offer', data: { listingId: '...' } }
    ]
  }
}

Timeline

Week	Tasks
1	Intent recognition with Gemini
2	Product router, adapter interface
3	Context management, state machine
4	Response formatting, rich messages
5	Chat UI
6	Web chat adapter, testing

Definition of Done

[ ] Agent understands basic intents (sell, buy, find job, etc.)
[ ] Agent routes to correct product
[ ] Agent maintains conversation context
[ ] Agent responds with rich cards/buttons
[ ] Works on Yebo Chat
[ ] Works on web

Phase 1 Integration

How Components Connect

User message (Yebo Chat)
        │
        ▼
┌─────────────────────┐
│   Core Orchestrator │
│   • Parse intent    │
│   • Load context    │
│   • Route to product│
└──────────┬──────────┘
           │
     ┌─────┴─────┐
     ▼           ▼
┌─────────┐ ┌─────────┐
│ YeboID  │ │YeboSafe │
│ (Auth)  │ │(Payment)│
└─────────┘ └─────────┘

Shared Infrastructure

Database: Neon PostgreSQL (separate DBs per service)
Hosting: Cloud Run
Secrets: GCP Secret Manager
Queue: Cloud Tasks (for async jobs)

Environment Setup

env

# All services share
YEBOID_JWT_SECRET=shared-secret-for-token-validation

# YeboID
DATABASE_URL=postgresql://...yeboid
YEBOLINK_API_KEY=for-sending-otp

# YeboSafe
DATABASE_URL=postgresql://...yebosafe
MPESA_CONSUMER_KEY=...
MPESA_CONSUMER_SECRET=...

# Orchestrator
DATABASE_URL=postgresql://...orchestrator
GEMINI_API_KEY=...
YEBOID_API_URL=https://api.yeboid.com
YEBOSAFE_API_URL=https://api.yebosafe.com

Success Metrics

Metric	Target
YeboID signups	1,000 in first month
Auth success rate	>99%
Payment success rate	>95%
Agent intent accuracy	>85%
Response time	<2s average

Risks & Mitigations

Risk	Impact	Mitigation
M-Pesa integration delays	High	Start integration early, have fallback
AI intent accuracy low	Medium	Start with limited intents, expand
User adoption	Medium	Leverage existing Eneza users

Phase 1 Exit Criteria

Before moving to Phase 2:

[ ] YeboID: Users can sign up, sign in, have profiles
[ ] YeboSafe: Deposits and withdrawals working
[ ] Orchestrator: Basic intents routed correctly
[ ] Integration: All three components talking
[ ] Testing: End-to-end flow tested
[ ] Deployment: All services on Cloud Run

Next: Phase 2: Core Products

API

Backend API

Okia AI Service

Frontend

Student Dashboard

Teacher Dashboard

Parent Dashboard

School Admin Dashboard

Phase 1: Foundation ​

Why This First ​

1.1 YeboID — Identity Layer ​

What We're Building ​

Technical Spec ​

Timeline ​

Definition of Done ​

1.2 YeboSafe — Payment Layer ​

What We're Building ​

Technical Spec ​

Timeline ​

Definition of Done ​

1.3 Core Agent — Chat Orchestrator ​

What We're Building ​

Technical Spec ​

Timeline ​

Definition of Done ​

Phase 1 Integration ​

How Components Connect ​

Shared Infrastructure ​

Environment Setup ​

Success Metrics ​

Risks & Mitigations ​

Phase 1 Exit Criteria ​

Phase 1: Foundation

Why This First

1.1 YeboID — Identity Layer

What We're Building

Technical Spec

Timeline

Definition of Done

1.2 YeboSafe — Payment Layer

What We're Building

Technical Spec

Timeline

Definition of Done

1.3 Core Agent — Chat Orchestrator

What We're Building

Technical Spec

Timeline

Definition of Done

Phase 1 Integration

How Components Connect

Shared Infrastructure

Environment Setup

Success Metrics

Risks & Mitigations

Phase 1 Exit Criteria