YeboNa PRD

China-Africa Trade & Sourcing Platform

Product: YeboNa
Tagline: "Import with Confidence"
Last Updated: 2026-03-19
Status: In Development (MVP Complete)

1. Vision & Problem Statement

The Problem

African entrepreneurs and businesses face massive friction when importing goods from China:

Trust Deficit — No way to verify Chinese suppliers, sourcing agents, or freight forwarders
Payment Risk — Sending money overseas with no recourse if supplier disappears
Information Asymmetry — Hidden fees, fake quotes, and no price transparency
Language Barriers — Communication breakdowns lead to wrong products, missed deadlines
Currency Complexity — Converting ZAR/NGN/KES to CNY/USD is expensive and confusing
Fragmented Services — Need separate contacts for sourcing, shipping, customs, exchange

The Vision

YeboNa is a trusted marketplace connecting African buyers with verified Chinese suppliers and service providers—with escrow protection, transparent pricing, and end-to-end tracking.

Think "Alibaba + Upwork + Escrow.com" purpose-built for China-Africa trade.

Target Markets

Primary: Nigeria, South Africa, Kenya, Ghana, Tanzania
Secondary: Uganda, Rwanda, Ethiopia, Senegal, Côte d'Ivoire, Eswatini
Supplier Side: China (Guangzhou, Yiwu, Shenzhen)

2. Solution Overview

Core Value Propositions

For African Buyers	For Chinese Suppliers/Agents
Find verified providers	Access African buyer demand
Escrow-protected payments	Get paid reliably
Compare quotes transparently	Build reputation via reviews
Track orders end-to-end	Expand market reach
Multi-language support	Reduce payment friction

Service Categories (Implemented)

typescript

type ServiceCategory = 
  | 'sourcing'      // Product sourcing & factory finding
  | 'freight'       // Shipping & logistics
  | 'exchange'      // Currency exchange (CNY↔USD↔local)
  | 'inspection'    // Quality inspection
  | 'customs'       // Customs clearance
  | 'translation'   // Translation & negotiation
  | 'verification'  // Supplier verification
  | 'other';

3. Core Features (Implemented)

3.1 User Accounts & Authentication

Phone-based signup with OTP verification (WhatsApp/SMS via YeboLink)
Password authentication with secure hashing (bcrypt)
JWT access tokens (15-minute expiry) with refresh token rotation (30-day)
Multi-country support: China, Nigeria, South Africa, Kenya, Ghana, Tanzania, Uganda, Eswatini + 15 more African countries
User types: buyer (default), provider, both
Verification levels: unverified, phone_verified, id_verified, fully_verified

3.2 Provider Profiles & Services

Provider registration with business name, bio, location, languages
Service catalog: Each provider can offer multiple services across categories
Pricing models: Fixed price, per-unit, hourly, custom quote
Rating system: Overall + breakdown (communication, quality, value, timeliness)
Provider status: pending, active, suspended, inactive

3.3 Service Requests (RFQ System)

Request creation: Category, title, description, attachments, budget range, timeline
Request lifecycle: open → quoted → in_progress → completed / cancelled / expired
Targeted requests: Can specify specific providers to quote
Auto-expiry: Requests expire after configurable period

3.4 Quote Management

Quote submission: Amount, currency, description, deliverables, timeline, validity
Quote status: pending → accepted / declined / expired
Single quote per provider per request (no spam)
Quote comparison: Buyers see all quotes with provider ratings

3.5 Escrow Transactions

Transaction creation: Automatically created when quote accepted
Platform fee: 5% of transaction amount (configurable)

Transaction states:

pending_payment → payment_received → in_progress → completed → released
                                                ↘ disputed → refunded

Proof uploads: Payment proof, completion proof (URLs stored)
Dispute handling: Either party can open dispute, admin resolves

3.6 Messaging System

1:1 conversations between buyers and providers
Request-linked chats: Conversations tied to specific requests
Message types: text, image, file, system, quote, payment
Read receipts: Track message read status
Conversation search: Find by participant

3.7 Reviews & Ratings

Bidirectional reviews: Users review providers, providers review users
5-star rating with breakdown categories
Photo attachments on reviews
Provider response: Providers can respond to reviews
Rating aggregation: Automatic recalculation on new reviews

3.8 Waitlist & Pre-launch

Waitlist signup: Name, phone, interest, country, source tracking
Status management: pending, approved, invited, registered
Email notifications: New signup alerts to admin
CEO Dashboard integration: Waitlist data accessible via API

3.9 Blog/Content System

Blog posts: Title, slug, content, excerpt, category, tags
AI-powered: Integrated with autoblogger for content generation
SEO-ready: Slugs, meta descriptions, featured images

4. User Journeys

4.1 African Buyer Journey

1. DISCOVERY
   └─ Lands on yebona.com → Sees value prop & providers
   
