Flexport Reference Architecture

Overview

Production reference architecture for Flexport logistics integrations. Three core services: Ingest (webhooks + polling), Core (business logic), and Expose (API + dashboard).

Prerequisites

• A data-flow inventory naming system owners, approved destinations, retention rules, endpoint scopes, and trust boundaries.
• Separate identities for ingress, workers, storage, dashboards, and integrations; use synthetic fixtures for every architecture test.

Instructions

1. Verify webhook signatures at ingress and enqueue opaque event IDs for idempotent processing.
2. Apply field allowlists and access checks before storage, dashboard exposure, or downstream notifications.
3. Define cache freshness, rate limits, retry bounds, audit logging, and a disable/rollback switch per service boundary.
4. Promote architecture changes through staging with fictional data and review aggregate canary evidence before production.

Output

Maintain an architecture decision record showing trust boundaries, source-of-truth assignments, data destinations, access/retention controls, owners, and rollback mechanisms. Do not include shipments, documents, commercial terms, or secrets.

Error Handling

• Quarantine events with unknown schemas, destinations, or permissions rather than forwarding them.
• Isolate a failed service boundary, disable unsafe consumers, and preserve only redacted evidence.
• Restore the prior routing/configuration before replaying queued work after an incident.

Examples

Route a fictional milestone through ingress, queue, core, and a staging dashboard. Confirm duplicate suppression, denied access for an unapproved consumer, and a controlled rollback that leaves no shipment payload in logs.

Architecture

┌──────────────────────────────────────────────────────┐
│                    Your Application                   │
├──────────────┬──────────────────┬─────────────────────┤
│  Ingest      │  Core            │  Expose             │
│              │                  │                     │
│  Webhook     │  Shipment        │  REST API           │
│  Receiver    │  Service         │  (your clients)     │
│              │                  │                     │
│  Scheduled   │  Product         │  Dashboard          │
│  Sync        │  Service         │  (Next.js/Astro)    │
│              │                  │                     │
│  Event       │  Invoice         │  Notifications      │
│  Queue       │  Service         │  (email/slack)      │
├──────────────┴──────────────────┴─────────────────────┤
│  Infrastructure: Cache (Redis) │ DB (Postgres) │ Queue │
├───────────────────────────────────────────────────────┤
│  Flexport API v2 (https://api.flexport.com)           │
└───────────────────────────────────────────────────────┘

Project Layout

flexport-integration/
├── src/
│   ├── flexport/
│   │   ├── client.ts           # Singleton API client
│   │   ├── types.ts            # Zod schemas for API responses
│   │   └── webhooks.ts         # Webhook signature + routing
│   ├── services/
│   │   ├── shipment.service.ts # Shipment CRUD + tracking
│   │   ├── product.service.ts  # Product catalog sync
│   │   ├── invoice.service.ts  # Commercial + freight invoices
│   │   └── booking.service.ts  # Booking creation + amendments
│   ├── jobs/
│   │   ├── sync-shipments.ts   # Scheduled full sync (hourly)
│   │   └── cache-warmup.ts     # Pre-populate caches on deploy
│   ├── api/
│   │   ├── routes.ts           # Express/Fastify routes
│   │   └── middleware.ts       # Auth, logging, error handling
│   └── config/
│       ├── flexport.ts         # API config per environment
│       └── cache.ts            # TTL settings per data type
├── tests/
│   ├── unit/                   # Mocked API tests
│   └── integration/            # Live API tests (CI only)
├── .env.example
└── docker-compose.yml          # Redis + Postgres for local dev

Data Flow

Flexport API ──webhook──> Ingest ──queue──> Core ──cache──> Expose
                                    │                │
                                    └── DB (Postgres) ┘

1. Ingest: Webhook receiver validates signatures, enqueues events
2. Core: Services process events, sync with Flexport API, update DB
3. Expose: API/dashboard reads from DB + cache, never directly from Flexport
4. Scheduled jobs: Hourly full sync catches any missed webhooks

Key Design Decisions

Resources

• Flexport Developer Portal
• Flexport API Reference

Next Steps

For multi-environment setup, see flexport-multi-env-setup.