Architecture Overview

System Architecture

High-Level Architecture

flowchart TB
  subgraph "Frontend Layer"
      Dashboard[Dashboard - Vue 3]
      DevPortal[Developer Portal]
      WC[Web Components]
  end
  
  subgraph "Gateway Layer"
      API[Gateway API - Laravel]
      Auth[OAuth Server]
      Integrations[Integration Engine]
  end
  
  subgraph "Processing Layer"
      Kafka[Message Queue]
      GoService[Go Microservice]
      Workers[Background Workers]
  end
  
  subgraph "Data Layer"
      Postgres[(PostgreSQL)]
      Redis[(Redis Cache)]
  end
  
  subgraph "External Systems"
      Shopify[Shopify]
      Amazon[Amazon]
      WooCommerce[WooCommerce]
      OtherCarts[Other Carts...]
      WMS[WMS]
  end
  
  Dashboard --> API
  DevPortal --> API
  WC --> API
  
  API --> Auth
  API --> Integrations
  API --> Postgres
  API --> Redis
  API --> Kafka
  
  Kafka --> GoService
  GoService --> Workers
  Workers --> API
  
  Integrations <--> Shopify
  Integrations <--> Amazon
  Integrations <--> WooCommerce
  Integrations <--> OtherCarts
  API <--> WMS

Authentication Architecture

Tip

The Gateway uses a Stripe-like authentication model with three session types.

Session Types

Admin Session

Middleware: auth:api

Used by the Dashboard for administrative operations.

Authorization: Bearer {admin_token}

Developer App Session

Middleware: client_credentials

Used by OAuth apps with scoped access.

Authorization: Bearer {app_token}
X-App-Id: {app_id}

WebComponent Session

Middleware: auth.account

Limited access via Intent tokens (10 min TTL).

Authorization: Bearer {intent_token}

Authentication Flow

sequenceDiagram
  participant Dev as Developer
  participant Dash[Dashboard]
  participant API[IONFLOW API]
  participant WC as WebComponent
  participant User as End User
  
  Dev->>Dash: Create OAuth App
  Dash->>API: Register App
  API-->>Dash: Client ID & Secret
  
  Dev->>API: Request Token (client_credentials)
  API-->>Dev: Access Token (scoped)
  
  Dev->>API: Create Account (end-user)
  API-->>Dev: Account ID
  
  Dev->>API: Generate Intent Token
  API-->>Dev: Intent Token (10 min TTL)
  
  Dev->>WC: Initialize with Intent Token
  WC->>API: Operate on Account
  User->>WC: Interact
  WC->>API: API calls with Intent Token

Data Flow

Order Processing Flow

sequenceDiagram
  participant Cart as E-commerce Cart
  participant GW as Gateway
  participant KF as Kafka
  participant GO as Go Service
  participant WMS[WMS]
  
  Cart->>GW: Webhook: New Order
  GW->>GW: Validate & Map Order
  GW->>KF: Publish: order.created
  GW-->>Cart: 200 OK
  
  KF->>GO: Consume: order.created
  GO->>GO: Process Order
  GO->>WMS: Create Order in WMS
  WMS-->>GO: Order Created
  GO->>KF: Publish: order.processed
  
  KF->>GW: Consume: order.processed
  GW->>Cart: Update Order Status

Technology Decisions

Decision	Choice	Rationale
API Framework	Laravel	Ecosystem, OAuth support, rapid development
Frontend	Vue 3	Composition API, TypeScript support, team expertise
Microservice	Go	Performance, concurrency, small binary size
Message Queue	Kafka	Throughput, durability, replay capability
Database	PostgreSQL	JSONB support, reliability, extensions
Cache	Redis	Speed, pub/sub, session storage

Continue to Tech Stack →