YeboNa Deep Dive - Architecture

YeboNa is a cross-border services marketplace connecting users with providers for currency exchange, product sourcing, verification, freight, translation, and consulting.

Repository Structure

yebona/
├── api/                        # Node.js + Express API
│   ├── src/
│   │   ├── controllers/        # Route handlers
│   │   ├── services/           # Business logic + database
│   │   ├── routes/             # API endpoints
│   │   ├── middleware/         # Auth, validation
│   │   ├── utils/              # Helpers, JWT
│   │   └── config/             # App configuration
│   └── package.json
├── app/                        # React Native mobile app
│   └── ...
└── landing/                    # Marketing website

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                   Load Balancer (Cloud Run)                  │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                     YeboNa API                               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │   Auth   │  │ Providers│  │ Requests │  │  Quotes  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │   Txns   │  │ Messages │  │ Reviews  │  │   Blog   │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
└──────────────────────────┬──────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
┌───────▼───────┐  ┌───────▼───────┐  ┌──────▼──────┐
│  Neon Postgres │  │   WhatsApp    │  │   Redis     │
│  (Serverless)  │  │  (YeboLink)   │  │  (Optional) │
└────────────────┘  └───────────────┘  └─────────────┘

Service Categories

YeboNa supports 6 service categories:

Category	Description	Use Cases
exchange	Currency exchange	Cross-border money transfer
sourcing	Product sourcing	Import goods from China, etc.
verification	Document verification	Business checks, references
freight	Shipping & logistics	International shipping
translation	Language services	Document translation
consulting	Business consulting	Market entry, compliance

Database Layer

YeboNa uses Neon Serverless Postgres with inline SQL (not Prisma/ORM):

import { neon } from '@neondatabase/serverless';

export const sql = neon(config.databaseUrl);

// Example query
const users = await sql`
  SELECT * FROM users WHERE phone_number = ${phone}
`;

User Types

type UserType = 'user' | 'provider' | 'both';

• User: Can post requests, hire providers
• Provider: Can offer services, submit quotes
• Both: Can do both

Key Flows

1. Provider Onboarding

User Registers → Becomes Provider → Adds Services → Gets Verified → Listed

2. Service Request Flow

User Posts Request → Providers See It → Submit Quotes → User Accepts → Transaction → Escrow → Completion → Review

3. Transaction Lifecycle

pending_payment → payment_received → in_progress → completed → released
                          ↓                            ↓
                     disputed ←─────────────────── refunded

Authentication

• Phone number + password
• OTP via WhatsApp (YeboLink)
• JWT access tokens (15min expiry)
• Refresh tokens (7 days)

// JWT Payload
interface TokenPayload {
  userId: string;
  phoneNumber: string;
  exp: number;
}

Trust & Verification

Level	Requirements
phone	Phone verified (default)
id	ID document verified
business	Business registration
pro	Full verification + track record

Provider Ratings

Multi-dimensional rating system:

interface ProviderRatings {
  rating: number;              // Overall (1-5)
  rating_communication: number;
  rating_quality: number;
  rating_value: number;
  rating_timeliness: number;
  review_count: number;
}

Integration Points

Service	Purpose
YeboLink	WhatsApp OTP delivery
Neon	Serverless PostgreSQL
Cloud Run	API hosting
Cloudflare Pages	Landing page

Security Features

• Rate limiting (20 auth attempts / 15 min)
• Password hashing
• JWT with refresh token rotation
• CORS configuration