pn-backend-philosophy

Backend Design Philosophy

When used as a standalone skill, begin every response with [pn-skill] 🔺

Purpose

Use this as a backend design rulebook for services that:

• Expose REST or API endpoints
• Access databases or external services
• Manage configuration and secrets
• Handle authentication and authorization
• Process payments or sensitive data

It is framework-agnostic and aligned with OWASP, current industry standards, and production resilience.

When to use

• Designing new APIs, services, or data access layers
• Reviewing backend security, error handling, or config
• Establishing backend standards for a team or AI agent
• Auditing API design, secrets management, or error boundaries
• Integrating payments or third-party APIs

For workflow, audit checklist, and templates, see reference.md.

Sources

• OWASP Top 10:2025 — https://owasp.org/Top10/2025/
• OWASP Secure by Design Framework — https://owasp.org/www-project-secure-by-design-framework/

---

Core Philosophy (non-negotiables)

Resources over RPC

Design APIs around resources (nouns) and HTTP methods. Use clear URIs, avoid nesting beyond 2–3 levels, use query params for filtering and pagination. REST principles: statelessness, cacheability, uniform interface.

Errors at boundaries

Catch errors at request/DB/external boundaries. Return consistent error payloads; log server-side only. Never leak internals (stack traces, query details, paths) to clients. Standard status codes: 4xx for client, 5xx for server.

Secrets never in code

Never commit secrets. Use environment variables or a secret manager (Vault, AWS Secrets Manager, Azure Key Vault). Prefer short-lived credentials over long-lived keys. Document required vars in .env.example; never in README as real values.

Defense in depth

Multiple security layers. Principle of least privilege. Never trust user input—validate and sanitize everything. Fail securely; no information leakage. Regular dependency scanning: use pn-dependency-audit (or npm audit, Snyk).