YeboLink Deep Dive: Architecture Overview

YeboLink is a multi-channel messaging platform built for African businesses. It provides unified APIs for sending SMS, Email, WhatsApp, and Voice messages through a credit-based billing system.

Repository Structure

The YeboLink monorepo (~/Documents/omevision/yebolink/monorepo/) contains five projects:

yebolink/monorepo/
├── yebolink-backend/      # Express.js API server
├── yebolink-dashboard/    # React dashboard (Vite + TailwindCSS)
├── yebolink-admin/        # Admin dashboard for platform management
├── yebolink-landing/      # Marketing website
└── yebolink-docs/         # API documentation site

Technology Stack

Backend (yebolink-backend)

• Runtime: Node.js + TypeScript
• Framework: Express.js
• Database: PostgreSQL (via pg pool)
• Queue: Google Cloud Tasks (async message processing)
• Auth: JWT + API Keys (HMAC-SHA256 hashed)
• Payments: Stripe (multi-currency support)
• SMS/Voice: Twilio
• Email: Resend
• AI: Google Gemini (sender name verification)

Frontend (yebolink-dashboard)

• Framework: React 18 + TypeScript
• Build: Vite
• Styling: TailwindCSS
• State: TanStack Query (React Query)
• Routing: React Router v6

High-Level Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         CLIENT LAYER                                │
├─────────────────────────────────────────────────────────────────────┤
│  Dashboard (React)  │  API Clients (SDK/curl)  │  Webhooks (inbound)│
└──────────┬──────────┴───────────┬──────────────┴──────────┬─────────┘
           │                      │                         │
           ▼                      ▼                         ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         EXPRESS API SERVER                          │
├─────────────────────────────────────────────────────────────────────┤
│  Middleware: CORS │ Helmet │ Rate Limiting │ Auth (JWT/API Key)     │
├─────────────────────────────────────────────────────────────────────┤
│  Routes:                                                            │
│  /api/v1/auth      → Authentication & Session Management            │
│  /api/v1/messages  → Send SMS/Email/WhatsApp (single + bulk)        │
│  /api/v1/account   → Balance, Usage Stats, Profile                  │
│  /api/v1/api-keys  → Manage API Keys                                │
│  /api/v1/billing   → Credit Packages, Stripe Checkout               │
│  /api/v1/contacts  → Contact Management (CRUD)                      │
│  /api/v1/webhooks  → Webhook Configuration                          │
│  /api/dashboard    → CEO/Admin Dashboard (protected)                │
│  /api/blog         → Autoblogger integration                        │
│  /internal         → Cloud Tasks workers                            │
└──────────┬──────────────────────┬────────────────────────┬──────────┘
           │                      │                        │
           ▼                      ▼                        ▼
┌───────────────────┐  ┌───────────────────┐  ┌───────────────────────┐
│    PostgreSQL     │  │   Cloud Tasks     │  │   External Providers  │
│    (Neon)         │  │   (async queue)   │  │   • Twilio (SMS/Voice)│
│                   │  │                   │  │   • Resend (Email)    │
│   12 tables       │  │  message-queue    │  │   • Stripe (Payments) │
│                   │  │  webhook-queue    │  │   • Gemini (AI)       │
└───────────────────┘  └───────────────────┘  └───────────────────────┘

Core Concepts

1. Workspaces

A workspace represents a customer account. Each workspace has:

• Credentials (email/password)
• Credit balance
• API keys
• Contacts
• Webhooks
• Message history

2. Credit System

Messages are paid via credits:

Channel	Credits
SMS	1.0
WhatsApp	0.5
Email	0.1
Voice	2.0
Push	0.05
Web	0.0

Credits are purchased via Stripe checkout with multi-currency support for African countries.

3. Message Flow

1. API Request → Authenticated via JWT or API Key
2. Balance Check → Ensure sufficient credits
3. Message Queued → Saved to DB with status queued
4. Cloud Tasks → Async job enqueued
5. Provider Send → Twilio/Resend delivers message
6. Status Update → Webhook callbacks update status
7. Workspace Webhook → Notify customer of delivery

4. Authentication

Two authentication methods:

