About

Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/flexport-reference-architecture/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill flexport-reference-architecture. Copyright stays with the author (MIT).

Flexport Reference Architecture

Name: flexport-reference-architecture
Author: jeremylongshore

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

Verify webhook signatures at ingress and enqueue opaque event IDs for idempotent processing.
Apply field allowlists and access checks before storage, dashboard exposure, or downstream notifications.
Define cache freshness, rate limits, retry bounds, audit logging, and a disable/rollback switch per service boundary.
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) ┘

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.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/jeremylongshore-tons-of-skills-marketplace-flexport-refe-08b141/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

jeremylongshore-tons-of-skills-marketplace-flexport-refe-08b141.ocm.jsonjson

{
  "ocm": "1",
  "id": "jeremylongshore-tons-of-skills-marketplace-flexport-refe-08b141",
  "kind": "skill",
  "name": "flexport-reference-architecture",
  "description": "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\".",
  "publisher": "jeremylongshore",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "saas",
      "logistics",
      "flexport",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "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\"."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/jeremylongshore/tons-of-skills-marketplace",
      "path": "skills/.curated/flexport-reference-architecture/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/jeremylongshore/tons-of-skills-marketplace/blob/HEAD/skills/.curated/flexport-reference-architecture/SKILL.md",
      "key": "jeremylongshore/tons-of-skills-marketplace/skills/.curated/flexport-reference-architecture/SKILL.md"
    },
    "compatibility": "Designed for Claude Code",
    "allowed_tools": [
      "Read,",
      "Write,",
      "Edit"
    ],
    "license": "MIT"
  },
  "instructions": "# Flexport Reference Architecture\n\n## Overview\n\nProduction reference architecture for Flexport logistics integrations. Three core services: Ingest (webhooks + polling), Core (business logic), and Expose (API + dashboard).\n\n## Prerequisites\n\n- A data-flow inventory naming system owners, approved destinations, retention rules, endpoint scopes, and trust boundaries.\n- Separate identities for ingress, workers, storage, dashboards, and integrations; use synthetic fixtures for every architecture test.\n\n## Instructions\n\n1. Verify webhook signatures at ingress and enqueue opaque event IDs for idempote",
  "cost": {
    "context_tokens": 1284
  }
}

Fetch it by URL: GET /api/v1/registry/jeremylongshore-tons-of-skills-marketplace-flexport-refe-08b141/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.