ahtishamshahzad/agent_dev_flow/backend-performance

Backend Performance

Purpose

Improve backend performance the disciplined way: measure, find the actual bottleneck, apply the narrowest safe fix, and prove the improvement. Aligns with ../../performance-review; database-level depth lives in ../../database/database-performance.

When to Use

• When latency/throughput/resource usage misses targets, with evidence.
• When setting performance budgets for critical endpoints.
• Not for speculative "make it faster" passes without measurement.

Inputs

• Metrics/traces showing the symptom (backend-observability): which endpoints, which percentiles, since when.
• Performance targets per critical flow.

Discovery Questions

• What exactly is slow — endpoint, percentile, load level? Since when (deploy? data growth?)?
• Where does the time go: database, external calls, serialization, event-loop blocking?
• What are the targets — and are they real requirements or vibes?

Responsibilities

• Measure first: per-endpoint duration breakdowns, query logs, external-call timing; profile CPU/event-loop where compute-bound. The bottleneck is usually one of: N+1 queries, missing index, slow external call in the request path, oversized payloads, event-loop blocking.
• Database work: N+1 detection and batching/eager-loading, index needs, unbounded queries → delegate specifics to ../../database/database-performance and ../../database/indexing.
• External calls: move out of the request path (background-jobs), parallelize independent calls, cache stable responses (third-party-integrations timeouts already bound them).
• Caching: only for measured hot, stable data — with explicit invalidation and stampede stories; cache layers (in-process vs shared) chosen for the instance count. A cache without an invalidation design is a future correctness bug (../../database/concurrency).
• Node specifics: keep the event loop unblocked (no sync crypto/zlib/fs in handlers, chunk large JSON work); pool sizes matched to DB limits × instances.
• Payloads: pagination enforced, field selection over SELECT * dumps, compression at the edge.
• Prove it: re-measure under representative load; record before/after; watch for regressions via backend-observability dashboards.

Required Workflow

1. Reproduce and quantify the symptom against the target.
2. Break down where time goes; identify the dominant contributor.
3. Apply the narrowest fix at that layer (delegate DB depth to the database pack).
4. Re-measure under representative conditions; compare to target.
5. Record fix + numbers; add a regression guard (alert threshold or test).

Decision Rules

• No optimization without a measurement pointing at it.
• Fix the dominant contributor first; a 5ms micro-win under a 2s query is noise.
• Caching is the last resort after query/design fixes — it trades correctness risk for speed; record the invalidation path when taken.
• Scaling out is a valid fix only after per-instance efficiency is sane.

Rules

• Before/after numbers accompany every performance change (unverified until run).
• Performance fixes must not weaken authorization/validation (no "skip the check, it's slow").
• Budgets for critical endpoints live with the endpoint design (rest-api-design).

Anti-Patterns

• Adding Redis before finding the missing index.
• Optimizing code paths no measurement implicated.
• Caches with TTL-only "invalidation" for data users edit.
• Promise.all fan-outs that stampede the DB pool.
• Declaring victory from local benchmarks on empty tables.

Validation Checklist

• [ ] Symptom quantified against a target.
• [ ] Time breakdown identifies the dominant contributor.
• [ ] Narrowest fix applied at the right layer.
• [ ] Cache additions include invalidation + stampede design.
• [ ] Before/after measured under representative load.
• [ ] Regression guard in place.

Definition of Done

A measured bottleneck, a narrow fix at the responsible layer, proven improvement against the target under representative load, and a guard against regression — all recorded.

Related Skills

../../performance-review, ../../database/database-performance, ../../database/indexing, backend-observability, background-jobs, third-party-integrations, rest-api-design.

Related Knowledge

../../../knowledge/ (targets, load profile, data growth).

Related References

../../../references/backend/performance/ (measurement notes, when populated).

Context Loading Guidance

• Requires: the symptom with numbers, targets, relevant endpoint/query code.
• Does not require: the whole codebase, unrelated endpoints.
• May load: ../../database/database-performance (query depth), backend-observability.
• Stop when: improvement is proven and recorded with a regression guard.

Token Efficiency Guidance

Load only the implicated path. Report as symptom → cause → fix → numbers; skip the tour of everything examined.