Documentation
Generated reference for the unified integration-server API plus
hand-maintained architecture diagrams. The nine verticals (accounting,
crm, ecommerce, logistics, payments, docsign, projects, customer-support,
inventory) live behind one spec — every doc artifact covers the full surface.
Deploying to Kubernetes? See the root README’s cloud section and the chart guide at
deploy/helm/opensteward/README.md(per-cloud overlays, reference IaC, and marketplace artifacts all live underdeploy/).
Structure
Section titled “Structure”docs/ admin/ — the admin console guide, page by page openapi/ — unified OpenAPI 3.1 spec (json + yaml) platforms/ — flat catalog of every platform across every vertical postman/ — Postman collections (unified + admin-api) + local/production/sandbox environments environment/ — env var documentation api-reference/ — markdown Unified API reference rendered from the spec architecture/ — hand-maintained mermaid diagrams (services, flows, …) security/ — threat model, hardening guide, and operator checklist deployment/ — custom-domain + TLS recipes, SSO and OAuth setup, Postgres analytics, Superset, backup/restore, upgrading, key rotation integrate/ — per-platform integration walkthroughs operations/ — generated CLI reference + hand-maintained ops runbooks sdk/ — @opensteward/sdk getting-started guide business-cases/ — regulatory / commercial framing assets/ — screenshots and images referenced from the guidesTop-level pages: dev-api.md (the Developer Guide),
mcp.md (AI agents), why-opensteward.md,
and GLOSSARY.md (canonical term definitions).
| Type | File |
|---|---|
| Admin console guide | admin/README.md — every page of the admin console: who can use it, what it does, with screenshots |
| OpenAPI spec | openapi.json, openapi.yaml |
| Platforms catalog | platforms.md |
| Postman | collection, local env, prod env, sandbox env |
| Environment vars | environment-variables.md |
| Unified API | api-reference.md |
| Architecture diagrams | architecture/README.md |
| Security guide | security/README.md |
| Data classification & masking | security/data-classification.md — field classes, masks, and the check:field-classification guard |
| Data viewer & dashboards | architecture/data-access.md — browsing, reveal, export and native dashboards; the scope header and trust boundaries |
| Permissions, roles & tenant scope | architecture/permissions-and-roles.md — the permission catalog, custom roles, per-user and IdP-driven tenant scope, escalation guards |
| Destinations (warehouse / lake exports) | integrate/destinations.md — Parquet on S3/GCS/Azure, Postgres, Snowflake, BigQuery, Databricks; masking, tombstones, at-least-once delivery |
| Read-only SQL access (BI tools) | integrate/sql-access.md — views, columns, masking, scope; setup in deployment/postgres-analytics.md |
| Embedded Superset dashboards | deployment/superset.md — optional, Postgres only: guest tokens with tenant row-level security over the masked views; compose analytics profile and Helm |
| CLI reference | operations/cli.md |
| Rehearsing admin SSO locally | operations/sso-testing.md — mock IdP, compose bridge, personas |
| Local HTTPS for OAuth callbacks | operations/local-https.md — Caddy https profile for providers that refuse http:// redirect URIs |
| SSO setup (admin console) | deployment/sso-setup.md |
| OIDC setup (developer API) | deployment/oauth-clients-setup.md |
| Data-erasure runbook (right to be forgotten) | operations/data-erasure.md |
| Switching the stack between SQLite and Postgres (with its data) | operations/switching-databases.md — scripts/switch-db.sh and the per-service db-copy tool |
| Custom domain + TLS | deployment/custom-domain.md — branded hosts for Connect Links and the API, TLS at your proxy, private internal services |
| Backup + restore | deployment/backup-restore.md — pnpm backup / pnpm restore for the compose volumes and configuration |
| Upgrade runbook | deployment/upgrading.md — moving a compose deployment from version N to N+1 |
| Installing and renewing your license | deployment/license.md — the signed license file, offline verification, states, community mode, renewal, Compose and Helm |
Rotating STORE_SECRET |
deployment/key-rotation.md — offline re-encryption with pnpm rotate-store-secret |
| Platform logos | operations/platform-logos.md — why no logos ship, and the none / cdn / local modes |
Regenerating
Section titled “Regenerating”pnpm run docs:all # regenerates every artifact abovepnpm run docs:openapi # just the OpenAPI specpnpm run docs:screenshots # admin-UI PNGs embedded in guides (needs a live stack)pnpm run docs:screenshots:clean # remove all (screenshot fixture)-tagged rows from the admin DBpnpm run check:docs # CI: regenerate then fail if any docs drifteddocs:all starts with the integration-server orchestrator
pnpm --filter integration-server run generate:all, which chains:
generate-openapi— walks each vertical’sbuildSpec(), merges into one documentgenerate:api-reference— markdown from the specgenerate:postman— Postman v2.1 collection + 3 environments (local, production,/test/v1sandbox)generate:platforms-doc— flat 1548-row platform tablegenerate:env-doc— the services’ own env vars, plus the OAuth platforms whose client credentials are adapter config (not env vars)
then runs the artifacts that live outside integration-server:
runtime-settings:generate— admin-api’s_runtime-settings-schema.generated.tsdocs:admin-api-openapi+docs:admin-api-postman— admin-api’s own spec and collectionsdk:generate+cli:generate— typed clients inpackages/sdkandpackages/clidocs:cli—operations/cli.mdfrom the built CLIdocs:search-index— the search index the docs site reads
check:docs runs the whole chain and fails when any output differs from what is committed.
docs:screenshots is separate (not part of docs:all) because it needs a
running docker stack to capture the admin UI. The runner lives at
apps/admin/scripts/screenshots/; specs in specs.ts, fake seed fixtures
in seed.ts. PNGs land in docs/assets/screenshots/ (the admin console
guide’s in admin/) and are referenced from guides with relative paths, such
as , which render both on GitHub
and on the docs site. Seed data is
intentionally tagged (screenshot fixture) so it’s obvious when reviewing
the admin DB later.
Fixtures persist by default — re-running docs:screenshots is a no-op
on the seed side (every step dedupes by label / tenant / email pattern),
so the dev admin UI keeps its populated pages between regens. Run
docs:screenshots:clean to wipe every (screenshot fixture)-tagged row
when you want a pristine DB. Match is conservative: label / tenant +
email-domain (*.screenshot.example.local), so non-fixture customers
that happen to share the tenant are untouched.
Versioning
Section titled “Versioning”The OpenAPI spec’s info.version is read from
apps/integration-server/package.json. Bump the version there and run
pnpm run docs:all to refresh the spec.
Releasing
Section titled “Releasing”pnpm run release integration-server patch # 1.0.0 → 1.0.1pnpm run release integration-server minor # 1.0.0 → 1.1.0pnpm run release integration-server major # 1.0.0 → 2.0.0pnpm run release shared major # 0.1.0 → 1.0.0 for @opensteward/sharedThe release script bumps package.json, regenerates the docs, commits,
and creates a scoped git tag. It does NOT auto-push — review first, then:
git push origin main <scope>/v<version>Retrieving past versions
Section titled “Retrieving past versions”git tag -l 'integration-server/*' # list all tagsgit show integration-server/v1.0.0:docs/openapi/openapi.json # view a past specgit diff integration-server/v1.0.0..integration-server/v1.1.0 -- docs/ # diff between versionsTag convention
Section titled “Tag convention”| Scope | Tag format | When to tag |
|---|---|---|
integration-server |
integration-server/vX.Y.Z |
Release of the unified service |
admin |
admin/vX.Y.Z |
Release of admin panel |
admin-api |
admin-api/vX.Y.Z |
Release of admin REST API |
webhook-gateway |
webhook-gateway/vX.Y.Z |
Release of webhook receiver |
docs-server |
docs-server/vX.Y.Z |
Release of Swagger UI server |
shared |
shared/vX.Y.Z |
Breaking or notable change to @opensteward/shared |
design-system |
design-system/vX.Y.Z |
Token / CSS / logo updates |
codegen |
codegen/vX.Y.Z |
Changes to generation utilities |
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.