2. SIGNUP
   └─ Enter phone → Receive OTP → Create password → Verify
   
3. POST REQUEST
   └─ Select category → Describe need → Set budget → Submit
   
4. COMPARE QUOTES
   └─ Receive quotes → View provider profiles → Compare prices
   
5. ACCEPT & PAY
   └─ Accept quote → Transaction created → Make payment (escrow)
   
6. TRACK & COMMUNICATE
   └─ Message provider → Track progress → Receive updates
   
7. CONFIRM & REVIEW
   └─ Confirm delivery → Release payment → Leave review

4.2 Chinese Supplier/Agent Journey

1. REGISTER
   └─ Signup → Complete provider profile → Add services
   
2. BROWSE REQUESTS
   └─ View open requests → Filter by category → Find opportunities
   
3. SUBMIT QUOTES
   └─ Create detailed quote → Set price & timeline → Submit
   
4. WIN & DELIVER
   └─ Quote accepted → Payment confirmed → Start work
   
5. COMPLETE & GET PAID
   └─ Submit deliverables → Buyer confirms → Receive payout
   
6. BUILD REPUTATION
   └─ Receive reviews → Improve ratings → Attract more business

4.3 Admin Journey (via CEO Dashboard)

1. MONITOR
   └─ View waitlist signups → Track provider applications
   
2. MANAGE
   └─ Verify providers → Resolve disputes → Process payouts
   
3. ANALYZE
   └─ Review transaction metrics → Monitor GMV → Track growth

5. Data Models (Complete Schema)

5.1 Users Table

sql

CREATE TABLE users (
  id              VARCHAR(50) PRIMARY KEY,       -- 'usr_1234567890'
  phone_number    VARCHAR(20) UNIQUE NOT NULL,
  password_hash   VARCHAR(255) NOT NULL,
  email           VARCHAR(255),
  name            VARCHAR(255),
  avatar_url      TEXT,
  country         VARCHAR(100),
  country_code    VARCHAR(10),                   -- 'NG', 'ZA', 'KE'
  user_type       VARCHAR(20) DEFAULT 'buyer',   -- buyer, provider, both
  verification_level VARCHAR(20) DEFAULT 'phone_verified',
  language        VARCHAR(10) DEFAULT 'en',
  currency        VARCHAR(10) DEFAULT 'USD',
  created_at      TIMESTAMP DEFAULT NOW(),
  updated_at      TIMESTAMP DEFAULT NOW()
);

5.2 Refresh Tokens Table

sql

CREATE TABLE refresh_tokens (
  token           VARCHAR(255) PRIMARY KEY,      -- Cryptographic random
  user_id         VARCHAR(50) REFERENCES users(id),
  phone_number    VARCHAR(20) NOT NULL,
  expires_at      TIMESTAMP NOT NULL,            -- 30 days from creation
  created_at      TIMESTAMP DEFAULT NOW()
);

5.3 Providers Table

sql

CREATE TABLE providers (
  id                   VARCHAR(50) PRIMARY KEY,  -- 'prov_1234567890'
  user_id              VARCHAR(50) REFERENCES users(id),
  business_name        VARCHAR(255),
  bio                  TEXT,
  city                 VARCHAR(100),
  country              VARCHAR(100),
  languages            TEXT[],                    -- Array of language codes
  response_time_mins   INTEGER,
  rating               DECIMAL(3,2) DEFAULT 0,
  review_count         INTEGER DEFAULT 0,
  rating_communication DECIMAL(3,2) DEFAULT 0,
  rating_quality       DECIMAL(3,2) DEFAULT 0,
  rating_value         DECIMAL(3,2) DEFAULT 0,
  rating_timeliness    DECIMAL(3,2) DEFAULT 0,
  status               VARCHAR(20) DEFAULT 'pending', -- pending, active, suspended
  verified_at          TIMESTAMP,
  created_at           TIMESTAMP DEFAULT NOW(),
  updated_at           TIMESTAMP DEFAULT NOW()
);

5.4 Provider Services Table

sql

CREATE TABLE provider_services (
  id              VARCHAR(50) PRIMARY KEY,       -- 'svc_1234567890_abc123'
  provider_id     VARCHAR(50) REFERENCES providers(id),
  category        VARCHAR(50) NOT NULL,          -- ServiceCategory enum
  description     TEXT,
  starting_price  DECIMAL(15,2),
  currency        VARCHAR(10) DEFAULT 'USD',
  price_unit      VARCHAR(20) DEFAULT 'fixed',   -- fixed, per_unit, hourly
  created_at      TIMESTAMP DEFAULT NOW(),
  updated_at      TIMESTAMP DEFAULT NOW()
);

5.5 Requests Table

sql

