Skip to content

OpenSteward architecture

A tiered set of mermaid diagrams that document the entire repo. Read top-to-bottom, drill down by clicking nodes.

  • First time here? Read the end-user journey →. It walks through one operator’s lived experience from git clone to working integrations.
  • Want the technical map? The diagram below is the entry point. Click any service node to drill into the subsystem that owns it.
  • Writing a new adapter? Skip to the adapter walkthrough → — Fortnox dissected file-by-file with rationale, plus a table of what varies across adapters.

Diagram: Chart 1 — Overview Diagram: Chart 1 — Overview
Layer Purpose Talks to
UX (admin) EJS-rendered admin frontend, session cookie auth admin-api over JWT
Control plane (admin-api) Single source of truth for users, audit, notifications, company info, adapter management integration-server over X-Admin-Secret
Unified service (integration-server) Single backend mapping every vertical (accounting, crm, ecommerce, logistics, payments, docsign, projects, customer-support, inventory) to the canonical REST API. Also serves the developer-facing /v1/customers and /v1/connections endpoints under tenant-scoped Bearer auth, fires HMAC-signed outbound customer.* / connect_link.* / resource.* webhook events with at-least-once retry, and enforces per-key scopes + rate limits. Owns the encrypted SQLite credential store and (when dataStore.mode != passthrough) a sibling resources.db cache populated by per-vertical SyncWorkers. External platforms over OAuth / API key; developer backends over Bearer auth (osk_ API keys, or OIDC bearer tokens from a registered issuer)
Side-cars Webhook Gateway (inbound webhook receiver with retries + DLQ), Docs Server (Swagger UI on the unified spec), opt-in Redis (docker compose --profile scale) for shared rate-limit budget across replicas integration-server
External platforms Fortnox, QuickBooks, EasyPost, DHL, Shippo, Shopify, Stripe, DocuSign, Asana, Zendesk, Cin7, … (1,548 adapters across 9 verticals); plus the customer-supplied webhook URLs that receive outbound customer.* / connect_link.* events integration-server

Tier 2 — Subsystem views (start here for breadth)

Section titled “Tier 2 — Subsystem views (start here for breadth)”
# File What it covers
2 end-user-journey.md The full operator narrative, from git clone to day-2 ops
3 services.md All 5 services plus the opt-in compose profiles (Redis, Postgres + Superset, local HTTPS, dev SSO), ports, depends_on, databases, the sync scheduler
4 runtime-flows.md API request • sync job • OAuth connect • webhook ingestion (4 sequence diagrams)
5 persistence.md ERD across the four databases + the resources-cache runbook
6 build-and-workspace.md pnpm workspace deps + Dockerfile build args
7 testing.md The 3-layer test taxonomy (transform unit · journeys · CI guards) + how CI runs

Tier 3 — Deep dives (drill in for depth)

Section titled “Tier 3 — Deep dives (drill in for depth)”
# File What it covers
8 vertical-internals.md Inside one vertical (build chain + middleware chain)
9 adapter-lifecycle.md Adapter enable / disable / configure flow
10 setup-wizard.md First-run guard + 8-step wizard, and how it resumes where setup stands
11 auth-and-tenancy.md Operator vs admin user vs developer key vs tenant vs end-user vs connection
12 admin-page-map.md Every admin frontend route grouped by access level (for how to use each page, see the admin console guide)
13 webhook-delivery.md Inbound webhook gateway delivery lifecycle. For outbound customer/connect-link events see ../dev-api.md §8
14 adapter-walkthrough.md Fortnox adapter file-by-file — the worked example for scaffolding a new adapter
— connect-links.md Hosted OAuth links — mint modes, session lifecycle, templates, per-link scope override
— sso-and-identity-providers.md Corporate SSO (SAML / OIDC / LDAP) + SCIM against the admin-user layer
— permissions-and-roles.md Permission catalog, custom roles, per-user tenant scope and the escalation guards
— data-access.md Data viewer and native dashboards — admin UI → admin-api → integration-server, the scope header, masking, metrics and audit
— ../dev-api.md Developer-facing walkthrough — Bearer keys, scopes, customers, connect links, vertical APIs, outbound webhooks

  • Source of truth. When the codebase changes, the corresponding chart should be updated in the same PR.
  • No build step. GitHub renders mermaid natively in .md files.
  • Single-tier rule. Any chart that exceeds ~30 nodes should split into a Tier 3 sub-chart and be replaced with a node-group in the parent.