07-performance-scalability

name	07-performance-scalability
description	Use when auditing or improving speed, responsiveness, Core Web Vitals, caching, database performance, API response times, image optimization, bundle size, rendering strategy, and launch scalability.

Performance and Scalability

Mission

Make the system fast enough for real users, real devices, real data volume, and launch traffic. AI-generated apps often work in localhost while hiding huge bundles, unoptimized images, unindexed queries, zero caching, and fragile serverless/database behavior.

Use when

• The user asks about performance, scaling, slow pages, launch readiness, PageSpeed, Core Web Vitals, Supabase performance, Vercel limits, API latency, or bundle size.

Targets

• LCP under 2.5s.
• INP under 200ms.
• CLS under 0.1.
• First Load JS ideally under 200KB for typical pages.
• List queries paginated.
• External calls have explicit timeouts.
• Serverless database connections use pooling where applicable.

Workflow

1. Identify framework and build profile

cat package.json
npm run build 2>/tmp/build.log || pnpm build 2>/tmp/build.log || yarn build 2>/tmp/build.log
cat /tmp/build.log | tail -120

Look for route sizes, first-load JS, static/dynamic rendering, and build warnings.

2. Audit Core Web Vitals and loading UX

If URL is available, use PageSpeed/Lighthouse or provider analytics. In code, search:

rg -n 'loading\.tsx|Suspense|skeleton|ErrorBoundary|error\.tsx|priority=|next/image|<img|layout shift|font-display' app pages src 2>/dev/null

Required:

• skeleton/loading states for slow routes;
• error boundaries;
• stable image dimensions;
• font loading does not cause major layout shifts.

3. Audit images

find public app src -type f \( -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.webp' -o -iname '*.gif' \) -size +500k -print 2>/dev/null
rg -n '<img|next/image|Image from' app pages src 2>/dev/null

Required:

• use next/image or equivalent optimizer;
• width/height/alt set;
• above-the-fold images prioritized;
• large images compressed and modern formats preferred;
• lazy loading below the fold.

4. Audit bundle and client boundaries

rg -n '"use client"|use client|dynamic\(|import\(|from "lodash"|from "moment"|from "lucide-react"|from "@mui"|from "framer-motion"|from "recharts"' app pages src 2>/dev/null

Red flags:

• use client at layout/root level without need;
• giant libraries imported into common paths;
• charts/editors/maps loaded on first page load;
• no dynamic import for heavy components.

5. Audit caching and rendering strategy

rg -n 'revalidate|cache:|force-dynamic|no-store|s-maxage|Cache-Control|SWR|useQuery|React Query|fetch\(' app pages src server 2>/dev/null

Required:

• SSG/ISR for stable pages;
• SSR only where freshness requires it;
• SWR/React Query for client-side data fetching;
• API cache headers for cacheable responses;
• avoid no-store everywhere.

6. Audit database performance

rg -n 'select\(\*\)|findMany|limit|range\(|order\(|where:|include:|for \(.*await|Promise\.all|user_id|organization_id|tenantId|created_at|index|@@index|CREATE INDEX' app pages src server prisma supabase db 2>/dev/null

Required:

• pagination on all list queries;
• indexes on frequent filters;
• no N+1 loops;
• no full-table select('*') without filters;
• connection pooling in serverless.

7. Audit API performance

Search external calls and payload size:

rg -n 'fetch\(|axios|openai|anthropic|stripe|resend|sendgrid|AbortController|timeout|stream|ReadableStream|select\(\*\)' app pages src server 2>/dev/null

Required:

• explicit timeouts;
• streaming for long AI responses;
• minimal payloads;
• background jobs for heavy work;
• avoid blocking user requests on non-critical operations.

8. Basic load readiness

If allowed:

npx artillery quick --count 10 --num 5 https://example.com

Or provide a k6 script for the user to run. Record provider limits and expected launch traffic.

Output contract

# Performance and Scalability Report

## Executive summary

## Metrics / build observations

## Findings
| Severity | Area | Evidence | Impact | Fix | Verification |
|---|---|---|---|---|---|

## Quick wins

## Launch-readiness risks

## Changes made

## Remaining risks

Stop criteria

Stop and warn before load-testing production at meaningful volume, changing cache semantics on critical data, or modifying database indexes/migrations without backup/approval.