Flexport Supply Chain Integration Architecture

v20260423

flexport-reference-architecture

A comprehensive reference architecture for building robust and scalable supply chain integrations with Flexport's logistics API. It outlines a structured pipeline using Ingest (webhooks/polling), Core (business logic services), and Expose (REST API/Dashboard layers), ensuring reliable data flow, caching, and queueing best practices.

Flexport Logistics Integration Architecture Supply Chain Webhooks API Backend

Get Skill

59 downloads

Overview

Flexport Reference Architecture

Overview

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

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) ┘

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

Key Design Decisions

Decision	Choice	Rationale
Database	PostgreSQL	Structured logistics data, JSONB for flexible fields
Cache	Redis with 5min TTL	Shipment data changes infrequently
Queue	BullMQ	Retry, dead letter, rate limiting built in
API client	Custom fetch wrapper	No official SDK, typed with Zod
Webhook processing	Async via queue	Fast 200 response, process later

Resources

Next Steps

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

Info

Category Development

Name flexport-reference-architecture

Version v20260423

Size 4.86KB

Source jeremylongshore/claude-code-plugins-plus-skills

Updated At 2026-04-28