Performance

# Benchmark runbook
1. Build/run production mode; never compare next dev.
2. Reset/seed representative data.
3. Confirm test environment, commit, versions, region, and DB topology.
4. Warm up.
5. Run the exact same scenario (route, token role, concurrency, duration, dataset).
6. Record p50/p95/p99, throughput, non-2xx, CPU/memory, DB latency/connections.
7. Change one variable.
8. Repeat.
9. Keep change only if improvement is meaningful and correctness/security tests pass.

# TaskFlow performance budget (starting targets)

These are course targets, not universal SLAs. Revisit after production field data exists.

- Core Web Vitals at p75: LCP <= 2.5 s, INP <= 200 ms, CLS <= 0.1.
- GET /tasks p95 API latency <= 300 ms under the recorded normal-load scenario.
- PATCH /tasks/:id p95 <= 400 ms under the recorded normal-load scenario.
- Unexpected 5xx under benchmark <= 1%.
- Query review required for repeated hot-path queries around/above 100 ms or any N+1 pattern.
- No unexplained client bundle regression after dependency changes.

# TaskFlow Phase 31 performance snapshot
Study snapshot only. Performance changes must be measured before/after in the same scenario. Keep correctness, authorization, data isolation, and security tests green.

# Official/current references used
- https://nextjs.org/docs/app/guides/production-checklist
- https://nextjs.org/docs/app/guides/lazy-loading
- https://nextjs.org/docs/app/getting-started/fonts
- https://www.npmjs.com/package/@next/bundle-analyzer
- https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults
- https://tanstack.com/query/latest/docs/framework/react/guides/render-optimizations
- https://docs.prisma.io/docs/orm/v7/more/best-practices
- https://www.postgresql.org/docs/18/sql-explain.html
- https://www.postgresql.org/docs/18/indexes-multicolumn.html
- https://www.postgresql.org/docs/18/indexes-examine.html
- https://supabase.com/docs/guides/database/connecting-to-postgres/pooling-and-limits
- https://supabase.com/docs/guides/database/connecting-to-postgres
- https://fastify.dev/docs/latest/Guides/Recommendations/
- https://fastify.dev/docs/latest/Reference/Validation-and-Serialization/
- https://web.dev/articles/vitals
- https://www.npmjs.com/package/autocannon

# Phase 31 version lock
- Prisma remains course-locked at 7.9.1.
- PostgreSQL 18 documentation is used for planner/index guidance.
- @next/bundle-analyzer 16.3.5 (optional development tool; keep aligned with your Next.js release line).
- autocannon 8.0.0 (benchmark tool).

# API hot-path notes
1. Remove unnecessary I/O before micro-optimizing framework code.
2. Keep payloads bounded and projections intentional.
3. Move long-running reports/imports/exports to background workers when the request budget is exceeded.
4. Do not solve DB saturation by blindly increasing connection counts.

// Example query-shape review: bounded projection + relation projection.
const tasks = await prisma.task.findMany({
  where,
  select: {
    id: true,
    title: true,
    status: true,
    priority: true,
    createdAt: true,
    assignee: { select: { id: true, displayName: true } },
  },
  orderBy: [{ createdAt: 'desc' }, { id: 'asc' }],
  take: pageSize,
  skip,
});

import bundleAnalyzer from '@next/bundle-analyzer';

const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
});

export default withBundleAnalyzer({});

// Example only - keep resource freshness intentional.
export const TASK_LIST_STALE_TIME_MS = 30_000;

// Do not disable structural sharing or tracked-property behavior unless profiling proves a problem.

-- Run ANALYZE first when appropriate so planner statistics are current.
EXPLAIN (ANALYZE, BUFFERS)
SELECT id, title, status, priority, "createdAt"
FROM "Task"
WHERE "projectId" = '00000000-0000-4000-8000-000000000001'::uuid
  AND status = 'IN_PROGRESS'
ORDER BY "createdAt" DESC, id ASC
LIMIT 20 OFFSET 0;

-- Candidate only. Measure before/after; do not blindly add indexes.
-- CREATE INDEX CONCURRENTLY ... ON "Task" ("projectId", status, "createdAt" DESC, id);

# Requires a valid bearer token in TASKFLOW_TOKEN.
# Run against a disposable/staging environment you are authorized to load test.
pnpm dlx autocannon@8.0.0 `
  -c 20 `
  -d 30 `
  -m GET `
  -H "Authorization=Bearer $env:TASKFLOW_TOKEN" `
  "http://localhost:3001/tasks?page=1&pageSize=20"

# Performance verification matrix
- Compare production builds, never development mode.
- Record commit, dataset, environment, concurrency, duration, and auth role.
- GET /tasks benchmark captures p50/p95/p99, throughput, errors.
- PATCH /tasks/:id benchmark uses a safe repeatable fixture/workflow.
- Query count check catches accidental N+1 behavior.
- EXPLAIN (ANALYZE, BUFFERS) recorded for hot Task list query.
- Index change measured before/after and validated with correctness tests.
- DB connection usage observed during load.
- Bundle analyzer run after dependency/client-boundary changes.
- Core Web Vitals lab measurement paired with field telemetry when available.
- Security/authorization tests remain green after optimization.