Skip to content

Instantly share code, notes, and snippets.

@AustinWood

AustinWood/vitaboom-vendor-proxy-architecture.md

Created December 12, 2025 15:58
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save AustinWood/03201ec9c308e6168e89bdf1780e4bd0 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save AustinWood/03201ec9c308e6168e89bdf1780e4bd0 to your computer and use it in GitHub Desktop.
Download ZIP
Vitaboom Vendor Proxy Architecture - Visual Documentation
Raw
vitaboom-vendor-proxy-architecture.md

Vitaboom Vendor Proxy Architecture

Visual documentation of the vendor integration architecture transformation

Architecture Overview

This document illustrates how Vitaboom's backend proxy simplifies vendor integrations with Shopify, transforming complex direct Shopify API interactions into a streamlined, vendor-friendly interface.

Before: Direct Shopify Integration (Without Proxy)

Architecture Diagram

flowchart TB
    subgraph "Vendor System"
        V1[Vendor Application]
        V2[Shopify Admin Access]
        V3[Custom Integration Code]
    end

    subgraph "Shopify Ecosystem"
        S1[Shopify Admin API]
        S2[GraphQL Endpoint]
        S3[REST Admin API]
        S4[Webhook Subscriptions]
        S5[OAuth App]
    end

    subgraph "Integration Complexity"
        I1[OAuth Flow Implementation]
        I2[GraphQL Schema Knowledge]
        I3[API Rate Limiting Logic]
        I4[Webhook Signature Validation]
        I5[Error Handling & Retries]
        I6[Data Transformation]
    end

    V1 -->|1. Authenticate| S5
    S5 -->|2. Access Token| V3
    V3 -->|3. Create Order| S2
    S2 -->|GraphQL Mutation| S1
    S1 -->|4. Order Response| V3
    S1 -->|5. Webhook Events| V3
    V3 -->|Implement| I1
    V3 -->|Implement| I2
    V3 -->|Implement| I3
    V3 -->|Implement| I4
    V3 -->|Implement| I5
    V3 -->|Implement| I6

    style V1 fill:#ff9999
    style V2 fill:#ff9999
    style V3 fill:#ff9999
    style I1 fill:#ffcccc
    style I2 fill:#ffcccc
    style I3 fill:#ffcccc
    style I4 fill:#ffcccc
    style I5 fill:#ffcccc
    style I6 fill:#ffcccc
Loading

Challenges

Technical Complexity:

  • Vendors must implement OAuth 2.0 flow
  • Requires deep Shopify GraphQL/REST API knowledge
  • Must handle rate limiting (bucket-based)
  • Complex webhook signature validation (HMAC-SHA256)
  • Manual retry logic for failed requests
  • Data transformation between Shopify and vendor formats

Operational Burden:

  • Each vendor needs dedicated Shopify app
  • Individual API credentials management
  • Direct exposure to Shopify API changes
  • No centralized monitoring or error handling
  • Difficult to maintain consistency across vendors

Security Concerns:

  • Vendors have direct Shopify store access
  • Broader permissions than necessary
  • Multiple OAuth apps increase attack surface
  • Webhook endpoints must be publicly accessible

After: Vitaboom Proxy Integration (With Proxy)

Architecture Diagram - API Flow

flowchart TB
    subgraph "Vendor System"
        V1[Vendor Application]
        V2[Simple REST Client]
    end

    subgraph "Vitaboom Backend Proxy"
        direction TB
        P1[API Gateway]
        P2[Vendor Authentication<br/>API Key Validation]
        P3[Order Validation<br/>Joi Schemas]
        P4[Shopify Service Layer]
        P5[Vendor Order Database]
        P6[Auto-Tagging Logic]
        P7[Error Handling & Retry]
    end

    subgraph "Shopify Ecosystem"
        S1[Shopify Admin API]
        S2[GraphQL Endpoint]
    end

    V1 -->|1. POST /api/vendor/{slug}/orders<br/>X-API-Key: xxx| P1
    P1 -->|2. Validate Key| P2
    P2 -->|3. Validate Payload| P3
    P3 -->|4. Transform & Enrich| P4
    P4 -->|5. Auto-add Vendor Tag| P6
    P4 -->|6. GraphQL Mutation| S2
    S2 -->|7. Shopify Order| P4
    P4 -->|8. Store Mapping| P5
    P5 -->|9. Simple Response| V1
    P7 -.->|Automatic Retries| P4

    style V1 fill:#99ff99
    style V2 fill:#99ff99
    style P1 fill:#cce5ff
    style P2 fill:#cce5ff
    style P3 fill:#cce5ff
    style P4 fill:#cce5ff
    style P5 fill:#cce5ff
    style P6 fill:#cce5ff
    style P7 fill:#cce5ff
