OpenSteward architecture
A tiered set of mermaid diagrams that document the entire repo. Read top-to-bottom, drill down by clicking nodes.
Where to start
Section titled “Where to start”- First time here? Read the end-user journey →. It walks through one operator’s lived experience from
git cloneto 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.
Chart 1 — Overview
Section titled “Chart 1 — Overview”Layers at a glance
Section titled “Layers at a glance”| 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 |
Chart index
Section titled “Chart index”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 |
Maintenance
Section titled “Maintenance”- 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
.mdfiles. - 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.
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.