# 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

- **First time here?** Read the [end-user journey →](https://docs.opensteward.dev/architecture/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 →](https://docs.opensteward.dev/architecture/adapter-walkthrough/) — Fortnox dissected file-by-file with rationale, plus a table of what varies across adapters.

---

## Chart 1 — Overview

```mermaid
flowchart LR
  classDef ux fill:#dbeafe,stroke:#1e40af,color:#1e3a8a
  classDef ctrl fill:#fef3c7,stroke:#a16207,color:#713f12
  classDef vert fill:#dcfce7,stroke:#15803d,color:#14532d
  classDef ext fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d
  classDef side fill:#e9d5ff,stroke:#7e22ce,color:#581c87

  Op([Operator])
  Dev([Developer backend])
  EndUser([External customer<br/>opens Connect Link])

  subgraph UX["UX layer"]
    Admin[":3000<br/>admin (UI)"]:::ux
  end

  subgraph Ctrl["Control plane"]
    AdminApi[":3001<br/>admin-api"]:::ctrl
  end

  subgraph Unified["Unified service"]
    IS[":3010<br/>integration-server<br/>9 verticals · 1,548 adapters<br/>/v1/customers · /v1/connections · /v1/&#123;vertical&#125;/* · /auth/*"]:::vert
  end

  subgraph Side["Side-cars"]
    WebhookGw[":3004<br/>webhook-gateway"]:::side
    Docs[":3003<br/>docs-server"]:::side
    Redis["redis:7-alpine<br/>(opt-in, --profile scale)"]:::side
  end

  subgraph Ext["External platforms"]
    Platform[Fortnox / Nutshell / Shopify / EasyPost / Stripe / DocuSign / Asana / Zendesk / Cin7 / 1536 more]:::ext
    Receiver[Customer's webhook URL]:::ext
  end

  Op -->|browser| Admin
  Dev -->|Bearer: osk_ key / OIDC JWT| IS
  EndUser -.->|/connect/&lt;token&gt;| IS

  Admin -->|JWT| AdminApi
  AdminApi -->|X-Admin-Secret| IS

  Platform -.->|inbound webhook| WebhookGw
  WebhookGw -->|forwards| IS

  IS -->|OAuth/API| Platform
  IS -.->|HMAC POST retry queue| Receiver
  IS <-->|opt-in REDIS_URL| Redis

  Docs -.->|reads openapi.json| IS

  click Admin href "./admin-page-map.md" "Admin frontend page map"
  click AdminApi href "./services.md" "Service topology"
  click IS href "./vertical-internals.md" "Inside one vertical"
  click WebhookGw href "./webhook-delivery.md" "Webhook delivery state machine"
  click Docs href "./services.md" "Service topology"
```

### 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

### Tier 2 — Subsystem views (start here for breadth)

| # | File | What it covers |
|---|---|---|
| 2 | [end-user-journey.md](https://docs.opensteward.dev/architecture/end-user-journey/) | The full operator narrative, from `git clone` to day-2 ops |
| 3 | [services.md](https://docs.opensteward.dev/architecture/services/) | 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](https://docs.opensteward.dev/architecture/runtime-flows/) | API request • sync job • OAuth connect • webhook ingestion (4 sequence diagrams) |
| 5 | [persistence.md](https://docs.opensteward.dev/architecture/persistence/) | ERD across the four databases + the resources-cache runbook |
| 6 | [build-and-workspace.md](https://docs.opensteward.dev/architecture/build-and-workspace/) | pnpm workspace deps + Dockerfile build args |
| 7 | [testing.md](https://docs.opensteward.dev/architecture/testing/) | The 3-layer test taxonomy (transform unit · journeys · CI guards) + how CI runs |

### Tier 3 — Deep dives (drill in for depth)

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

---

## 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 `.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.