Loading

Architecture Diagram - Webhook Flow

flowchart TB
    subgraph "Shopify Ecosystem"
        S1[Shopify Admin]
        S2[Order Created Event]
        S3[Order Fulfilled Event]
        S4[Order Cancelled Event]
        S5[Order Updated Event]
    end

    subgraph "Vitaboom Backend Proxy"
        direction TB
        P1[Webhook Receiver<br/>HMAC Validation]
        P2[Event Classification]
        P3[Webhook Event Database]
        P4[Vendor Lookup<br/>By Order Tags]
        P5[Payload Transformation]
        P6[Webhook Forwarder]
        P7[Retry Queue<br/>Max 3 Attempts]
    end

    subgraph "Vendor Systems"
        V1[Humanaut Webhook]
        V2[Thrivelab Webhook]
        V3[Other Vendors...]
    end

    S2 & S3 & S4 & S5 -->|1. Shopify Webhook<br/>HMAC Signature| P1
    P1 -->|2. Validate & Parse| P2
    P2 -->|3. Store Event| P3
    P3 -->|4. Identify Vendor| P4
    P4 -->|5. Transform Format| P5
    P5 -->|6a. Forward to Vendor| V1
    P5 -->|6b. Forward to Vendor| V2
    P5 -->|6c. Forward to Vendor| V3
    P5 -.->|7. On Failure| P7
    P7 -.->|8. Exponential Backoff| P6
    P6 -.->|9. Retry| V1 & V2 & V3

    style S2 fill:#fff4cc
    style S3 fill:#fff4cc
    style S4 fill:#fff4cc
    style S5 fill:#fff4cc
    style P1 fill:#cce5ff
    style P2 fill:#cce5ff
    style P3 fill:#cce5ff
    style P4 fill:#cce5ff
    style P5 fill:#cce5ff
    style P6 fill:#cce5ff
    style P7 fill:#cce5ff
    style V1 fill:#99ff99
    style V2 fill:#99ff99
    style V3 fill:#99ff99
Loading

Complete Data Flow Sequence

sequenceDiagram
    participant V as Vendor System
    participant P as Vitaboom Proxy
    participant DB as VendorOrder DB
    participant S as Shopify API
    participant WH as Webhook Queue

    Note over V,S: Order Creation Flow
    V->>+P: POST /api/vendor/humanaut/orders<br/>{lineItems, addresses, ...}
    P->>P: Validate API Key
    P->>P: Validate Request (Joi Schema)
    P->>P: Add "Humanaut Health" tag
    P->>+S: GraphQL: draftOrderCreate
    S-->>-P: Shopify Order Created<br/>{id, name, orderNumber}
    P->>+DB: Store Order Mapping<br/>{vendorId, shopifyOrderId, vendorOrderId}
    DB-->>-P: Stored
    P-->>-V: 201 Created<br/>{success: true, order: {...}}

    Note over V,S: Webhook Flow (Order Fulfilled)
    S->>+P: POST /webhooks/shopify/orders/fulfilled<br/>HMAC-SHA256 Signature
    P->>P: Validate HMAC
    P->>+DB: Lookup Vendor by Shopify Order
    DB-->>-P: Vendor: Humanaut
    P->>+WH: Store Webhook Event<br/>{eventType, payload, orderId}
    WH-->>-P: Event Stored
    P->>P: Transform to Vendor Format<br/>{event, order, shopifyData}
    P->>+V: POST https://humanaut.com/webhooks/vitaboom<br/>X-Vitaboom-Event: orders/fulfilled
    V-->>-P: 200 OK
    P->>WH: Mark as forwarded
    P-->>-S: 200 OK (Acknowledge)

    Note over V,S: Webhook Retry on Failure
    alt Vendor Endpoint Fails
        P->>V: POST webhook
        V-->>P: 500 Error
        P->>WH: Store retry (attempt 1/3)
        P->>P: Wait ~1 second
        P->>V: POST webhook (retry 1)
        V-->>P: 500 Error
        P->>WH: Store retry (attempt 2/3)
        P->>P: Wait ~2 seconds
        P->>V: POST webhook (retry 2)
        V-->>P: 200 OK
        P->>WH: Mark as forwarded
    end
Loading

Comparison: Key Improvements

