YeboSafe Deep Dive - Architecture

YeboSafe is an escrow-as-a-service API that enables secure transactions between parties by holding funds until conditions are met.

Repository Structure

yebosafe/monorepo/
├── yebosafe-api/              # Node.js + Express API
│   ├── src/
│   │   ├── controllers/       # Route handlers
│   │   ├── services/          # Business logic
│   │   ├── routes/            # API endpoints
│   │   ├── middleware/        # Auth, validation
│   │   └── config/            # Prisma, app config
│   └── prisma/
│       └── schema.prisma      # Database schema
├── yebosafe-dashboard/        # Merchant dashboard (React)
└── yebosafe-landing/          # Marketing website

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     Merchant Application                     │
│                    (Uses YeboSafe API)                       │
└──────────────────────────┬──────────────────────────────────┘
                           │ API Calls
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                     YeboSafe API                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │    Escrow    │  │   Merchant   │  │   Webhooks   │      │
│  │   Service    │  │   Service    │  │   Service    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│  ┌──────────────┐  ┌──────────────┐                        │
│  │   Wallet     │  │    Admin     │                        │
│  │   Service    │  │   Service    │                        │
│  └──────────────┘  └──────────────┘                        │
└──────────────────────────┬──────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
┌───────▼───────┐  ┌───────▼───────┐  ┌──────▼──────┐
│  PostgreSQL   │  │   Merchant    │  │   Payment   │
│   (Neon)      │  │   Webhooks    │  │  Providers  │
└───────────────┘  └───────────────┘  └─────────────┘

Core Concept

Escrow Flow:

1. Merchant creates escrow with amount and description
2. Payer receives completion code
3. Merchant accepts (commits to deliver)
4. Upon delivery, payer provides completion code
5. Funds released to merchant wallet

Authentication

Merchant Authentication

Two modes supported via flexAuth middleware:

1. API Key (for server-to-server):

   Authorization: Bearer sk_live_xxx

2. JWT Token (for dashboard):

   Authorization: Bearer eyJhbGc...

API Key Structure

sk_live_abc123xyz...
│  │
│  └── Environment (live/test)
└── Prefix identifier

Escrow Status Flow

PENDING ─────┬───► ACCEPTED ───► COMPLETED
             │         │
             │         └───► DISPUTED
             │
             ├───► REFUSED
             │
             └───► CANCELLED ───► REFUNDED

Merchant Wallet

Each merchant has a wallet that:

• Receives funds from completed escrows
• Tracks balance by currency
• Logs all transactions

Webhook Events

Event	Trigger
escrow.created	New escrow created
escrow.accepted	Merchant accepts
escrow.refused	Merchant declines
escrow.completed	Completion code used
escrow.disputed	Dispute opened
escrow.cancelled	Escrow cancelled

Security Features

• HMAC-SHA256 webhook signatures
• API key hashing
• Rate limiting
• Audit logging via EscrowLog

Integration Points

Service	Purpose
PostgreSQL (Neon)	Primary database
Merchant Webhooks	Event notifications
Cloud Run	API hosting