Backend platform map

This documentation covers the backend contract used by the console, TypeScript client, CLI, MCP server, and serverless runtime. Start here when you need to decide which service owns a capability.

Contract surfaces

Need	Canonical surface	Documentation
Read or mutate business records	Entity Service	entity data guide, CRUD reference
Discover or evolve schemas	Schema Manager	schema design, Schema Manager API
Run backend code	Serverless functions	serverless functions
Coordinate long-running work	Workflow Service	workflows
Automate from a terminal	gsb CLI	CLI reference
Connect an editor or agent	MCP server	MCP server
Inspect the contract safely	Read-only inspection tools	MCP server

The API reference lists every registered operation and links to its request, response, and safety contract.

Backend request lifecycle

1. Authenticate the caller and verify the token signature against the issuer JWKS.
2. Resolve tenant context from the verified session, never from an untrusted URL or body field.
3. Authorize the operation against that tenant and entity definition.
4. Validate external input with a schema before calling Entity Service or a function.
5. Bound reads with selected columns, pagination, and explicit includes.
6. Rate-limit mutations and side effects, then log a request id with secrets and PII redacted.

Authentication and authorization are separate controls. See authentication and tenancy for the server-side session pattern.

Data and schema lifecycle

Definitions are the source of truth for entity properties, references, constraints, and indexes. Read the definition before writing records, select only the fields the caller needs, and evolve properties through Schema Manager operations rather than undocumented payloads.

For lists, use QueryParams with a stable sort, skip, and take. Use include for bounded relationships. Request a total count only when the UI displays it. Prefer getById when the identifier is known.

Code and workflow lifecycle

Serverless functions run in the tenant backend and receive runtime context, entity definitions, enums, and referenced libraries. Test code with testWfFunction before publishing it. Use runWfFunction for an approved invocation, and keep destructive or external side effects behind explicit approval.

Use startWorkflow for asynchronous processes that wait on people, timers, or external events. Use runWorkflow only when the caller needs an inline result. Monitor instances and audit rows as ordinary entities through Entity Service.

CLI and MCP safety

The CLI and MCP server share one registry and implementation. Read tools are bounded inspection surfaces; writes, destructive operations, and external side effects require explicit approval. Inspect gsb tools --read-only before automation, and never place tokens in command history, browser storage, or committed configuration.

Documentation source and Dev1 extraction

Tenant-authored help pages live in GsbHelpPage and their localized content lives in the related GsbMlContent record. English content is the en_us field. The canonical CLI extraction query is:

gsb call query --tenant dev1 --raw --input '{
  "queryParams": {
    "entDefName": "GsbHelpPage",
    "selectCols": [
      {"name":"id"}, {"name":"title"}, {"name":"slug"},
      {"name":"path"}, {"name":"parent_id"}, {"name":"content_id"},
      {"name":"lastUpdateDate"}
    ],
    "includes": [{
      "name": "content",
      "selectCols": [{"name":"id"}, {"name":"title"}, {"name":"en_us"}]
    }],
    "count": 500,
    "calcTotalCount": true
  }
}'

Treat the returned HTML as untrusted content before rendering it. Keep the export build-time and reviewed; the public docs app must not require tenant credentials or make live backend calls.

Coverage boundary

This site documents the backend contract and its approved integration surfaces. Product-specific frontend behavior, local persistence, fake API responses, and browser-only business logic do not belong here. When a capability is missing from Entity Service, Schema Manager, functions, or workflows, document the missing backend contract instead of simulating it in an app.