flowchart LR
    subgraph "Before (Direct)"
        B1[Complex OAuth]
        B2[GraphQL Expertise]
        B3[Rate Limit Logic]
        B4[Manual Retries]
        B5[Data Mapping]
        B6[HMAC Validation]
    end

    subgraph "After (Proxy)"
        A1[Simple API Key]
        A2[REST API]
        A3[Automatic Handling]
        A4[Built-in Retries]
        A5[Standardized Format]
        A6[Handled by Proxy]
    end

    B1 -.->|Simplified| A1
    B2 -.->|Abstracted| A2
    B3 -.->|Managed| A3
    B4 -.->|Automated| A4
    B5 -.->|Unified| A5
    B6 -.->|Centralized| A6

    style B1 fill:#ffcccc
    style B2 fill:#ffcccc
    style B3 fill:#ffcccc
    style B4 fill:#ffcccc
    style B5 fill:#ffcccc
    style B6 fill:#ffcccc
    style A1 fill:#ccffcc
    style A2 fill:#ccffcc
    style A3 fill:#ccffcc
    style A4 fill:#ccffcc
    style A5 fill:#ccffcc
    style A6 fill:#ccffcc
Loading

Benefits Summary

For Vendors

Aspect Before (Direct) After (Proxy)
Integration Time 2-4 weeks 2-3 days
Technical Complexity High (OAuth, GraphQL, HMAC) Low (REST, API Key)
Maintenance Burden Ongoing (API changes) Minimal (proxy handles changes)
Error Handling Manual implementation Automatic retries + monitoring
Security Model Full Shopify store access Scoped to order operations only
Webhook Reliability Vendor must handle retries Proxy handles 3 automatic retries
Data Format Shopify-specific (complex) Vendor-friendly (simplified)
Rate Limiting Vendor must implement Handled by proxy

For Vitaboom

Aspect Before (Direct) After (Proxy)
Vendor Onboarding Manual OAuth setup per vendor Automated API key generation
Order Tracking Scattered across vendor systems Centralized in VendorOrder DB
Error Visibility No visibility Centralized logging + Sentry
Consistency Each vendor implements differently Standardized interface
Security Multiple OAuth apps Single Shopify integration
Scalability Linear complexity per vendor O(1) complexity

Technical Implementation Details

Proxy Components

graph TB
    subgraph "Authentication Layer"
        A1[API Key Middleware]
        A2[Vendor Lookup]
        A3[Scope Validation]
    end

    subgraph "Validation Layer"
        V1[Joi Schema Validator]
        V2[Address Validation]
        V3[Line Item Validation]
        V4[Financial Status Check]
    end

    subgraph "Business Logic Layer"
        B1[Auto-Tagging Service]
        B2[Order Creation Service]
        B3[Fulfillment Service]
        B4[Cancellation Service]
    end

    subgraph "Integration Layer"
        I1[Shopify GraphQL Client]
        I2[Rate Limiter]
        I3[Error Handler]
        I4[Retry Logic]
    end

    subgraph "Persistence Layer"
        P1[(VendorOrder DB)]
        P2[(WebhookEvent DB)]
        P3[(Vendor DB)]
    end

    subgraph "Webhook System"
        W1[Event Processor]
        W2[Vendor Matcher]
        W3[Payload Transformer]
        W4[Forwarder Service]
        W5[Retry Queue]
    end

    A1 --> A2 --> A3
    A3 --> V1 --> V2 & V3 & V4
    V4 --> B1 & B2 & B3 & B4
    B2 --> I1
    I1 --> I2 --> I3 --> I4
    I4 --> P1 & P2 & P3

    P2 --> W1 --> W2 --> W3 --> W4
    W4 -.-> W5
    W5 -.->|Retry| W4

    style A1 fill:#e1f5ff
    style V1 fill:#fff9e1
    style B1 fill:#e8f5e9
    style I1 fill:#f3e5f5
    style P1 fill:#fce4ec
    style W1 fill:#fff3e0
Loading

Database Schema

