thedixitjain 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.
Source: jeremylongshore/claude-code-plugins-plus-skills → skills/.curated/flexport-reference-architecture/SKILL.md
Also appears in: jeremylongshore/claude-code-plugins-plus-skills/plugins/saas-packs/flexport-pack/skills/flexport-reference-architecture/SKILL.md