performance

Profile the actual system before changing anything, since intuition about bottlenecks is unreliable. Record the baseline number, the target, and the measured delta in the same PR as the change so optimization is driven by measurement.

Every read that can grow with data volume needs an explicit LIMIT, page size, cursor, or aggregation. Check call sites in code review, not just the query itself, since a fetchall() on a growing table can permanently add tens of megabytes per request.

Synchronous heavy work on an async loop freezes every request queued behind it; one synchronous embedding call froze all HTTP traffic for 5-18 seconds in a real incident. Anything taking more than a few milliseconds should run on a thread pool, worker, or async-native client.

Only after measuring. Premature optimization routinely targets the wrong layer, while profiling-driven refactors have doubled critical-path speed and reduced code size. Establish a baseline and target first, then optimize the measured bottleneck.

Performance asks whether the system is fast and cheap enough: throughput, latency, resource budgets, and the critical path. Concurrency asks whether it is correct under parallel execution: shared state, connection lifecycles, and backpressure. They share incidents like event-loop blocking but answer different questions.