Skip to content

Inside one vertical

← back to overview

A flowchart of one vertical’s internal structure. Logistics is the canonical example (320 adapters), but the architecture is identical across all nine verticals (accounting, crm, ecommerce, logistics, payments, docsign, projects, customer-support, inventory).


Chart 8 — Logistics service boot + request lifecycle

Section titled “Chart 8 — Logistics service boot + request lifecycle”
Diagram: Chart 8 — Logistics service boot + request lifecycle Diagram: Chart 8 — Logistics service boot + request lifecycle

When a request hits a resource route like GET /v1/logistics/shipments?connection_id=…, this is the chain it walks:

Diagram: Resource request middleware chain Diagram: Resource request middleware chain

cachedList and cachedGet are short-circuited to live-only when request.cacheMode === 'passthrough' (set per-plugin from dataStore.mode). POST / PATCH / DELETE skip the cache-read decision but call writeThrough / cachedDelete after the upstream succeeds.


Each vertical lives under apps/integration-server/src/verticals/<name>/. Auth, connections, health, platforms, and admin/adapters routes are shared (control plane in @opensteward/shared); only the resource routers + adapter implementations are per-vertical.

apps/integration-server/
├── src/
│ ├── index.ts # entry — loadConfig + buildServer + listen
│ ├── config.ts # YAML loader, defaults, env overrides
│ ├── server.ts # buildServer — wires control plane + every vertical
│ └── verticals/
│ └── logistics/
│ ├── index.ts # buildLogisticsRegistry + createLogisticsPlugin
│ ├── adapter/
│ │ ├── interface.ts # LogisticsAdapter type
│ │ ├── registry.ts # shared AdapterRegistry, typed for LogisticsAdapter
│ │ └── factories.ts # ADAPTER_FACTORIES — 320 entries
│ ├── router/
│ │ ├── shipments.ts # /v1/logistics/shipments
│ │ ├── orders.ts # /v1/logistics/orders
│ │ ├── rates.ts # /v1/logistics/rates
│ │ ├── labels.ts # /v1/logistics/labels
│ │ ├── manifests.ts # /v1/logistics/manifests
│ │ ├── trackingevents.ts # /v1/logistics/trackingevents
│ │ ├── carriers.ts # /v1/logistics/carriers
│ │ └── warehouses.ts # /v1/logistics/warehouses
│ ├── schema/ # canonical Zod schemas (vertical-wide)
│ ├── platforms/metadata.ts # platform catalog (320 entries)
│ ├── sync/ # listable-resources.ts + token-refresher.ts
│ ├── webhook.ts # re-exports the shared HMAC verify helpers
│ ├── webhooks.ts # WEBHOOK_HANDLERS map — generated, 17 for logistics
│ ├── openapi.ts # buildSpec() — vertical's slice of the unified spec
│ └── adapters/ # 320 adapter implementations + a shared/ helpers dir
│ ├── easypost/
│ │ ├── index.ts # EasyPostAdapter implements LogisticsAdapter
│ │ ├── auth.ts # buildAuthUrl, exchangeCode, refreshCredentials
│ │ ├── client.ts # axios wrapper for upstream calls
│ │ └── transform/ # raw response → canonical schema
│ ├── fedex/ … # 318 more in the same shape
│ └── …
└── tests/verticals/logistics/ # ~770 unit-test files

The other eight verticals follow the same shape under src/verticals/<name>/. Differences:

  • Adapter counts: accounting 281, crm 152, ecommerce 176, logistics 320, payments 159, docsign 116, projects 116, customer-support 105, inventory 123 — 1,548 in total.
  • Sync worker: buildServer constructs one SyncWorker<TAdapter> per vertical (imported from @opensteward/shared) when dataStore.mode != passthrough; in passthrough none are built and the vertical plugins are a thin live proxy. The vertical-specific bits are sync/listable-resources.ts (which adapter methods to walk) + sync/token-refresher.ts (per-vertical adapter type). The shared worker drives polling, pagination, progress tracking, and resource.synced event emission. See runtime-flows.md §4d for the lifecycle.
  • Webhook handlers: every vertical’s WEBHOOK_HANDLERS map is populated, but coverage is uneven — crm and payments wire 122 each, ecommerce 86, docsign 71, projects 53, customer-support 49, inventory 41, and accounting and logistics 17 each. check:webhook-verifiers fails when an adapter ships a webhook.ts that isn’t in its vertical’s map — but it only scans five of the nine verticals (accounting, crm, ecommerce, logistics, payments), so docsign, projects, customer-support and inventory are unguarded.
  • Resource routers vary per vertical — see each vertical’s router/ directory.