Skip to content

esz-backend documentation

Internal and partner-facing documentation for the esz-backend platform. This site is served behind authentication — nothing here is public.

New here? Why esz-backend explains what the platform is for before the pages below explain how it works.

  • Connect a system

    Start with scope, responsibilities and the discovery checklist.

    Partner overview

  • Authenticate your client

    Choose the right method, request credentials and get an access token.

    Authentication quick start

  • Call an API

    Find URL patterns, request examples, paging and the OpenAPI specification.

    Endpoints and contracts

  • Find a field mapping

    Browse canonical fields, external names, direction and authority.

    Data catalogue

Integration — connecting an external system

  • Project brief — the short, standalone version to hand to a project lead deciding whether and how to integrate.
  • Partner overview — the onboarding narrative that threads the reference pages together in the order the work happens.
  • Authentication — choose an auth method, request credentials, obtain a token and verify webhooks. Canonical.
  • Endpoints & contracts — request/response shapes and the published-field contract. Canonical.
  • Environments — hostnames, sandboxes, egress allowlisting.
  • Errors & retries — transient vs permanent, backoff, idempotency. Canonical.
  • Data protection — personal data, DPA, minimisation.

Architecture — how the platform is built

  • Platform & services — the service catalogue, the design rules, and where a vendor app fits. Canonical.
  • Domain modelling — bounded contexts, field authority, and the six questions, with a worked example.

Data — what crosses each boundary

  • Data catalogue — task-oriented entry point for every domain field map.
  • Domain pages show the canonical type, vendor API name, flow, authority, transformations and mirror-only operational fields.

Reference

  • Glossary — terms as used across these docs.

How the docs are organised

Each fact has one canonical home; other pages link to it rather than restating it. Change how authentication works → edit Authentication; internal procedures remain under Operations in the navigation. Change the service list → edit Platform & services.

Editing

Docs are plain Markdown under services/docs/content/. Preview locally with just docs-serve, build with just docs-build. The build is --strict, so a broken link or a page missing from the nav fails CI.