Performance Playbook

This document replaces the old checklist/changelog with a living reference for how we monitor and improve ignitionstack.pro performance. It covers the observability pipeline (Lighthouse, Chrome DevTools, MCP automations), the tech-specific guardrails woven into ../src, and how to react when metrics regress.

Core Metrics & Benchmarks

Metric	Target	Tools
Largest Contentful Paint (LCP)	< 2.5s on 4G/CPU Slowdown 4x	Lighthouse CI, PageSpeed Insights
First Input Delay / Interaction to Next Paint	< 100ms	Chrome DevTools Performance panel, Web Vitals logger
Time to Interactive	< 3.5s	Lighthouse, DevTools trace flamegraph
Cumulative Layout Shift	< 0.1	Chrome Layout Shift overlay, Next Image layout hints
Bundle Size (main/app)	< 350 KB gz	npm run build:analyze (Webpack analyzer)
Server Response	< 200 ms p95	Supabase logs, Next.js telemetry

We enforce these through automated runs (Lighthouse CLI, Playwright/perf in CI) and manual spot-checks every release.

Observability Toolkit

Lighthouse & PageSpeed Insights

• Use npx lighthouse http://localhost:3000 --view --preset=desktop for local scoring.
• Cloud builds run Lighthouse in CI for /, /blog, /store, /chat with budgets.
• Export reports under ./performance-reports/ if they trigger action items.

Chrome DevTools

• Performance panel → record 20s session, look for long tasks >50ms, paint timings, network waterfalls.
• Coverage tab → identify unused CSS/JS on hero sections.
• Layers/Layout Shift overlays → confirm next/image placeholders handle LCP elements.

Supabase Insights

• For slow queries: supabase db logs --since 1h and Investigate EXPLAIN ANALYZE in the Dashboard SQL editor.
• Confirm indexes referenced in /content/guides/projects-setup.mdx exist; if not, add migrations.

MCP (Model Control Plane) Automations

• Use DevTools MCP script to run: npm run build:test + npm run e2e and capture performance telemetry before merging heavy features.
• MCP bots (documented in AI/) provide summary comments of lighthouse regressions on pull requests.

Architectural Guardrails

1. Data Fetching – every server query under src/app/server/** wraps Supabase calls in React cache() + tag-based unstable_cache. Mutations must call revalidateTag or revalidatePath so ISR caches stay fresh.
2. Rendering – src/app/[locale]/(pages) use Server Components by default. Client islands ("use client") exist only for interactive surfaces (chat, analytics, forms).
3. Assets – next/image everywhere, with sizes tuned per layout and priority on hero banners. Asset pipeline uses npm run optimize:images before release.
4. Styles – Tailwind theme tokens + globals.css reduce layout shift by ensuring height/spacing tokens align across breakpoints.
5. Network – next.config.ts sets stale-while-revalidate headers, caches fonts/images aggressively, and strips unused locales.
6. Scripts – next/script loads GA and Mixpanel only when NEXT_PUBLIC_APP_ENV !== 'development'; window.gtag lazily loads after painting.

Debugging Workflow

1. Reproduce – Run npm run dev + npm run build:test (if regression shows only in prod) and open Chrome DevTools.
2. Trace – Capture a performance recording; note largest long task and LCP element. Save the .json trace to /performance-traces/issue-[id].json.
3. Inspect Backend – Use Supabase dashboard metrics (RLS policies, query log) and pnpm supabase db show to profile slow endpoints.
4. Compare Bundles – npm run build:analyze and compare stats.html with previous release; ensure dynamic imports isolate heavy feature code.
5. Automate – If fix requires consistent monitoring (e.g., chat streaming), author an MCP script or GitHub action to guard the regression.

Optimization Playbook

Server Layer

• Caching: maintain React.cache + unstable_cache wrappers; keep TTL conservative (30–3600s) and tag names documented.
• Parallelism: Promise.all for independent fetches; never await sequentially unless results depend on each other.
• Partial hydration: rely on Server Components; avoid large JSON serialization by keeping data logic on the server.

Client Layer

• Scroll reveal: reuse IntersectionObserver from src/app/components/motion/scroll-reveal.tsx.
• Markdown & heavy components: wrap with React.memo and useMemo; lazily import large libraries.
• Forms: leverage custom hooks (useFormField, useAsyncAction) to minimize re-render chains.
• Images: provide placeholder="blur" and correct sizes attributes; store optimized assets under public/assets/....

Analytics & Monitoring

• Web Vitals logged via WebVitals component to GA4 + internal API; check /analytics/events for instrumentation specs.
• Playwright tests (src/app/test/e2e/tests/accessibility.spec.ts, navigation.spec.ts, etc.) ensure UI interactions stay within <100ms response budget.
• Use npm run e2e:debug with CPU throttling to reproduce field conditions.

When Metrics Regress

1. Open a tracking issue with the failing metric, screenshot/report, and impacted routes.
2. Add a checklist referencing observation tools (Lighthouse build hash, DevTools trace file, Supabase query ID).
3. Implement fix following layer guidelines above.
4. Prove improvement using the same tool (attach before/after). If regression was prevented by MCP automation, update scripts to guard the new path as well.

References

• Code-level Optimizations
• Asset Guidelines
• Testing Playbook
• Analytics Instrumentation
• AI MCP automations

Keep this page up to date whenever new diagnostic scripts, MCP tools, or architectural guardrails land so all contributors share the same performance toolbox.