SKILL: backend-architecture#

Purpose#

Design backend systems with clear boundaries: API contracts, services, persistence, observability, and security controls.

When to Use#

• Building a new backend or major subsystem.
• Introducing a new API surface (REST/WebSocket).
• You need a concrete module/service layout and DB model.

Inputs#

• requirements (required, string|object): endpoints, behaviors, SLAs, compliance needs.
• constraints (optional, string[]): security, latency, cost, runtime, stack limits.
• data_entities (optional, string[]): core domain objects.
• integration_points (optional, string[]): external services/APIs.

Steps#

1. Define API surface:
   • endpoints/events
   • request/response schema
   • error model (codes/messages)
2. Define security model:
   • authentication method
   • authorization rules
   • rate limits and abuse controls
3. Define service/module boundaries:
   • controllers/handlers
   • domain services
   • repositories/adapters
4. Define persistence:
   • schema/tables/collections
   • migrations
   • idempotency model (if needed)
5. Define observability:
   • structured logs
   • request ids
   • audit trail for sensitive actions
6. Define validation plan (tests + CI hooks).

Validation#

• Every endpoint has authz rules or an explicit “public” justification.
• Inputs are validated; outputs are consistent with schema.
• Failure modes are explicit (timeouts, retries, fallbacks).

Output#

Architecture spec (example schema):

yaml

api:
  - method: POST
    path: /v1/...
    auth: required
services: ["..."]
data_model: ["..."]
observability: ["logs", "metrics (optional)"]
validation: ["unit tests", "integration tests"]

Safety Rules#

• Do not design systems that require storing secrets in source control.
• Avoid introducing new dependencies unless justified.
• Default to safe failure modes (no partial writes without idempotency).

Example#

Requirement: “Webhook ingestion with replay protection.” Output: includes idempotency key storage, signature verification, and audit logging.