ReddRadar
Agent skill
flexport-reference-architecture
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".
Install this agent skill to your Project
npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/flexport-pack/skills/flexport-reference-architecture
SKILL.md
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.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
jeremylongshore/claude-code-plugins-plus-skills
dockerfile-generator
Dockerfile Generator - Auto-activating skill for DevOps Basics. Triggers on: dockerfile generator, dockerfile generator Part of the DevOps Basics skill category.
jeremylongshore/claude-code-plugins-plus-skills
branch-naming-helper
Branch Naming Helper - Auto-activating skill for DevOps Basics. Triggers on: branch naming helper, branch naming helper Part of the DevOps Basics skill category.
jeremylongshore/claude-code-plugins-plus-skills
readme-generator
Readme Generator - Auto-activating skill for DevOps Basics. Triggers on: readme generator, readme generator Part of the DevOps Basics skill category.
jeremylongshore/claude-code-plugins-plus-skills
makefile-generator
Makefile Generator - Auto-activating skill for DevOps Basics. Triggers on: makefile generator, makefile generator Part of the DevOps Basics skill category.
jeremylongshore/claude-code-plugins-plus-skills
gitignore-generator
Gitignore Generator - Auto-activating skill for DevOps Basics. Triggers on: gitignore generator, gitignore generator Part of the DevOps Basics skill category.
jeremylongshore/claude-code-plugins-plus-skills
pre-commit-hook-setup
Pre Commit Hook Setup - Auto-activating skill for DevOps Basics. Triggers on: pre commit hook setup, pre commit hook setup Part of the DevOps Basics skill category.
Didn't find tool you were looking for?