orbyn-backend-design git:20261026.5ac9638A

Immutable. This exact content never changes and is served at /api/v1/blob/8e513fd98ac22410.

---
name: orbyn-backend-design
description: "Design and implement API/service behavior across validation, authorization, persistence, concurrency and client errors using the consuming project's stack. Use architect first for unsettled ownership; use orbyn-data-migration for stored-format changes."
---

# Backend contracts that reach the client

Start from the consuming project's instructions and actual API, transport and
domain owners. Use [how](../how/SKILL.md) to trace the existing request, and
[architect](../architect/SKILL.md) when ownership or lifecycle is undecided.
Do not introduce Fastify, PostgreSQL, Zod or any other Orbyn stack component merely
because it appears in an example.

For service readiness or a material workload change, include the
[operating contract](../architect/references/service-readiness.md): user completion
indicator and observation window, demand/quota bounds, operator/recovery ownership,
and data classification, retention/deletion and safe diagnostic fields. Put these
in the returned criteria; unknown targets or policies remain unresolved gates.

State the caller's input, allowed identity/scope, successful result and expected
domain failures. Identify which reads establish authority/freshness and which
write or external effect must preserve them. A parsed ID and a signed-in session
do not prove access to the referenced tenant resource.

Place parsing at the trust boundary and reuse the owning schema inside the
service. Keep transactions around related persistence, with version conditions or
locks where stale state matters. For external effects, define operation identity,
unknown outcomes and reconciliation; do not hold a database transaction open
while a remote provider decides. Preserve cancellation and cleanup ownership.

Trace the result through the shared client and each affected UI. Errors should
remain recognizable enough for a client to preserve its draft, explain the failure
and retry deliberately. Avoid returning success for a rejected effect or exposing
internal exceptions and credentials as UI copy.

For example, moving a task between projects requires source/destination scope,
stage compatibility, a concurrency condition and a consistent API result. Updating
one route without its shared schema and mobile caller leaves the feature incomplete.

When verification is authorized, check the legitimate outcome, denied access,
stale update and relevant retry behavior at the owning boundary. Return the changed
contract, affected callers, evidence and recovery limits. Hand persisted-format
changes to [data migration](../orbyn-data-migration/SKILL.md), visible flows to
[UI design](../orbyn-ui-design/SKILL.md), and coordinated work to
[orbyn-workflow](../orbyn-workflow/SKILL.md).

## Worked example

[Retrying an external effect](examples/retry-safe-effect.md) separates request
identity, durable state and an unknown provider outcome in a synthetic task.

Pair the effect contract with [language guidance](../language-best-practices/SKILL.md)
for the actual service/runtime. Database syntax and isolation need the engine's
SQL reference; language types alone do not prove transaction or authorization
behavior. Choosing a replacement stack belongs to stack selection and architect,
not an incidental service implementation.

## Production behavior and diagnostics

Use [production service contracts](references/service-contracts.md) for bounded input/work, error semantics, concurrency and stable pagination. Use [observability](references/observability.md) when the changed operation needs diagnosable phases and privacy-aware records; installing telemetry or a provider is a separate decision.

## Boundary and retry rules

For critical retry, lease or worker lifecycle rules, connect current effect
boundaries to [statecharts](../architect/references/statecharts.md) and
[property verification](../tdd/references/formal-verification.md) when justified.
For example, a lost save response needs reconciliation/idempotency at the real
backend boundary; a simulated preview cannot prove absence of duplicate effects.

Validate at actual trust/effect boundaries and express failures in the owning
contract; do not scatter defensive checks over already valid internal values.
Retries, crashes and duplicate delivery need an explicit idempotency key, effect
identity or recovery contract. Concurrent writers need application-level ownership
or fencing; a Git worktree cannot isolate them. Use the
[boundary method](references/principles/boundary-discipline.md) and
[idempotency method](references/principles/make-operations-idempotent.md) for examples.