• JWT (Bearer Token) — For dashboard users, 7-day expiry with refresh tokens
• API Key (X-API-Key) — For programmatic access, format ybk_<hex>

Backend Source Structure

yebolink-backend/src/
├── app.ts              # Express app setup, middleware, routes
├── config/
│   ├── database.ts     # PostgreSQL connection pool
│   ├── env.ts          # Environment variable loader
│   └── swagger.ts      # OpenAPI documentation config
├── controllers/
│   ├── blog.controller.ts
│   └── dashboard.controller.ts
├── jobs/
│   └── queues.ts       # Cloud Tasks integration
├── middleware/
│   ├── auth.ts         # JWT + API Key authentication
│   ├── dashboardAuth.ts # Admin API key auth
│   ├── errorHandler.ts # Error handling + AppError class
│   ├── rateLimiter.ts  # Rate limiting (general, API, bulk, auth)
│   └── validator.ts    # express-validator schemas
├── models/
│   ├── apiKey.ts       # API key CRUD
│   ├── contact.ts      # Contact management
│   ├── message.ts      # Message CRUD + stats
│   ├── refreshToken.ts # Refresh token management
│   ├── transaction.ts  # Credit transactions
│   ├── verificationToken.ts # Email/password tokens
│   ├── webhook.ts      # Webhook + delivery tracking
│   └── workspace.ts    # Workspace CRUD + credit ops
├── routes/
│   ├── account.routes.ts
│   ├── apiKeys.routes.ts
│   ├── auth.routes.ts
│   ├── billing.routes.ts
│   ├── blog.routes.ts
│   ├── contacts.routes.ts
│   ├── dashboard.routes.ts
│   ├── internal.routes.ts
│   ├── messages.routes.ts
│   └── webhooks.routes.ts
├── services/
│   ├── auth.service.ts           # JWT, signup, login, password reset
│   ├── billing.service.ts        # Stripe checkout, credit packages
│   ├── blog.service.ts           # Blog post CRUD
│   ├── dashboard.service.ts      # Platform metrics
│   ├── email.service.ts          # Resend email sending
│   ├── message.service.ts        # Message sending orchestration
│   ├── message-processor.service.ts # Async message delivery
│   ├── resend.service.ts         # Email notifications
│   ├── sender-verification.service.ts # AI sender name check
│   ├── twilio.service.ts         # SMS/Voice via Twilio
│   └── webhook.service.ts        # Webhook management
├── types/
│   └── index.ts        # TypeScript interfaces
└── utils/
    ├── crypto.ts       # Password hashing, API key generation
    ├── currencies.ts   # Multi-currency pricing
    └── logger.ts       # Winston logging

Environment Variables

Key environment variables required:

# Core
NODE_ENV=production
PORT=3000
APP_URL=https://api.yebolink.com
FRONTEND_URL=https://app.yebolink.com

# Auth
JWT_SECRET=<secret>
API_KEY_SECRET=<secret>

# Database
DATABASE_URL=postgres://...

# Twilio (SMS/Voice)
TWILIO_ACCOUNT_SID=<sid>
TWILIO_AUTH_TOKEN=<token>
TWILIO_API_KEY_SID=<sid>
TWILIO_API_KEY_SECRET=<secret>
TWILIO_PHONE_NUMBER=+1...

# Email
RESEND_API_KEY=re_...
FROM_EMAIL=noreply@yebolink.com

# Payments
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_MODE=live

# Cloud Tasks
GCLOUD_PROJECT=yebolink
CLOUD_TASKS_LOCATION=europe-west1

# AI
GEMINI_API_KEY=AIza...

Deployment

• Backend: Google Cloud Run (auto-scaled)
• Dashboard: Cloudflare Pages
• Database: Neon (serverless Postgres)
• Queue: Google Cloud Tasks

Deploy via deploy.sh in the backend directory which handles secrets binding to Cloud Run.

Related Deep-Dive Pages

• Services — All service classes
• Controllers — Controller implementations
• Routes — Complete endpoint reference (40+)
• Models — Database schema (12 tables)
• Middleware — Auth, rate limiting, validation
• Billing — Credit system & Stripe
• Providers — SMS/Email/WhatsApp abstraction
• Webhooks — Event notification system
• Dashboard — Frontend application