Backend Design

---
name: backend-design
description: "Produce a complete, review-ready backend design spec with explicit tradeoffs, compliance checks, and a fixed output contract.. Use when Use this skill when the task matches its description and triggers.."
---

# Backend Design

## Compliance
- Check against GOLD Industry Standards guide in ~/.codex/AGENTS.override.md. If missing, use `references/standards-baseline.md`.


## Overview
Produce a complete, review-ready backend design spec with explicit tradeoffs, compliance checks, and a fixed output contract.

Gold standard rule (Jan 2026):
All guidance, decisions, and outputs must align with industry best practices as of Jan 2026.

## Philosophy
- Aim for correctness first, then security, then reliability; speed is a feature, not a priority.
- Prefer explicit tradeoffs over implicit assumptions; call out what you are optimizing for.
- Design for operability: if it cannot be observed and rolled back, it is not ready.

Ask these guiding questions before drafting:
- What is the single most critical user workflow and its failure mode?
- Which data integrity constraints must never be violated?
- Where does trust enter the system and how is it verified?
- What is the minimal viable architecture that still meets reliability goals?

## Empowerment
You are capable of extraordinary rigor here. Push boundaries on clarity and risk coverage while keeping the design practical.

## Decision priority stack (must follow)
1. Correctness and data integrity
2. Security and compliance
3. Reliability and observability
4. Performance and scalability
5. Developer ergonomics and delivery speed

## Inputs (ask only if blocking; max 2 questions)
1. System type: REST, GraphQL, or both
2. Compliance scope: which standards apply (if user says "all", include a superset checklist and flag legal review)

## Workflow (use this order)
1. Confirm scope: product goal, primary workflows, critical path, and integration surfaces.
2. Choose architecture pattern: Clean, Hexagonal, DDD, or hybrid; justify.
3. Define domain model and invariants.
4. Define API contract and versioning strategy.
5. Define data design and migration strategy.
6. Define authN/authZ model and tenanting.
7. Define reliability, observability, and performance targets.
8. Identify risks and edge cases.
9. Produce file plan and next steps.

## Output contract (always in this order)
1. SYSTEM_CONTEXT
2. ARCHITECTURE_PATTERN
3. DOMAIN_MODEL
4. API_CONTRACT
5. DATA_DESIGN
6. AUTHN_AUTHZ
7. RELIABILITY
8. OBSERVABILITY
9. PERFORMANCE
10. INTEGRATION_SURFACES
11. APPS_SDK_REQUIREMENTS
12. RISK_CHECKLIST
13. FILE_PLAN

Use `assets/backend_design_output_template.md` as the default structure.

## Required response headings
Every response must include these headings:
- `## When to use`
- `## Inputs`
- `## Outputs` (place the output contract under this heading)

## Failure-mode template (out of scope)
Use this exact structure when the request is out of scope:

```md
## When to use
- This skill applies to backend architecture and API design requests. The current request is out of scope.

## Outputs
- None (out of scope).

## Inputs
- None (out of scope).
```

## Standards baseline (enforce as of Jan 2026)
- HTTP semantics and status codes per RFC 9110
- OpenAPI latest published version (check `oas/latest`; 3.1.1 as of Oct 24, 2024) for REST contracts (JSON Schema 2020-12 dialect)
- GraphQL spec latest edition (Sep 2025)
- JSON (RFC 8259), JSON Schema 2020-12, YAML 1.2.1 for docs and schemas
- OWASP API Security Top 10 (2023) + OWASP Top 10 (2025)
- Compliance scopes: SOC 2, ISO/IEC 27001:2022, PCI DSS v4.0.1, HIPAA, GDPR, CCPA/CPRA (flag legal review)

Use references:
- `references/standards-baseline.md`

## Architecture pattern selection
- **Clean Architecture** when business rules must stay framework-agnostic and testable.
- **Hexagonal** when many external systems exist and swapability/testing are priorities.
- **DDD** when complex domain logic and bounded contexts are needed.
- **Hybrid** when two or more patterns are needed; explain boundaries.

## API contract rules
- Enforce resource naming, HTTP semantics, pagination, versioning, error format, rate limits, and auth.
- REST and GraphQL can coexist; avoid overlapping responsibilities.
- For both, define a stable error schema and client-facing examples.
- Include rate-limit + quota templates for REST/GraphQL and MCP tools.

Use references:
- `references/api-design-checklist.md` for REST + GraphQL validation
- `references/rest-best-practices.md` for REST patterns
- `references/graphql-schema-design.md` for GraphQL patterns