CREATE TABLE requests (
  id              VARCHAR(50) PRIMARY KEY,       -- 'req_1234567890'
  user_id         VARCHAR(50) REFERENCES users(id),
  category        VARCHAR(50) NOT NULL,
  title           VARCHAR(255) NOT NULL,
  description     TEXT NOT NULL,
  attachments     TEXT[],                        -- Array of URLs
  budget_min      DECIMAL(15,2),
  budget_max      DECIMAL(15,2),
  budget_currency VARCHAR(10) DEFAULT 'USD',
  timeline        VARCHAR(100),
  target_providers TEXT[],                       -- Specific provider IDs
  status          VARCHAR(20) DEFAULT 'open',    -- open, quoted, in_progress, completed, cancelled, expired
  expires_at      TIMESTAMP,
  created_at      TIMESTAMP DEFAULT NOW(),
  updated_at      TIMESTAMP DEFAULT NOW()
);

5.6 Quotes Table

sql

CREATE TABLE quotes (
  id              VARCHAR(50) PRIMARY KEY,       -- 'quote_1234567890'
  request_id      VARCHAR(50) REFERENCES requests(id),
  provider_id     VARCHAR(50) REFERENCES providers(id),
  amount          DECIMAL(15,2) NOT NULL,
  currency        VARCHAR(10) DEFAULT 'USD',
  description     TEXT,
  deliverables    TEXT[],                        -- Array of deliverable strings
  timeline        VARCHAR(100),
  valid_until     TIMESTAMP,
  status          VARCHAR(20) DEFAULT 'pending', -- pending, accepted, declined, expired
  created_at      TIMESTAMP DEFAULT NOW(),
  updated_at      TIMESTAMP DEFAULT NOW()
);

5.7 Transactions Table

sql

CREATE TABLE transactions (
  id                   VARCHAR(50) PRIMARY KEY,  -- 'txn_1234567890'
  quote_id             VARCHAR(50) REFERENCES quotes(id),
  request_id           VARCHAR(50) REFERENCES requests(id),
  user_id              VARCHAR(50) REFERENCES users(id),
  provider_id          VARCHAR(50) REFERENCES providers(id),
  amount               DECIMAL(15,2) NOT NULL,
  currency             VARCHAR(10) DEFAULT 'USD',
  fee                  DECIMAL(15,2),             -- Platform fee (5%)
  provider_payout      DECIMAL(15,2),             -- Amount - Fee
  status               VARCHAR(20) DEFAULT 'pending_payment',
  -- pending_payment, payment_received, in_progress, completed, released, disputed, refunded
  payment_proof_url    TEXT,
  completion_proof_url TEXT,
  paid_at              TIMESTAMP,
  completed_at         TIMESTAMP,
  released_at          TIMESTAMP,
  created_at           TIMESTAMP DEFAULT NOW(),
  updated_at           TIMESTAMP DEFAULT NOW()
);

5.8 Conversations Table

sql

CREATE TABLE conversations (
  id               VARCHAR(50) PRIMARY KEY,      -- 'conv_1234567890'
  participant_1_id VARCHAR(50) REFERENCES users(id),
  participant_2_id VARCHAR(50) REFERENCES users(id),
  request_id       VARCHAR(50) REFERENCES requests(id),
  transaction_id   VARCHAR(50) REFERENCES transactions(id),
  last_message_at  TIMESTAMP,
  created_at       TIMESTAMP DEFAULT NOW(),
  updated_at       TIMESTAMP DEFAULT NOW()
);

5.9 Messages Table

sql

CREATE TABLE messages (
  id              VARCHAR(50) PRIMARY KEY,       -- 'msg_1234567890_abc123'
  conversation_id VARCHAR(50) REFERENCES conversations(id),
  sender_id       VARCHAR(50) REFERENCES users(id),
  message_type    VARCHAR(20) DEFAULT 'text',    -- text, image, file, system, quote, payment
  content         TEXT NOT NULL,
  metadata        JSONB,                         -- For structured data (file info, etc.)
  read_at         TIMESTAMP,
  created_at      TIMESTAMP DEFAULT NOW()
);

5.10 Reviews Table

sql

CREATE TABLE reviews (
  id                   VARCHAR(50) PRIMARY KEY,  -- 'review_1234567890'
  transaction_id       VARCHAR(50) REFERENCES transactions(id),
  reviewer_id          VARCHAR(50) REFERENCES users(id),
  reviewee_id          VARCHAR(50) REFERENCES users(id),
  review_type          VARCHAR(20) NOT NULL,     -- user_to_provider, provider_to_user
  rating               DECIMAL(2,1) NOT NULL,    -- 1.0 - 5.0
  rating_communication DECIMAL(2,1),
  rating_quality       DECIMAL(2,1),
  rating_value         DECIMAL(2,1),
  rating_timeliness    DECIMAL(2,1),
  text                 TEXT NOT NULL,            -- Min 20 chars
  photos               TEXT[],
  response             TEXT,                     -- Provider's response
  created_at           TIMESTAMP DEFAULT NOW(),
  updated_at           TIMESTAMP DEFAULT NOW()
);

