YeboID Deep Dive — Architecture Overview

One identity. All of Yebo. Forever.

YeboID is the centralized identity layer for the entire Yebo ecosystem. It provides phone-based authentication, JWT token management, @handle identifiers, and KYC integration across all Yebo products.

---

Repository Structure

~/Documents/omevision/yeboid/monorepo/
├── api/                          # Express API server
│   ├── prisma/
│   │   └── schema.prisma         # Database schema (Users, OTP, RefreshTokens)
│   ├── src/
│   │   ├── index.ts              # Express app entry point
│   │   ├── middleware/
│   │   │   ├── auth.ts           # JWT validation middleware
│   │   │   └── error.ts          # Error handling middleware
│   │   ├── routes/
│   │   │   ├── auth.ts           # Authentication endpoints
│   │   │   └── users.ts          # User profile endpoints
│   │   └── services/
│   │       ├── db.ts             # Prisma client singleton
│   │       ├── handle.ts         # Handle validation logic
│   │       ├── otp.ts            # OTP generation & verification
│   │       └── token.ts          # JWT & refresh token management
│   ├── package.json
│   └── tsconfig.json
├── sdk/                          # Client SDKs
│   ├── node/                     # @yeboid/node backend SDK
│   │   └── README.md             # SDK documentation
│   ├── react/                    # @yeboid/react (planned)
│   └── react-native/             # @yeboid/react-native (planned)
├── docs/                         # VitePress documentation
├── AUTH_SPEC.md                  # Authentication specification
├── CONSOLIDATION.md              # User consolidation strategy
├── PRODUCT.md                    # Full product specification
└── README.md                     # Project overview

---

System Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         YeboID System                                │
│                                                                      │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐   │
│  │   YeboID API     │  │   YeboID Web     │  │   YeboID SDKs    │   │
│  │                  │  │                  │  │                  │   │
│  │ api.yeboid.com   │  │  id.yebo.com     │  │  @yeboid/node    │   │
│  │ Express + TS     │  │  (planned)       │  │  @yeboid/react   │   │
│  └────────┬─────────┘  └──────────────────┘  └──────────────────┘   │
│           │                                                          │
│           ▼                                                          │
│  ┌──────────────────┐                                               │
│  │  Neon PostgreSQL │                                               │
│  │  (Prisma ORM)    │                                               │
│  └──────────────────┘                                               │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘
                            │
                            │ JWT Tokens (validated locally via shared secret)
                            ▼
┌──────────────────────────────────────────────────────────────────────┐
│                        Yebo Products                                  │
│                                                                       │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐            │
│  │ YeboShops │ │ YeboJobs  │ │  Eneza    │ │ YeboLink  │            │
│  └───────────┘ └───────────┘ └───────────┘ └───────────┘            │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐            │
│  │  YeboNa   │ │ YeboLearn │ │ YeboSafe  │ │ YeboCars  │            │
│  └───────────┘ └───────────┘ └───────────┘ └───────────┘            │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘

---

How YeboID Connects to All Products

Token Flow

1. User authenticates via YeboID (phone + OTP)
2. YeboID issues tokens:
   • Access Token (JWT, 15 minutes)
   • Refresh Token (random string, 7 days, stored in DB)
3. User accesses any product with the access token
4. Product validates locally using shared YEBOID_JWT_SECRET
5. No API call to YeboID for validation — fast & scalable
6. Token refresh happens via YeboID API when access token expires

Shared Secret Distribution

All Yebo products share YEBOID_JWT_SECRET:

GCP Secret Manager (organization level)
         │
         └─── YEBOID_JWT_SECRET
              │
              ├─── YeboShops (Cloud Run)
              ├─── YeboJobs (Cloud Run)
              ├─── Eneza (Cloud Run)
              ├─── YeboLink (Cloud Run)
              └─── [All other products]

Product Integration Pattern

Each product links to YeboID via yeboidUserId:

// In each product's schema
model User {
  id            String   @id @default(uuid())
  yeboidUserId  String   @unique @map("yeboid_user_id")
  
  // Product-specific fields
  shopName      String?  // YeboShops
  resume        Json?    // YeboJobs
  // etc.
}

---

Tech Stack

Component	Technology
Runtime	Node.js + TypeScript
Framework	Express.js 4.x
Database	Neon PostgreSQL
ORM	Prisma 7.x
Auth	JWT (jsonwebtoken)
Validation	Zod
OTP Delivery	YeboLink SMS API
KYC	YeboVerify (planned)
Hosting	Cloud Run (planned)

---

Environment Variables

# Database
DATABASE_URL=postgres://...neon.tech/yeboid

# JWT Configuration
JWT_SECRET=your-secret-key
JWT_ACCESS_EXPIRY=15m        # Optional, default: 15m

# OTP Configuration  
OTP_EXPIRY_MINUTES=5         # Optional, default: 5
OTP_LENGTH=6                 # Optional, default: 6

# YeboLink SMS
YEBOLINK_API_URL=https://api.yebolink.com
YEBOLINK_API_KEY=your-yebolink-key

# Server
PORT=3000
NODE_ENV=production

---

API Endpoints Overview

Prefix	Purpose
/health	Health check
/auth/*	Authentication (OTP, verify, refresh, logout)
/users/*	User profiles and handles

See routes.md for complete route documentation.

---

Key Concepts

1. Phone = Identity

Phone number is the unique identifier. No emails, no usernames — just phone.

2. OTP for Verification Only

OTP is sent only for:

• First-time signup
• PIN reset (future)

3. JWT for Sessions

• Access Token: Short-lived (15 min), contains userId
• Refresh Token: Long-lived (7 days), stored in DB, rotated on use

4. @handle System

• Unique human-readable identifier (e.g., @laslie)
• 3-30 characters, lowercase + numbers + underscores
• Reserved words blocked

5. Local Token Validation

Products validate tokens locally using shared JWT secret — no network call to YeboID per request.

---

Related Documentation

• services.md — All services with methods & params
• routes.md — Complete route map
• models.md — Full Prisma schema
• middleware.md — Auth & error middleware
• sdk.md — @yeboid/node SDK integration
• consolidation.md — User consolidation strategy