Bridge Payments Docs

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     │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │                  │                  │              │
│         │                  │                  │              │
│  ┌──────▼──────────────────▼──────────────────▼───────┐    │
│  │     Hybrid Cache Layer (Redis optional + LRU)       │    │
│  └──────┬──────────────────┬──────────────────┬───────┘    │
│         │                  │                  │              │
│  ┌──────▼──────┐    ┌──────▼──────┐    ┌─────▼──────┐     │
│  │  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: Fast, consistent caching across instances (especially when Redis is enabled).

Technology (hybrid SmartCache):

  • Optional Redis: When REDIS_URL is set and reachable, Redis is the primary store for eligible caches (shared across processes and horizontally scaled instances).
  • LRU fallback: In-process LRU caches are always available—either as the sole backend when Redis is not configured, or as an automatic fallback if Redis is unavailable.

Cached Data (examples):

  • Guest token validations (1 hour TTL)
  • User session validations (5 minutes TTL)
  • Payment method lists (5 minutes TTL)
  • Customer data (5 minutes TTL)
  • Organization membership and related auth context (where SmartCache is wired)

Benefits:

  • Reduced database queries
  • Faster response times
  • Lower Flowless API calls
  • Improved scalability—Redis keeps cache coherent across multiple Bridge Payments instances; LRU mode remains fully supported for single-node or dev setups

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 ​

  • SmartCache / LRU: Optional Redis-backed cache with in-memory LRU emergency fallback (REDIS_URL optional)
  • 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
  • Hybrid cache: Per-instance LRU always; optional Redis for shared cache across instances
  • Load balancer ready: Can run multiple instances

Performance Optimizations ​

  • Bun runtime: 3x faster than Node.js
  • Kysely ORM: Optimized SQL queries
  • Redis or LRU caching: Reduces database load and provider/auth fan-out
  • 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

Modules, plugins, and hosted UI ​

Beyond the JSON API in this diagram:

  • Module Hub installs SQL-backed modules (native manifests under modules/ or legacy plugins under database/plugins/). Admin routes: /bridge-payment/admin/plugins/.... See Module Hub & extensions.
  • Bridge Pages (PAGES_ENABLED) serves checkout/billing HTML under /bridge-payment/pages/....
  • Bridge Embeds (EMBED_ENABLED) serves widget routes under /bridge-payment/embed/....
  • Optional domains (projects, memberships, invoices/receipts, etc.) are gated by their own feature flags—see Environment Setup and Module Hub & extensions.

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 ​