Bridge Payments

Appearance

Architecture ​

Bridge Payments is built on a modern, scalable architecture designed for high performance and reliability.

System Overview ​

┌─────────────────────────────────────────────────────────────┐
│                     Client Applications                      │
│         (React, Next.js, React Native, Mobile Apps)         │
└────────────────────────┬────────────────────────────────────┘
                         │
                         │ HTTPS/REST API
                         │
┌────────────────────────▼────────────────────────────────────┐
│                    Bridge Payments API                       │
│                    (Hono + Bun Runtime)                      │
├──────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Auth Bridge  │  │   Payment    │  │   Webhook    │      │
│  │  Validator   │  │   Engine     │  │   System     │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │                  │                  │              │
│         │                  │                  │              │
│  ┌──────▼──────────────────▼──────────────────▼───────┐    │
│  │              LRU Cache Layer                        │    │
│  └──────┬──────────────────┬──────────────────┬───────┘    │
│         │                  │                  │              │
│  ┌──────▼──────┐    ┌──────▼──────┐    ┌─────▼──────┐     │
│  │  Provider   │    │  Database   │    │  External  │     │
│  │  Adapters   │    │   Layer     │    │  Webhooks  │     │
│  └──────┬──────┘    └──────┬──────┘    └─────┬──────┘     │
└─────────┼──────────────────┼──────────────────┼────────────┘
          │                  │                  │
          │                  │                  │
    ┌─────▼─────┐      ┌─────▼─────┐     ┌─────▼─────┐
    │  Stripe   │      │PostgreSQL │     │  Discord  │
    │  PayPal   │      │   MySQL   │     │   Slack   │
    │Authorize  │      │  SQLite   │     │Custom APIs│
    └───────────┘      └───────────┘     └───────────┘

Core Components ​

1. Authentication Bridge ​

Purpose: Validates user sessions with Flowless backend

Features:

  • Session validation with Flowless API
  • Token-based authentication
  • Guest token validation and caching
  • Automatic session refresh
  • Rate limiting

Flow:

Client Request → Extract Session ID → Validate with Flowless → Cache Result → Continue

2. Payment Processing Engine ​

Purpose: Handles payment intent creation, confirmation, and status management

Features:

  • Payment intent lifecycle management
  • Multi-provider support (Stripe, PayPal, Authorize.net)
  • Client secret generation and cleanup
  • Payment status synchronization
  • Automatic retry logic

Payment Flow:

Create Intent → Generate Client Secret → Frontend Confirmation → Sync Status → Update Database

3. Provider Adapters ​

Purpose: Abstract payment provider implementations

Supported Providers:

  • Stripe: Credit cards, Apple Pay, Google Pay, 3D Secure
  • PayPal: PayPal accounts, Venmo, credit cards
  • Authorize.net: Credit cards, bank accounts

Adapter Pattern:

typescript
interface PaymentProvider {
  createPaymentIntent(data: PaymentIntentData): Promise<ProviderIntent>;
  confirmPayment(intentId: string): Promise<ProviderPayment>;
  syncPaymentStatus(paymentId: string): Promise<PaymentStatus>;
  createCustomer(data: CustomerData): Promise<ProviderCustomer>;
  createPaymentMethod(data: PaymentMethodData): Promise<ProviderPaymentMethod>;
}

4. Database Layer ​

Purpose: Multi-database support with type-safe queries

Technology: Kysely ORM

Supported Databases:

  • PostgreSQL
  • MySQL
  • SQLite
  • LibSQL (Turso)
  • Neon
  • PlanetScale

Schema:

  • provider_payments - Payment transactions
  • provider_payment_methods - Saved payment methods
  • provider_customers - Customer information
  • provider_addresses - Billing addresses
  • provider_subscriptions - Recurring subscriptions
  • provider_webhooks - Webhook event log

5. Webhook System ​

Purpose: Process provider webhooks and send external notifications

