Inside one vertical
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”Resource request middleware chain
Section titled “Resource request middleware chain”When a request hits a resource route like GET /v1/logistics/shipments?connection_id=…, this is the chain it walks:
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.
File map (logistics vertical)
Section titled “File map (logistics vertical)”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 filesThe 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:
buildServerconstructs oneSyncWorker<TAdapter>per vertical (imported from@opensteward/shared) whendataStore.mode != passthrough; inpassthroughnone are built and the vertical plugins are a thin live proxy. The vertical-specific bits aresync/listable-resources.ts(which adapter methods to walk) +sync/token-refresher.ts(per-vertical adapter type). The shared worker drives polling, pagination, progress tracking, andresource.syncedevent emission. Seeruntime-flows.md§4d for the lifecycle. - Webhook handlers: every vertical’s
WEBHOOK_HANDLERSmap 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-verifiersfails when an adapter ships awebhook.tsthat 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.
See also
Section titled “See also”- services.md — how this vertical fits into the wider topology
- adapter-lifecycle.md — the enable/disable flow into this registry
- runtime-flows.md — sequence diagrams for an actual request walking through this stack
opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.