erDiagram
    VENDOR ||--o{ VENDOR_ORDER : creates
    VENDOR ||--o{ WEBHOOK_EVENT : receives
    VENDOR_ORDER ||--o{ WEBHOOK_EVENT : triggers

    VENDOR {
        uuid id PK
        string slug UK
        string name
        string shopifyTag
        string apiKey
        string webhookUrl
        string webhookOrderConfirmedUrl
        string webhookOrderFulfilledUrl
        string webhookOrderCancelledUrl
        string webhookOrderUpdatedUrl
        jsonb metadata
        boolean isActive
    }

    VENDOR_ORDER {
        uuid id PK
        uuid vendorId FK
        string shopifyOrderId
        string shopifyOrderNumber
        string shopifyOrderName
        string vendorOrderId
        string status
        string financialStatus
        string fulfillmentStatus
        jsonb orderPayload
        jsonb shopifyResponse
        timestamp createdAt
        timestamp updatedAt
    }

    WEBHOOK_EVENT {
        uuid id PK
        uuid orderId FK
        string eventType
        string shopifyOrderId
        string shopifyOrderNumber
        jsonb payload
        boolean processed
        boolean forwardedToVendor
        timestamp vendorForwardedAt
        jsonb vendorResponse
        integer retryCount
        timestamp lastRetryAt
        string errorMessage
        timestamp createdAt
    }
Loading

Security Architecture

flowchart TB
    subgraph "Security Layers"
        direction TB
        S1[API Key Authentication]
        S2[Vendor Scoping]
        S3[Request Validation]
        S4[Rate Limiting]
        S5[HMAC Webhook Validation]
        S6[Error Sanitization]
    end

    subgraph "Threat Mitigation"
        T1[Unauthorized Access ❌]
        T2[Data Tampering ❌]
        T3[Injection Attacks ❌]
        T4[DDoS Attacks ❌]
        T5[Webhook Spoofing ❌]
        T6[Information Leakage ❌]
    end

    S1 --> T1
    S2 --> T1
    S3 --> T2 & T3
    S4 --> T4
    S5 --> T5
    S6 --> T6

    style S1 fill:#c8e6c9
    style S2 fill:#c8e6c9
    style S3 fill:#c8e6c9
    style S4 fill:#c8e6c9
    style S5 fill:#c8e6c9
    style S6 fill:#c8e6c9
    style T1 fill:#ffcdd2
    style T2 fill:#ffcdd2
    style T3 fill:#ffcdd2
    style T4 fill:#ffcdd2
    style T5 fill:#ffcdd2
    style T6 fill:#ffcdd2
Loading

Monitoring & Observability

flowchart LR
    subgraph "System Events"
        E1[API Requests]
        E2[Order Creations]
        E3[Webhook Deliveries]
        E4[Errors]
    end

    subgraph "Logging Layer"
        L1[Console Logs]
        L2[Structured Logging]
    end

    subgraph "Error Tracking"
        ET1[Sentry Integration]
        ET2[Error Context]
        ET3[Stack Traces]
    end

    subgraph "Database Metrics"
        D1[Order Success Rate]
        D2[Webhook Delivery Rate]
        D3[Retry Statistics]
        D4[Vendor Activity]
    end

    E1 & E2 --> L1 & L2
    E3 --> L1 & L2
    E4 --> L1 & L2
    E4 --> ET1 --> ET2 & ET3
    L2 --> D1 & D2 & D3 & D4

    style E1 fill:#e3f2fd
    style E2 fill:#e3f2fd
    style E3 fill:#e3f2fd
    style E4 fill:#ffebee
    style ET1 fill:#fff3e0
    style D1 fill:#f1f8e9
    style D2 fill:#f1f8e9
    style D3 fill:#f1f8e9
    style D4 fill:#f1f8e9
Loading

Future Enhancements

mindmap
  root((Vitaboom Proxy<br/>Evolution))
    Authentication
      Multi-tenant API Keys
      JWT Support
      OAuth 2.0 for Vendors
      IP Whitelisting
    Functionality
      Bulk Order Creation
      Order Search/Filter API
      Product Catalog Sync
      Inventory Management
      Customer Management
    Monitoring
      Real-time Dashboards
      Vendor Analytics
      Performance Metrics
      Cost Tracking
    Integration
      Multi-store Support
      Alternative Platforms
      Custom Fulfillment Services
      ERP Integrations
    Developer Experience
      SDK Libraries
      Postman Collections
      Interactive API Docs
      Sandbox Environment
Loading

Conclusion

The Vitaboom vendor proxy architecture transforms complex Shopify integrations into simple, secure, and maintainable REST API interactions. By centralizing authentication, validation, error handling, and webhook management, the proxy:

  1. Reduces vendor integration time from weeks to days
  2. Eliminates technical complexity (OAuth, GraphQL, HMAC)
  3. Provides automatic reliability (retries, rate limiting)
  4. Centralizes monitoring (Sentry, structured logging)
  5. Enhances security (scoped access, API keys)
  6. Ensures consistency (standardized data format)

This architecture scales efficiently as new vendors are onboarded, with O(1) complexity per vendor rather than linear complexity growth.

Architecture diagrams maintained by Fractal Labs - December 2025

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment