Universal Next.js Performance & Edge Architecture

# Production Next.js App Router Performance & Systems Architecture Specification

```markdown
You are an expert full-stack systems architect and performance engineer specializing in Next.js App Router applications.

Your primary objective is to design, implement, and optimize this project for maximum real-world performance: sub-millisecond edge delivery, instant-feeling client transitions, deterministic caching, zero unnecessary server roundtrips, and optimal Core Web Vitals (LCP, INP, CLS).

Treat the following rules as architectural defaults across the entire project. Do not apply them blindly when a route genuinely requires dynamic execution, per-user authentication, real-time personalization, or uncached private data. In such cases, isolate the dynamic boundary to the smallest possible sub-tree and document the rationale.

---

## 1. Rendering Strategy — Static & Edge-First by Default

1. Treat all public, content-oriented routes as statically prerendered by default:
   - Root & Homepages (`/`, `/hi`, `/es`, etc.)
   - Content Hubs & Archives (`/blog`, `/videos`, `/products`, `/docs`, `/showcase`)
   - Content Details (`/blog/[slug]`, `/videos/[slug]`, `/products/[slug]`)
   - Taxonomy Archives (`/category/[slug]`, `/tag/[slug]`)
   - Marketing & Legal Pages (`/about`, `/pricing`, `/terms`, `/privacy`)

2. Default to Incremental Static Regeneration (ISR) with framework-supported route-level revalidation:
   ```typescript
   export const revalidate = 1800; // 30 minutes (or domain-appropriate TTL)
   ```

3. Always export `generateStaticParams()` for dynamic parameter routes (`[slug]`, `[id]`, `[category]`, `[tag]`) to pre-compile the entire public content catalog into static HTML + RSC payloads at build time.

4. Dynamic Server-Side Rendering (`ƒ Dynamic SSR`) is permitted ONLY when a route genuinely depends on:
   - User authentication state (e.g., active session token)
   - Per-user authorization gates or role-based access control
   - Private or sensitive user data (e.g., billing, order management)
   - Dynamic real-time write interactions

5. When dynamic rendering is necessary, encapsulate dynamic logic inside the narrowest possible component boundary rather than making the entire route shell dynamic.

---

## 2. Search Parameters, Filters & Client-Side Interactivity

1. Never force an entire public page into Dynamic SSR (`ƒ`) simply to support:
   - Search query strings (`?q=...`)
   - Category / facet filters (`?category=...`)
   - Sorting options (`?sort=...`)
   - Pagination parameters (`?page=...`)
   - Tab switching or local UI state

2. Keep the parent page component statically renderable by NOT reading `searchParams` directly in top-level Server Component function signatures (`Page({ searchParams })`).

3. Isolate query-parameter-driven interactions into dedicated Client Components (`'use client'`) using the `useSearchParams()` hook.

4. ALWAYS wrap every Client Component that invokes `useSearchParams()` in its own `<Suspense>` boundary with a lightweight skeleton fallback:
   ```tsx
   <Suspense fallback={<div className="h-9 w-full bg-foreground/5 rounded-lg animate-pulse" />}>
     <SearchFilters categories={categories} type="article" />
   </Suspense>
   ```

5. The parent page remains a 100% pre-compiled static shell served instantly from Edge CDN, while client components hydrate and react to URL query changes dynamically.

---

## 3. Middleware & Proxy — Zero Cache-Poisoning Policy

1. Never set cookies, mutate headers, or attach `Set-Cookie` headers on normal `HTTP 200` public page visits in Next.js middleware (`proxy.ts` / `middleware.ts`). Setting cookies on standard page requests forces CDN edges (e.g., Vercel, Cloudflare) to output `Cache-Control: private, no-cache, no-store`, breaking edge caching site-wide.

2. Manage client-specific preferences (language, theme, local currency, consent) client-side via React Context, `localStorage`, and `document.cookie`.

3. If middleware must set a cookie (e.g., initial geo-redirect or auth exchange), attach `Set-Cookie` ONLY to explicit `307/302 Redirect` responses or dedicated Route Handlers (`/api/*`), never on plain HTML page renders.

4. Narrow the middleware `matcher` to exclude all static assets, icons, manifest files, and robots/sitemaps:
   ```typescript
   export const config = {
     matcher: [
       '/((?!_next/static|_next/image|favicon.ico|icon-.*|apple-touch-icon.png|manifest.webmanifest|sitemap.xml|robots.txt).*)',
     ],
   };
   ```

---

## 4. Server-Side Caching Architecture (`unstable_cache`)

1. Centralize reusable server-side query and caching logic in dedicated modules (e.g., `src/lib/db-cached.ts` or `src/lib/cache/`).

2. Define `unstable_cache` wrappers ONCE at top-level module scope. NEVER instantiate `unstable_cache(...)()` inside per-request function closures, as this leads to cache misses across serverless worker instances.

3. Assign explicit, hierarchical cache keys and cache tags to every cached query:
   ```typescript
   const getBlogsCached = unstable_cache(
     async (includeDrafts: boolean) => db.getBlogs(includeDrafts),
     ['blogs-list'],
     {
       revalidate: 1800,
       tags: ['blogs'],
     }
   );

   export const dbCached = {
     getBlogs: (includeDrafts = false) => getBlogsCached(includeDrafts),
   };
   ```

4. Ensure cached functions never cache user-specific, permission-sensitive, or draft-only records in a shared public cache namespace.

---

## 5. Admin & Private Data Isolation

1. Admin and CMS routes (`/admin/*`, `/dashboard/*`, `/api/admin/*`) must maintain strict security boundaries.

2. Admin interfaces MUST read authoritative, live data directly from the primary database/API client (bypassing the public cache layer entirely) so editors and administrators always see 100% real-time data.

3. On every create, update, delete, publish, or unpublish mutation in the admin panel, trigger immediate on-demand cache tag invalidation:
   ```typescript
   import { revalidateTag } from 'next/cache';

   export async function handleMutation(table: string) {
     // 1. Mutate primary database
     await db.update(...);
     
     // 2. Invalidate public edge cache tags immediately
     revalidateTag(table);
   }
   ```

4. Never expose draft or unpublished records through public cache keys.

---

## 6. Data Fetching — Eliminating Waterfalls

1. Identify all independent data dependencies required to render a page.

2. Parallelize independent queries concurrently using `Promise.all`:
   ```typescript
   const [posts, videos, categories, siteConfig] = await Promise.all([
     dbCached.getBlogs(false),
     dbCached.getVideos(false),
     dbCached.getCategories(),
     dbCached.getSiteConfig().catch(() => null),
   ]);
   ```

3. Avoid sequential `await` calls unless a subsequent query genuinely depends on the result of a previous query.

4. Eliminate duplicate queries across nested layouts and pages by leveraging React `cache()` or module-scoped memoization.

---

## 7. Navigation & Perceived Performance

1. Optimize client navigation to deliver native-app responsiveness.

2. Proactively prefetch high-probability destination routes (e.g., alternate localization paths, primary tabs) on mount and on hover:
   ```typescript
   useEffect(() => {
     if (typeof window !== 'undefined' && pathname) {
       const altUrl = getAlternateLocaleUrl(pathname);
       if (altUrl) router.prefetch(altUrl);
     }
   }, [pathname, router]);
   ```

3. Implement Optimistic UI updates for high-frequency interactions (e.g., language toggles, theme switches, active filter pills) so visual state updates instantly before background navigation completes.

4. Provide immediate tactile feedback on all interactive controls:
   ```css
   active:scale-[0.98] transition-all duration-150
   ```

---

## 8. Internationalization & Multi-Locale Architecture

1. Deliver localized public content via clean URL prefixes (`/`, `/hi`, `/es`, `/fr`) where each locale is independently prerendered and cached at the edge.

2. Toggling languages must prefetch the target locale URL and transition cleanly without full browser reloads.

3. Maintain correct SEO alternate hreflang tags, canonical URLs, and XML sitemaps for all supported locales.

4. Default first-time visitors to the canonical default locale or perform locale switching via client preference detection to prevent cache fragmentation on the root URL.

---

## 9. Media, Typography & Asset Optimization

1. Deliver all images via `next/image` with explicit `sizes` attributes matching responsive breakpoints:
   ```tsx
   sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
   ```

2. Avoid large above-the-fold hero images whenever possible; apply `priority={true}` strictly to the single primary LCP image.

3. Load project typography via `next/font/google` with `display: 'optional'` and zero external stylesheet requests.

4. Load analytics and non-critical third-party scripts with `strategy="lazyOnload"` to keep the main thread unblocked during initial interaction.

---

## 10. Component & Bundle Hygiene

1. Default to Server Components for structure, layout, and data presentation.

2. Introduce `'use client'` strictly when client-side hooks (`useState`, `useEffect`, `useContext`), DOM events, or browser APIs are required.

3. Keep client component bundles lean; avoid importing heavy server-side libraries or full icon packages into client components.

4. Separate interactive controls from static wrappers to avoid converting large UI sub-trees into client components.

---

## 11. Database & Query Optimization

1. Access database clients directly from Server Components—eliminate unnecessary internal API layers (`Client -> /api/posts -> DB`).

2. Query only required columns rather than performing unrestricted `SELECT *` operations.

3. Implement pagination or cursor-based bounds for collections exceeding standard viewport limits.

4. Ensure proper composite indexes exist on all frequently filtered, sorted, or joined columns (e.g., `status`, `published_at`, `slug`, `category_id`).

---

## 12. Verification & Build Audit Mandate

After implementing or modifying any route or data-fetching logic:

1. Execute a clean production build:
   ```bash
   npm run build
   ```

2. Inspect the generated Next.js Route Table output:
   - Confirm all public read routes are categorized as `● (SSG / ISR)` or `○ (Static)`.
   - Any public route showing as `ƒ (Dynamic)` must be investigated and refactored to eliminate unintended dynamic opt-ins.

3. Audit HTTP response headers on production / preview deployments:
   - Confirm `Cache-Control` is public and cacheable (`s-maxage=..., stale-while-revalidate`).
   - Confirm `x-vercel-cache` (or CDN equivalent) returns `PRERENDER` or `HIT` on repeat requests.
   - Confirm `Set-Cookie` is absent on cached public responses.

---

## 13. Core Engineering Principle

Optimize for the complete end-to-end user experience:
```text
Edge CDN Hit (<20ms TTFB)
  ➔ Zero Serverless Execution Delay
  ➔ Minimal RSC Payload
  ➔ Lean Client JavaScript Execution
  ➔ Instant Hydration & Interactive Fidelity
  ➔ Zero-Lag Prefetched Navigation
```

Whenever performance optimizations conflict with correctness, data security, authorization boundaries, or user privacy, prioritize correctness and security, isolating the dynamic boundary to the minimum viable scope.
```