## Data design rules
- Define entities, relationships, constraints, indexing strategy, and migration/versioning.
- Model consistency boundaries (aggregates or transactions).

## Auth and compliance
- Always specify authN (token/session) and authZ (roles/scopes/policies).
- If compliance scope is "all", include a superset checklist for SOC2, ISO 27001, HIPAA, PCI DSS, GDPR, and CCPA and flag legal review.
- If Auth0 is used, enforce OAuth 2.1 aligned flows, PKCE, refresh token rotation, and token storage best practices.

## Reliability and observability
- Define idempotency strategy for writes.
- Include retry, timeout, circuit breaker, and rate-limit policies.
- Specify logs, metrics, traces, and alerting.
- Add idempotency + replay protection for MCP tools (nonce, request_id, dedupe window).

- If clients include React/Vite/Tailwind/TS, Apps SDK UI, OpenAI widgets, MCP, Storybook, or CLI, define contract-first integration. When UI is involved, align with canonical design tokens/guidelines in `references/design-guidelines-canonical.md` (or summary).
- If a Tauri desktop app is in scope, define the Rust command/IPC layer, permission/allowlist boundaries, and data validation rules. Specify how backend services interact with the Tauri layer (local vs remote calls, auth handoff, and error mapping).
- If Cloudflare Workers are used, account for Workers limits, streaming, and security model constraints.
- If Ollama Cloud API or frontier models are used, document provider-specific auth, data handling, and usage constraints.
- Provide guidance for typed clients and schema-driven codegen.
- If CLI is required, follow create-cli conventions (flags, output modes, exit codes).

Use references:
- `references/integration-surfaces.md`
- `references/tech-standards.md`
- `references/tauri-backend.md`
- `references/rust-backend-design.md`
- `references/auth0-oidc-best-practices.md`
- `references/cloudflare-workers-notes.md`
- `references/ollama-cloud-api.md`
- `references/frontier-models.md`
- `references/data-retention-residency.md`
- `references/rate-limit-templates.md`
- `references/mcp-idempotency-replay.md`
- `references/contract-testing.md`
- `references/security-headers.md`
- `references/audit-log-integrity.md`
- `references/feature-flagging-rollout.md`
- `references/apps-sdk-ux.md`
- `references/apps-sdk-use-cases.md`
- `references/apps-sdk-auth.md`
- `references/apps-sdk-state.md`
- `references/apps-sdk-monetization.md`
- `references/apps-sdk-metadata.md`
- `references/apps-sdk-security-privacy.md`

## Output schema templates
- Use `assets/mcp_tool_schema_template.json` for MCP tool contracts.
- Use `assets/cli_output_schema_template.json` for CLI JSON output contracts.

## Anti-patterns to avoid
- Unversioned APIs or breaking changes without deprecation
- Business logic in controllers or route handlers
- Missing idempotency for create or payment flows
- ORM entities leaked across service boundaries
- No telemetry for failures or latency

## Anti-pattern quick warnings
Avoid these anti-patterns. DO NOT ship designs without explicit authZ, versioning, and rollback plans. NEVER propose unsafe defaults (wide-open CORS, plaintext secrets, or unauthenticated admin paths). These mistakes and pitfalls lead to insecure or unreliable systems.

## Variation guidance (prevent convergence)
- Vary structure depth based on system complexity (simple CRUD vs multi-tenant or high-scale).
- Vary tradeoff emphasis (latency vs cost, availability vs consistency, simplicity vs extensibility).
- Vary examples by domain (payments, healthcare, analytics, AI pipelines) to avoid generic patterns.

## Resources
Use the references directory for detailed checklists and patterns. Do not inline large templates in this file.

## Contracts and evals (reference)

- Output contract schema: `references/contract.yaml`
- Evaluation rubric: `references/evals.yaml`

## When to use
- Use this skill when the task matches its description and triggers.
- If the request is outside scope, route to the referenced skill.


## Outputs
- A structured response or artifact appropriate to the skill.
- Include `schema_version: 1` if outputs are contract-bound.


## Constraints
- Redact secrets/PII by default.
- Avoid destructive operations without explicit user direction.


## Validation
- Run any relevant checks or scripts when available.
- Fail fast and report errors before proceeding.
## Procedure
1) Clarify scope and inputs.
2) Execute the core workflow.
3) Summarize outputs and next steps.

## Antipatterns
- Do not add features outside the agreed scope.