Provider Webhooks:

  • Stripe webhook signature validation
  • PayPal webhook signature validation
  • Automatic event processing
  • Database updates

External Webhooks:

  • Event filtering and routing
  • Signature generation
  • Retry logic with exponential backoff
  • Multiple endpoint support

6. Cache Layer ​

Purpose: High-performance in-memory caching

Technology: LRU Cache

Cached Data:

  • Guest token validations (1 hour TTL)
  • User session validations (5 minutes TTL)
  • Payment method lists (5 minutes TTL)
  • Customer data (5 minutes TTL)

Benefits:

  • Reduced database queries
  • Faster response times
  • Lower Flowless API calls
  • Improved scalability

Technology Stack ​

Runtime & Framework ​

  • Bun: High-performance JavaScript runtime (3x faster than Node.js)
  • Hono: Lightweight web framework (optimized for edge computing)

Database ​

  • Kysely: Type-safe SQL query builder
  • Multi-database support: PostgreSQL, MySQL, SQLite, LibSQL, Neon, PlanetScale

Validation ​

  • Zod: TypeScript-first schema validation
  • Runtime type checking: Ensures data integrity

Payment SDKs ​

  • stripe: Official Stripe Node.js SDK
  • @paypal/sdk-client: Official PayPal SDK
  • authorizenet: Official Authorize.net SDK

Utilities ​

  • LRU Cache: In-memory caching
  • Croner: Cron job scheduling (client secret cleanup)

Security Architecture ​

Authentication Flow ​

1. Client sends request with X-Session-ID header
2. Bridge Payments validates session with Flowless
3. Flowless returns user data or error
4. Bridge Payments caches validation result
5. Request proceeds with user context

Client Secret Management ​

1. Payment intent created → Client secret generated
2. Client secret sent to frontend
3. Frontend confirms payment with provider
4. Client secret automatically deleted after 24 hours
5. Cron job cleans up expired secrets

Webhook Security ​

1. Provider sends webhook with signature
2. Bridge Payments validates signature
3. Event processed and database updated
4. External webhooks triggered with new signature
5. Retry logic for failed deliveries

Scalability ​

Horizontal Scaling ​

Bridge Payments is designed to scale horizontally:

  • Stateless architecture: No server-side sessions
  • Database connection pooling: Efficient database usage
  • LRU cache: In-memory caching per instance
  • Load balancer ready: Can run multiple instances

Performance Optimizations ​

  • Bun runtime: 3x faster than Node.js
  • Kysely ORM: Optimized SQL queries
  • LRU cache: Reduces database load
  • Async operations: Non-blocking I/O
  • Connection pooling: Reuses database connections

Database Optimization ​

  • Indexed columns: Fast lookups on user_id, customer_id, provider_payment_id
  • Composite indexes: Optimized for common queries
  • Partitioning ready: Can partition by date for large datasets

Deployment Architecture ​

Pubflow Platform Deployment ​

Pubflow Dashboard → Create Instance → Configure Providers → Deploy
                                                              ↓
                                                    ┌─────────────────┐
                                                    │ Bridge Payments │
                                                    │    Instance     │
                                                    └─────────────────┘
                                                              ↓
                                                    ┌─────────────────┐
                                                    │    Database     │
                                                    │   (Managed)     │
                                                    └─────────────────┘

Environment Configuration ​

All configuration managed through Pubflow dashboard:

  • Payment provider credentials
  • Database connection
  • Flowless integration
  • External webhooks
  • Feature flags

Monitoring & Observability ​

Logging ​

  • Structured logging: JSON format for easy parsing
  • Log levels: DEBUG, INFO, WARN, ERROR
  • Request logging: All API requests logged
  • Error tracking: Detailed error information

Metrics ​

  • Payment success rate: Track successful vs failed payments
  • Response times: Monitor API performance
  • Cache hit rate: Measure cache effectiveness
  • Webhook delivery rate: Track webhook success

Next Steps ​