5.11 Waitlist Table

sql

CREATE TABLE waitlist (
  id          VARCHAR(50) PRIMARY KEY,           -- 'wl_1234567890_abc123'
  name        VARCHAR(255) NOT NULL,
  phone       VARCHAR(20) NOT NULL,
  interest    VARCHAR(50) DEFAULT 'all',         -- all, sourcing, freight, exchange
  product     VARCHAR(50) DEFAULT 'yebona',
  source      VARCHAR(50) DEFAULT 'website',     -- website, referral, social
  status      VARCHAR(20) DEFAULT 'pending',     -- pending, approved, invited, registered
  notes       TEXT,
  country     VARCHAR(100),
  created_at  TIMESTAMP DEFAULT NOW(),
  updated_at  TIMESTAMP DEFAULT NOW(),
  UNIQUE(phone, product)
);

5.12 Blog Posts Table

sql

CREATE TABLE blog_posts (
  id              SERIAL PRIMARY KEY,
  title           VARCHAR(500) NOT NULL,
  slug            VARCHAR(500) UNIQUE NOT NULL,
  content         TEXT NOT NULL,
  excerpt         TEXT,
  category        VARCHAR(100),
  tags            TEXT[],
  status          VARCHAR(20) DEFAULT 'published',  -- draft, published
  author          VARCHAR(100) DEFAULT 'AI',
  featured_image  TEXT,
  published_at    TIMESTAMP DEFAULT NOW(),
  created_at      TIMESTAMP DEFAULT NOW(),
  updated_at      TIMESTAMP DEFAULT NOW()
);

6. API Reference (Complete)

6.1 Authentication

Method	Endpoint	Description	Auth
POST	`/api/auth/send-verification-code`	Send OTP to phone	None
POST	`/api/auth/signup`	Verify OTP & create account	None
POST	`/api/auth/login`	Login with phone/password	None
POST	`/api/auth/refresh`	Refresh access token	RefreshToken
POST	`/api/auth/logout`	Logout (revoke refresh token)	JWT
POST	`/api/auth/logout-all`	Logout all devices	JWT
GET	`/api/auth/me`	Get current user	JWT

Request/Response Examples

typescript

// POST /api/auth/send-verification-code
Request: { phoneNumber: "+2347012345678" }
Response: { success: true, message: "Code sent", otp?: "123456" /* dev only */ }

// POST /api/auth/signup
Request: { phoneNumber: "+2347012345678", otp: "123456", password: "secret123", name: "John Doe" }
Response: { 
  success: true, 
  data: { 
    accessToken: "eyJ...", 
    refreshToken: "abc123...", 
    user: { id, phoneNumber, name, ... } 
  } 
}

// POST /api/auth/login
Request: { phoneNumber: "+2347012345678", password: "secret123" }
Response: { success: true, data: { accessToken, refreshToken, user } }

// POST /api/auth/refresh
Request: { refreshToken: "abc123..." }
Response: { success: true, data: { accessToken, refreshToken } }

6.2 Users

Method	Endpoint	Description	Auth
GET	`/api/users/me`	Get profile	JWT
PATCH	`/api/users/me`	Update profile	JWT

typescript

// PATCH /api/users/me
Request: { name: "John Doe", country: "Nigeria", language: "en", currency: "NGN" }
Response: { success: true, data: { user: { ... } } }

6.3 Providers

Method	Endpoint	Description	Auth
GET	`/api/providers`	List providers with filters	Optional
GET	`/api/providers/:id`	Get provider details	Optional
POST	`/api/providers`	Register as provider	JWT
PATCH	`/api/providers/me`	Update provider profile	JWT
POST	`/api/providers/me/services`	Add service	JWT
DELETE	`/api/providers/me/services/:serviceId`	Remove service	JWT

typescript

// GET /api/providers?category=sourcing&country=China&minRating=4.0&limit=20
Response: {
  success: true,
  data: [{
    id: "prov_123",
    businessName: "TradeLink Asia",
    bio: "Professional sourcing agent...",
    rating: 4.8,
    reviewCount: 189,
    services: [{ category: "sourcing", startingPrice: 100, currency: "USD" }],
    user: { name: "Zhang Wei", verificationLevel: "fully_verified" }
  }],
  total: 45
}

// POST /api/providers
Request: {
  businessName: "My Trading Co",
  bio: "Experienced sourcing agent",
  city: "Guangzhou",
  country: "China",
  languages: ["en", "zh"],
  services: [{ category: "sourcing", description: "Factory finding", startingPrice: 100 }]
}

6.4 Requests

Method	Endpoint	Description	Auth
POST	`/api/requests`	Create request	JWT
GET	`/api/requests`	Get my requests	JWT
GET	`/api/requests/:id`	Get request details	JWT
GET	`/api/requests/open`	Browse open requests (for providers)	Optional
PATCH	`/api/requests/:id/status`	Update status	JWT

typescript

// POST /api/requests
Request: {
  category: "sourcing",
  title: "Need supplier for phone cases",
  description: "Looking for manufacturer of silicone phone cases...",
  attachments: ["https://..."],
  budgetMin: 500,
  budgetMax: 2000,
  budgetCurrency: "USD",
  timeline: "2 weeks"
}
Response: { success: true, data: { id: "req_123", status: "open", ... } }

6.5 Quotes

Method	Endpoint	Description	Auth
POST	`/api/requests/:requestId/quotes`	Submit quote	JWT (Provider)
GET	`/api/quotes/my`	Get my quotes	JWT (Provider)
POST	`/api/quotes/:id/accept`	Accept quote	JWT (Request Owner)
POST	`/api/quotes/:id/decline`	Decline quote	JWT (Request Owner)
POST	`/api/quotes/:id/withdraw`	Withdraw quote	JWT (Provider)

typescript

// POST /api/requests/:requestId/quotes
Request: {
  amount: 800,
  currency: "USD",
  description: "I can find 3 qualified suppliers...",
  deliverables: ["3 supplier quotes", "Sample negotiation", "Factory visit"],
  timeline: "5 days",
  validUntil: "2026-04-01"
}

6.6 Transactions

Method	Endpoint	Description	Auth
GET	`/api/transactions`	Get my transactions	JWT
GET	`/api/transactions/:id`	Get transaction details	JWT
POST	`/api/transactions/:id/confirm-payment`	Confirm payment made	JWT (Buyer)
POST	`/api/transactions/:id/start-work`	Mark work started	JWT (Provider)
POST	`/api/transactions/:id/complete`	Mark work complete	JWT (Provider)
POST	`/api/transactions/:id/release`	Release payment	JWT (Buyer)
POST	`/api/transactions/:id/dispute`	Open dispute	JWT

typescript

// Transaction Flow
1. Quote accepted → Transaction created (pending_payment)
2. Buyer pays → POST /confirm-payment (payment_received)
3. Provider starts → POST /start-work (in_progress)
4. Provider finishes → POST /complete (completed)
5. Buyer confirms → POST /release (released) → Payout to provider

6.7 Conversations & Messages

Method	Endpoint	Description	Auth
GET	`/api/conversations`	Get my conversations	JWT
POST	`/api/conversations`	Create/get conversation	JWT
GET	`/api/conversations/:id/messages`	Get messages	JWT
POST	`/api/conversations/:id/messages`	Send message	JWT

6.8 Reviews

Method	Endpoint	Description	Auth
POST	`/api/transactions/:transactionId/reviews`	Submit review	JWT
GET	`/api/providers/:providerId/reviews`	Get provider reviews	Optional

6.9 Waitlist (Admin API)

Method	Endpoint	Description	Auth
POST	`/api/waitlist`	Join waitlist	None
GET	`/api/waitlist`	List entries	API Key
PATCH	`/api/waitlist/:id`	Update entry	API Key
DELETE	`/api/waitlist/:id`	Delete entry	API Key

6.10 Blog

Method	Endpoint	Description	Auth
GET	`/api/blog/posts`	List published posts	None
GET	`/api/blog/posts/:slug`	Get post by slug	None
POST	`/api/blog/posts`	Create post	API Key

7. Service Architecture

7.1 System Overview

┌─────────────────────────────────────────────────────────────────┐
│                         CLIENTS                                  │
├──────────────────┬──────────────────┬───────────────────────────┤
│   Expo App       │   Landing Page   │   CEO Dashboard           │
│   (iOS/Android)  │   (React/Vite)   │   (waitlist/admin)        │
└────────┬─────────┴────────┬─────────┴───────────┬───────────────┘
         │                  │                     │
         ▼                  ▼                     ▼
┌─────────────────────────────────────────────────────────────────┐
│                    YEBONA API (Cloud Run)                        │
│   Express.js + TypeScript                                        │
│   ├── Routes (auth, providers, requests, quotes, transactions)  │
│   ├── Controllers (business logic)                               │
│   ├── Services (database, email, whatsapp)                       │
│   └── Middleware (auth, validation)                              │
└────────────────────────────┬────────────────────────────────────┘
                             │
         ┌───────────────────┼───────────────────┐
         ▼                   ▼                   ▼
┌────────────────┐  ┌────────────────┐  ┌────────────────┐
│   Neon DB      │  │   YeboLink     │  │   Resend       │
│   (Postgres)   │  │   (SMS/WA)     │  │   (Email)      │
└────────────────┘  └────────────────┘  └────────────────┘

7.2 Tech Stack

Layer	Technology	Purpose
Mobile App	Expo/React Native	Cross-platform mobile app
API	Express.js + TypeScript	REST API server
Database	Neon (Serverless Postgres)	Primary data store
Auth	Custom JWT + Refresh Tokens	Authentication
SMS/WhatsApp	YeboLink (via Swychr)	OTP delivery, notifications
Email	Resend	Email notifications
Hosting	Google Cloud Run	Serverless containers
State Mgmt	Zustand	Mobile app state
HTTP Client	Axios	API calls with interceptors

7.3 External Integrations

Service	Purpose	Status
YeboLink API	Send OTP codes via WhatsApp/SMS	✅ Implemented
Resend	Email notifications (waitlist alerts)	✅ Implemented
CEO Dashboard	Admin access to waitlist data	✅ Implemented

8. Authentication & Authorization

8.1 Authentication Flow

1. User enters phone number
2. Backend generates 6-digit OTP
3. OTP sent via YeboLink (WhatsApp preferred, SMS fallback)
4. User enters OTP + password
5. Backend verifies OTP, creates user, returns tokens
6. Access token (15 min) + Refresh token (30 days)
7. App stores tokens securely (SecureStore on mobile, localStorage on web)
8. Axios interceptor auto-refreshes on 401

8.2 Token Management

typescript

// Access Token (short-lived, stateless)
{
  userId: "usr_123",
  phoneNumber: "+2347012345678",
  type: "access",
  exp: 1679529600000,  // 15 minutes
  iat: 1679528700000
}

// Refresh Token (long-lived, stored in DB)
// Cryptographically random string stored in refresh_tokens table
// Can be revoked individually or all at once

8.3 Authorization Rules

Resource	Buyer	Provider	Admin
Create request	✅	✅	✅
Submit quote	❌	✅	❌
Accept quote	✅ (own)	❌	❌
Release payment	✅ (own)	❌	❌
Mark complete	❌	✅ (own)	❌
View transactions	✅ (own)	✅ (own)	✅
Manage waitlist	❌	❌	✅ (API key)

9. Payment & Escrow System

9.1 Current Implementation

The escrow system is logically implemented but payment processing is manual:

1. Quote accepted → Transaction created (pending_payment)
2. Buyer pays provider directly (bank transfer, mobile money, etc.)
3. Buyer confirms payment in app → (payment_received)
4. Provider delivers service
5. Provider marks complete → (completed)
6. Buyer releases → (released)
7. Platform takes 5% fee (tracked, not auto-collected)

9.2 Fee Structure

typescript

const PLATFORM_FEE_PERCENT = 0.05; // 5%

// On transaction creation:
fee = amount * PLATFORM_FEE_PERCENT;
providerPayout = amount - fee;

// Example: $1000 transaction
// Fee: $50
// Provider receives: $950

9.3 Dispute Resolution

Either party can open dispute with reason
Transaction status becomes disputed
Admin notified via logging (no automated resolution yet)
Manual resolution: refund or release

10. Logistics & Shipping

10.1 Current Implementation

Shipping/freight is handled as a service category—providers offer freight services, and the marketplace facilitates matching.

NOT YET IMPLEMENTED:

Real-time shipment tracking
Automated freight quotes
Integration with shipping carriers
Container/shipping cost calculators

10.2 Provider Capabilities

Freight providers can offer:

Sea freight (FCL/LCL)
Air freight
Door-to-door delivery
Customs clearance
Warehousing

11. Translation & Localization

11.1 Current Implementation

App Language: English (hardcoded)
User Language Preference: Stored in users.language but not used
Provider Languages: Array of language codes (['en', 'zh', 'fr'])

11.2 Translation as a Service

Translation is offered as a service category (translation)—providers offer translation/negotiation services.

NOT YET IMPLEMENTED:

In-app translation
Auto-translate messages
Multi-language UI

12. Notifications

12.1 Implemented Channels

Channel	Implementation	Use Case
WhatsApp	YeboLink API	OTP, critical alerts
SMS	YeboLink API (fallback)	OTP when WhatsApp fails
Email	Resend	Waitlist notifications

12.2 Notification Types

typescript

// Implemented in whatsappService.ts
sendVerificationCodeMessage()     // OTP
sendPasswordResetCode()           // Password reset
sendNewMatchNotification()        // (legacy from dating app, unused)
sendNewMessageNotification()      // New message alert
sendRequestAcceptedNotification() // Quote accepted
sendNewRequestNotification()      // New request for provider
sendServiceCompletedNotification() // Work marked complete
sendVerificationApprovedNotification() // Provider verified
sendVerificationRejectedNotification() // Verification failed

12.3 NOT YET IMPLEMENTED

Push notifications (mobile)
In-app notification center
Email notifications for transactions
SMS notifications for transaction updates

13. Technical Stack Details

13.1 Backend Dependencies

json

{
  "express": "^4.18.2",
  "typescript": "^5.3.3",
  "@neondatabase/serverless": "^0.10.6",
  "bcryptjs": "^2.4.3",
  "resend": "^2.1.0",
  "cors": "^2.8.5",
  "dotenv": "^16.4.1"
}

13.2 Mobile App Dependencies

json

{
  "expo": "~54.0.33",
  "expo-router": "~6.0.23",
  "expo-secure-store": "^15.0.8",
  "axios": "^1.13.5",
  "zustand": "^5.0.11",
  "react-hook-form": "^7.71.1",
  "zod": "^4.3.6",
  "@tanstack/react-query": "^5.90.21",
  "expo-linear-gradient": "^15.0.8"
}

13.3 Infrastructure

Component	Service	Region
API	Google Cloud Run	europe-west1
Database	Neon Postgres	eu-central-1
Domain	api.yebona.com	Cloudflare

14. Roadmap

Phase 1: MVP (COMPLETE) ✅

[x] User registration/auth with OTP
[x] Provider profiles & services
[x] Request/quote system
[x] Transaction/escrow flow
[x] Messaging system
[x] Reviews & ratings
[x] Waitlist
[x] Blog CMS
[x] Mobile app (Expo)

Phase 2: Payment Integration (NEXT)

[ ] Stripe Connect for escrow
[ ] Multi-currency support (USD, CNY, NGN, ZAR, KES)
[ ] Automatic payouts to providers
[ ] Payment method management
[ ] Currency exchange integration

Phase 3: Enhanced Discovery

[ ] AI-powered provider matching
[ ] Product search (image-based)
[ ] Verified supplier database
[ ] Price comparison tools
[ ] Market intelligence

Phase 4: Logistics & Tracking

[ ] Shipping carrier integrations
[ ] Real-time tracking
[ ] Automated freight quotes
[ ] Container calculator
[ ] Customs documentation

Phase 5: Scale & Localization

[ ] Multi-language UI (Chinese, French, Portuguese)
[ ] In-app translation
[ ] Push notifications
[ ] Provider mobile app
[ ] White-label for enterprises

15. Gaps & Needed Features

15.1 Critical Missing (Phase 2)

Feature	Priority	Effort	Notes
Stripe/Payment Integration	P0	High	Currently manual payments
Provider Verification Flow	P0	Medium	Manual approval only
Currency Exchange Rates	P0	Medium	Needed for multi-currency
File Upload	P0	Medium	No media storage (URLs only)
Push Notifications	P0	Medium	No mobile push yet

15.2 Important Missing (Phase 3)

Feature	Priority	Effort	Notes
Admin Dashboard	P1	High	Using CEO dashboard proxy
Provider Analytics	P1	Medium	No dashboard for providers
Order Tracking	P1	High	No shipment integration
Search/Filter Improvements	P1	Medium	Basic filtering only
Rate Limiting	P1	Low	No API rate limits

15.3 Nice to Have (Phase 4+)

Feature	Priority	Notes
Product catalog	P2	AI-powered product search
Supplier directory	P2	Verified Chinese supplier database
In-app translation	P2	AI translation for messages
Batch orders	P2	Group buying for better prices
Insurance integration	P3	Cargo insurance
Trade finance	P3	Payment terms, letters of credit

15.4 Technical Debt

Issue	Impact	Fix
No input validation	Security	Add Zod schemas
No rate limiting	Security	Add express-rate-limit
Passwords in plain logs	Security	Sanitize logger
No pagination cursor	Performance	Add cursor-based pagination
No caching	Performance	Add Redis cache
No tests	Quality	Add Jest test suite

16. Appendix

A. Environment Variables

bash

# Database
DATABASE_URL=postgresql://...@neon.tech/neondb?sslmode=require

# API Keys
DASHBOARD_API_KEY=yebona_dashboard_key_2026
INTERNAL_API_KEY=yebona_internal_key_2026

# Email
RESEND_API_KEY=re_xxx
NOTIFICATION_EMAIL=admin@yebona.com

# Runtime
PORT=3000
NODE_ENV=production

B. API Base URLs

Environment	URL
Production	https://api.yebona.com
Cloud Run	https://yebona-api-igsg3gipka-ew.a.run.app
Local Dev	http://localhost:3000

C. Mobile App Config

javascript

// app.json (Expo)
{
  "name": "yebona-app",
  "slug": "yebona",
  "scheme": "yebona",
  "extra": {
    "apiUrl": "https://api.yebona.com"
  }
}

Document generated from codebase analysis. Last updated: 2026-03-19

API

Backend API

Okia AI Service

Frontend

Student Dashboard

Teacher Dashboard

Parent Dashboard

School Admin Dashboard

YeboNa PRD ​

China-Africa Trade & Sourcing Platform ​

1. Vision & Problem Statement ​

The Problem ​

The Vision ​

Target Markets ​

2. Solution Overview ​

Core Value Propositions ​

Service Categories (Implemented) ​

3. Core Features (Implemented) ​

3.1 User Accounts & Authentication ​

3.2 Provider Profiles & Services ​

3.3 Service Requests (RFQ System) ​

3.4 Quote Management ​

3.5 Escrow Transactions ​

3.6 Messaging System ​

3.7 Reviews & Ratings ​

3.8 Waitlist & Pre-launch ​

3.9 Blog/Content System ​

4. User Journeys ​

4.1 African Buyer Journey ​

4.2 Chinese Supplier/Agent Journey ​

4.3 Admin Journey (via CEO Dashboard) ​

5. Data Models (Complete Schema) ​

5.1 Users Table ​

5.2 Refresh Tokens Table ​

5.3 Providers Table ​

5.4 Provider Services Table ​

5.5 Requests Table ​

5.6 Quotes Table ​

5.7 Transactions Table ​

5.8 Conversations Table ​

5.9 Messages Table ​

5.10 Reviews Table ​

5.11 Waitlist Table ​

5.12 Blog Posts Table ​

6. API Reference (Complete) ​

6.1 Authentication ​

Request/Response Examples ​

6.2 Users ​

6.3 Providers ​

6.4 Requests ​

6.5 Quotes ​

6.6 Transactions ​

6.7 Conversations & Messages ​

6.8 Reviews ​

6.9 Waitlist (Admin API) ​

6.10 Blog ​

7. Service Architecture ​

7.1 System Overview ​

7.2 Tech Stack ​

7.3 External Integrations ​

8. Authentication & Authorization ​

8.1 Authentication Flow ​

8.2 Token Management ​

8.3 Authorization Rules ​

9. Payment & Escrow System ​

9.1 Current Implementation ​

9.2 Fee Structure ​

9.3 Dispute Resolution ​

10. Logistics & Shipping ​

10.1 Current Implementation ​

10.2 Provider Capabilities ​

11. Translation & Localization ​

11.1 Current Implementation ​

11.2 Translation as a Service ​

12. Notifications ​

12.1 Implemented Channels ​

12.2 Notification Types ​

12.3 NOT YET IMPLEMENTED ​

13. Technical Stack Details ​

13.1 Backend Dependencies ​

YeboNa PRD

China-Africa Trade & Sourcing Platform

1. Vision & Problem Statement

The Problem

The Vision

Target Markets

2. Solution Overview

Core Value Propositions

Service Categories (Implemented)

3. Core Features (Implemented)

3.1 User Accounts & Authentication

3.2 Provider Profiles & Services

3.3 Service Requests (RFQ System)

3.4 Quote Management

3.5 Escrow Transactions

3.6 Messaging System

3.7 Reviews & Ratings

3.8 Waitlist & Pre-launch

3.9 Blog/Content System

4. User Journeys

4.1 African Buyer Journey

4.2 Chinese Supplier/Agent Journey

4.3 Admin Journey (via CEO Dashboard)

5. Data Models (Complete Schema)

5.1 Users Table

5.2 Refresh Tokens Table

5.3 Providers Table

5.4 Provider Services Table

5.5 Requests Table

5.6 Quotes Table

5.7 Transactions Table

5.8 Conversations Table

5.9 Messages Table

5.10 Reviews Table

5.11 Waitlist Table

5.12 Blog Posts Table

6. API Reference (Complete)

6.1 Authentication

Request/Response Examples

6.2 Users

6.3 Providers

6.4 Requests

6.5 Quotes

6.6 Transactions

6.7 Conversations & Messages

6.8 Reviews

6.9 Waitlist (Admin API)

6.10 Blog

7. Service Architecture

7.1 System Overview

7.2 Tech Stack

7.3 External Integrations

8. Authentication & Authorization

8.1 Authentication Flow

8.2 Token Management

8.3 Authorization Rules

9. Payment & Escrow System

9.1 Current Implementation

9.2 Fee Structure

9.3 Dispute Resolution

10. Logistics & Shipping

10.1 Current Implementation

10.2 Provider Capabilities

11. Translation & Localization

11.1 Current Implementation

11.2 Translation as a Service

12. Notifications

12.1 Implemented Channels

12.2 Notification Types

12.3 NOT YET IMPLEMENTED

13. Technical Stack Details

13.1 Backend Dependencies

13.2 Mobile App Dependencies

13.3 Infrastructure

14. Roadmap

Phase 1: MVP (COMPLETE) ✅

Phase 2: Payment Integration (NEXT)

Phase 3: Enhanced Discovery

Phase 4: Logistics & Tracking

Phase 5: Scale & Localization