YeboVerify Deep Dive - Architecture

YeboVerify is an identity verification API that uses AI-powered face comparison and document OCR to verify users.

Repository Structure

yeboverify/monorepo/
├── yeboverify-api/            # Node.js + Express API
│   ├── src/
│   │   ├── controllers/       # Route handlers
│   │   ├── services/          # Business logic
│   │   ├── routes/            # API endpoints
│   │   ├── middleware/        # Auth, upload
│   │   └── config/            # Prisma, app config
│   └── prisma/
│       └── schema.prisma      # Database schema
├── sdk/                       # Client SDKs
│   ├── node/                  # Node.js SDK
│   ├── react/                 # React widget
│   ├── react-native/          # React Native SDK
│   ├── swift/                 # iOS SDK
│   ├── kotlin/                # Android SDK
│   └── flutter/               # Flutter SDK
├── yeboverify-dashboard/      # Business dashboard
└── yeboverify-landing/        # Marketing website

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Client Application                        │
│              (SDK / Widget / Direct API)                     │
└──────────────────────────┬──────────────────────────────────┘
                           │ POST /v1/verify
                           │ (multipart: idFront, selfie)
┌──────────────────────────▼──────────────────────────────────┐
│                    YeboVerify API                            │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Verification Service                     │   │
│  │                                                       │   │
│  │  1. Upload images to R2 (private)                    │   │
│  │  2. Start async processing                           │   │
│  │  3. Return verificationId immediately                │   │
│  └──────────────────────────┬───────────────────────────┘   │
│                             │                               │
│  ┌──────────────────────────▼───────────────────────────┐   │
│  │            Background Processing                      │   │
│  │                                                       │   │
│  │  ┌─────────────┐     ┌─────────────┐                 │   │
│  │  │ Rekognition │     │  Gemini AI  │                 │   │
│  │  │   (Face)    │     │   (OCR)     │                 │   │
│  │  └──────┬──────┘     └──────┬──────┘                 │   │
│  │         │                   │                         │   │
│  │         └─────────┬─────────┘                         │   │
│  │                   │                                   │   │
│  │           ┌───────▼───────┐                           │   │
│  │           │   Decision    │                           │   │
│  │           │   Engine      │                           │   │
│  │           └───────┬───────┘                           │   │
│  │                   │                                   │   │
│  └───────────────────┼───────────────────────────────────┘   │
│                      │                                       │
│              ┌───────▼───────┐                              │
│              │   Webhook     │──────► Business Server       │
│              │   Service     │                              │
│              └───────────────┘                              │
└─────────────────────────────────────────────────────────────┘

Verification Pipeline

1. Image Upload - ID front, optional back, selfie
2. Face Comparison - AWS Rekognition compares selfie to ID photo
3. Document OCR - Gemini AI extracts personal information
4. Decision Engine - Combines scores for final decision
5. Webhook Delivery - Notifies business of result

Decision Logic

if (faceScore >= 85 && ocrConfidence >= 70) {
  decision = 'APPROVED';
  confidence = 'high';
} else if (faceScore >= 70 && ocrConfidence >= 50) {
  if (faceScore >= 80 && ocrConfidence >= 60) {
    decision = 'APPROVED';
    confidence = 'medium';
  } else {
    decision = 'NEEDS_REVIEW';
    confidence = 'medium';
  }
} else {
  decision = 'REJECTED';
  confidence = 'low';
}

Authentication

API key-based authentication:

X-API-Key: your_api_key_here

Verification Statuses

Status	Meaning
PENDING	Submitted, waiting for processing
PROCESSING	Currently being analyzed
COMPLETED	Processing finished
FAILED	Processing error
NEEDS_REVIEW	Requires manual review

Decision Values

Decision	When
APPROVED	High confidence match
REJECTED	Failed verification
NEEDS_REVIEW	Borderline, needs human review

Key Features

• Fast Processing - Results in seconds
• Multi-Document Support - ID cards, passports, licenses
• Liveness Detection - Coming soon
• Multi-SDK Support - 6 platform SDKs
• Webhook Integration - Real-time notifications
• GDPR Compliant - Images encrypted, never stored publicly