Implement Flexport reference architecture for supply chain integrations with best-practice project layout, service boundaries, and data flow. Trigger: "flexport architecture", "flexport project structure", "flexport system design".
Production reference architecture for Flexport logistics integrations. Three core services: Ingest (webhooks + polling), Core (business logic), and Expose (API + dashboard).
┌──────────────────────────────────────────────────────┐
│ 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) │
└───────────────────────────────────────────────────────┘
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
Flexport API ──webhook──> Ingest ──queue──> Core ──cache──> Expose
│ │
└── DB (Postgres) ┘
| 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 |
For multi-environment setup, see flexport-multi-env-setup.