Backend Principle Eng JavaScript Pro Max

Principal-level guidance for JavaScript backend systems. Optimized for Bun runtime with Node 20 LTS compatibility.

When to Apply

• Designing or refactoring JavaScript services, APIs, and distributed systems
• Reviewing code for correctness, reliability, performance, and security
• Planning migrations, scalability, or cost optimizations
• Incident follow-ups and systemic fixes

Priority Model (highest to lowest)

Quick Reference (Rules)

1. Correctness & Contracts (CRITICAL)

• api-contracts - Versioned schemas and explicit validation
• input-validation - Validate at boundaries, reject unknowns
• idempotency - Safe retries with idempotency keys
• invariants - Enforce domain rules in service and database
• time-utc - Store UTC, use monotonic clocks for durations

2. Reliability & Resilience (CRITICAL)

• timeouts - Set per dependency; no unbounded waits
• retries - Bounded with jitter; avoid retry storms
• circuit-breakers - Fail fast for degraded dependencies
• bulkheads - Isolate thread pools and queues
• load-shedding - Graceful degradation under load

3. Security & Privacy (CRITICAL)

• authz - Enforce at every service boundary
• secrets - Use vault/KMS; never in code or logs
• data-min - Redact PII by default
• crypto - TLS everywhere; strong defaults
• supply-chain - Pin deps; scan CVEs

4. Performance & Efficiency (HIGH)

• async-io - Use async for I/O bound paths; avoid blocking
• pooling - Right-size DB/HTTP pools; avoid starvation
• cache - TTL and stampede protection for hot reads
• batching - Batch I/O and DB operations where safe
• profiling - Measure before optimizing

5. Observability & Operability (HIGH)

• structured-logs - JSON logs with trace ids
• metrics - RED/USE metrics plus business KPIs
• tracing - Propagate context end-to-end
• alerts - SLO-based with runbooks
• deploys - Safe rollouts and rapid rollback

6. Data & Consistency (HIGH)

• transactions - Clear boundaries; avoid cross-service tx
• schema-evolution - Backward compatible migrations
• outbox - Reliable event publishing
• id-generation - Globally unique IDs
• read-models - Use CQRS when complexity is justified

7. Scalability & Evolution (MEDIUM)

• stateless - Externalize state, scale horizontally
• partitioning - Shard by stable keys
• versioning - API and event versioning
• backpressure - Bounded queues, explicit limits
• config - Dynamic config with validation

8. Developer Experience & Testing (MEDIUM)

• tests - Unit, integration, contract, load tests
• determinism - Hermetic tests, fixed seeds, stable time
• lint - ESLint + Prettier for consistency

Execution Workflow

1. Clarify product goals, SLOs, latency and cost budgets
2. Map data flow, dependencies, and failure modes
3. Choose storage and consistency model (document tradeoffs)
4. Define contracts: API schemas, events, and idempotency
5. Implement with safe defaults, observability, and resilience
6. Validate with tests, load, and failure scenarios
7. Review risks and publish runbooks

Language-Specific Guidance

See references/javascript-core.md for Bun-first stack defaults and JS-specific linting/testing.