================================================================================
DYNAMIC SEO IMPLEMENTATION PLAN - ClonifyNow (Next.js)
================================================================================
Prepared from a planning discussion. No code has been changed yet - this is a
reference document only. Every question the user asked during planning is
included below with the answer given, followed by the full step-by-step plan.


================================================================================
PART 1: GOAL
================================================================================

Make SEO metadata (title, description, Open Graph, Twitter card, robots,
canonical URL, JSON-LD structured data) editable from an admin panel instead
of hardcoded in each page.tsx file, without hurting site performance or SEO
ranking factors (Core Web Vitals / crawl reliability).

Current state: ~97 page.tsx files under src/app/(template_*)/*/page.tsx each
export a static `export const metadata: Metadata = {...}` object. The home
page (src/app/page.tsx) additionally has a hand-written JSON-LD `homeSchema`
object with Organization / Person / WebSite / WebPage nodes.

There is no admin panel and no CMS/database in this Next.js repo today. There
IS an existing external API client (src/lib/api.ts, using a `fetchApi<T>()`
helper against `NEXT_PUBLIC_API_URL`) already used for blogs and news, with
working dynamic-route precedents at src/app/blogs/[slug]/page.tsx and
src/app/news/[slug]/page.tsx (both use `generateMetadata`).

An earlier attempt at a generic "slug type architecture" (a config-driven
system for full page *content*, not just SEO, at
src/config/app-pages/* and src/app/slug_type_architecture_page/) was built
and then removed by the user during this conversation ("we didn't need
that"). This plan does NOT revive that system. It only makes SEO metadata
dynamic; page content/JSX stays exactly as hand-authored today.


================================================================================
PART 2: ALL QUESTIONS ASKED DURING PLANNING, WITH ANSWERS GIVEN
================================================================================

--------------------------------------------------------------------------------
Q1: "I want to make the SEO of all the pages dynamic... I have an admin
    panel, can we give the option to the user to enter the URL and the SEO
    data, and that data should be loaded in the page. What can we do, please
    let me know the implementation plan, do not make any changes."
--------------------------------------------------------------------------------
ANSWER GIVEN:
Researched the codebase and found the building blocks already exist but are
disconnected:
  - Next.js 16.3.4, App Router, `generateMetadata` fully supported.
  - src/lib/api.ts already has a working fetchApi<T>() client hitting an
    external backend.
  - Two working precedents: src/app/blogs/[slug]/page.tsx and
    src/app/news/[slug]/page.tsx, both dynamic [slug] routes with
    generateMetadata fetching remote data.
  - A half-built prototype of exactly this feature existed at
    src/app/slug_type_architecture_page/page.tsx with a SeoConfig/
    AppPageConfig type system in src/config/app-pages/*.
  - No CMS/DB/ORM packages in package.json - all data comes via fetch to the
    external API.
  - 97 page.tsx files across (template_*) route groups each hardcode
    `export const metadata`.

Initial proposed plan (6 steps): add an SEO endpoint on the backend; extend
src/lib/api.ts with getSeoBySlug(); consolidate the 97 static pages into
dynamic [slug] routes finishing the half-built prototype; use fallback-safe
generateMetadata (spread API data over defaults so nothing breaks if a slug
has no data yet); add a revalidation webhook so admin edits go live
immediately instead of waiting for a timed ISR interval; migrate
incrementally starting with one pilot template group, seeding the API with
today's hardcoded metadata first so nothing regresses.

--------------------------------------------------------------------------------
Q2: "I have removed the slug type pre-existing architecture, we didn't need
    that, now tell me what can we do."
--------------------------------------------------------------------------------
ANSWER GIVEN:
Confirmed on disk that slug_type_architecture_page/ and all of
src/config/app-pages/ (registry.ts, types.ts, shared/defaults.ts, and 5
page config files) were deleted. Since the generic content-config system is
gone, offered 3 options via a direct question to the user:
  1. Per-page generateMetadata() + a shared helper (keep all 97 page.tsx
     files as-is, each gets a ~3-line generateMetadata() calling one shared
     resolveMetadata(slug, defaults) helper).
  2. A central SEO lookup fetched once and injected via a shared
     layout-level mechanism.
  3. Rebuild a leaner version of the removed slug architecture (a real
     [slug] dynamic route, simpler than before).
User's own idea, given as the answer to this question, was a 4th path (see
Q3 below): call the API in the layout based on slug.

--------------------------------------------------------------------------------
Q3: "Can't we do something like we call the API in layout according to
    slug?"
--------------------------------------------------------------------------------
ANSWER GIVEN:
Technically possible, but with a real cost, because there is only ONE root
layout in this app (src/app/layout.tsx) covering every route.

How it would work: Next.js 16 renamed middleware.js to proxy.js (confirmed
breaking change via node_modules/next/dist/docs - this is exactly the kind
of change AGENTS.md warns about). A proxy.ts at the project root could set
an `x-pathname` request header on every request; the root layout's
`export const metadata` would become `generateMetadata()`, read that header
via `(await headers()).get("x-pathname")`, derive a slug, and fetch SEO data
for it. Page-level metadata always wins over layout-level for the same
fields, so every page's static `metadata` export would need to be deleted
for this to actually take effect.

THE CATCH: `headers()` is a request-time API. Using it anywhere in a route's
render tree (including inside generateMetadata) opts that ENTIRE route out
of static generation into full per-request dynamic rendering (confirmed via
node_modules/next/dist/docs/01-app/03-api-reference/04-functions/headers.md).
Because this sits in the ROOT layout, it would force EVERY route in the
whole app (home, blogs, news, all template pages) into SSR-per-request,
not just the 97 clone pages. That's a real performance/SEO regression
(slower TTFB, more server load, and it undermines the Core Web Vitals
ranking benefit static generation gives you).

Alternative given: route `params` (from a real [slug] segment) do NOT
trigger this loss of static generation - generateStaticParams + a
`revalidate` window keeps pages statically generated and incrementally
refreshed, no proxy.ts/headers() needed. This does not require reviving the
removed generic content-config system - only the ROUTE would be
slug-based; page content can stay as plain components.

User was asked to choose between: (1) per-slug generateStaticParams route
[recommended], (2) layout + proxy/headers accepting full dynamic
rendering, or (3) per-page generateMetadata + shared helper, no routing
changes.

--------------------------------------------------------------------------------
Q4: "For SEO which is more good: SSR, SSG?"
--------------------------------------------------------------------------------
ANSWER GIVEN:
SSG (with ISR) is better than SSR for this use case, for concrete reasons,
not just convention:
  - Both SSR and SSG are equally crawlable (both send fully-rendered HTML;
    this isn't the old client-side-rendering SEO problem).
  - Speed is a direct Google ranking factor (Core Web Vitals: LCP, INP,
    CLS). SSG serves pre-built HTML from cache/CDN, near-instant. SSR runs
    server compute AND an external API call on every single request,
    including every crawl, adding real latency each time.
  - Reliability affects crawl budget. With SSR, every crawl depends on the
    origin server and the external SEO API both being up and fast at that
    exact moment. Static pages don't have this failure mode.
  - You do not need true per-request SSR to get "editable without
    redeploy." Incremental Static Regeneration (ISR) gives static-speed
    pages that regenerate in the background on a timer or on-demand via a
    webhook the admin panel calls after saving - the specific page rebuilds
    within seconds, without a full site redeploy and without paying the
    SSR cost on every pageview forever.
  - SSR only wins when content must differ per-request in ways that cannot
    be predicted ahead of time (personalization, live prices). Occasional
    admin-edited SEO fields are the textbook ISR case, not that.

Conclusion: use the per-page/per-route generateMetadata + ISR path, not the
layout/proxy/headers SSR path.

--------------------------------------------------------------------------------
Q5: "Is there any other production-level approach that other websites have
    used?"
--------------------------------------------------------------------------------
ANSWER GIVEN:
Yes, the ISR + webhook approach IS the standard production pattern, not
something bespoke. Named concretely:
  1. CMS-driven ISR + webhook revalidation - the dominant pattern used by
     large Next.js marketing sites (public Vercel case studies include
     Tripadvisor, Washington Post, Ryanair-scale sites): CMS/admin saves ->
     fires a webhook -> a Route Handler calls revalidatePath() or
     revalidateTag() -> that one page rebuilds in the background, live
     within seconds.
  2. Tag-based revalidation (revalidateTag) instead of path-based
     (revalidatePath) - more scalable once there are many pages, or you
     want to invalidate a group at once (e.g. every page sharing one OG
     image). Costs nothing extra to set up from day one.
  3. Edge Config / KV store (Vercel Edge Config, Cloudflare KV) for the SEO
     data itself - a globally-replicated, sub-millisecond read-optimized
     store, used by some production sites so even a per-request
     generateMetadata call barely costs anything. Not necessary at ~97
     pages; worth it if this later grows to thousands of pages or you want
     sub-second propagation without waiting on the ISR regenerate cycle.
  4. Single source of truth beyond just <title>/<meta description> - mature
     setups feed the same admin-entered data into sitemap.xml
     (app/sitemap.ts), robots.txt, and JSON-LD structured data too, not
     just page meta tags.
  5. Named the closest real-world parallel: the CURRENT live site (before
     this Next.js rebuild) is WordPress + Elementor, and this exact
     problem - per-page admin-editable title/description/OG - is what
     Yoast SEO / RankMath solve on WordPress. This isn't a new problem;
     it's rebuilding Yoast's capability for a custom Next.js + API stack.
     Yoast's editor UX (title/description with live character-count + SERP
     preview, OG image picker, canonical override, noindex toggle) is a
     good reference for what fields the admin form should have.

Conclusion given: the previously discussed plan already matches production
practice. Only upgrade suggested: use revalidateTag over revalidatePath
from day one; keep Edge Config in mind as a later scaling step, not a v1
requirement.

--------------------------------------------------------------------------------
Q6: "Tell me how my folder structure will change, and we use these things
    [pointing at the home page's Metadata + homeSchema JSON-LD object] for
    SEO of our pages - how will it look, what should we enter from the
    admin panel, what should we store in the DB, please let me know every
    detail."
--------------------------------------------------------------------------------
ANSWER GIVEN:
First corrected an earlier implication: static-generation-safety isn't
about having a dynamic [slug] route - it's specifically about avoiding
headers()/cookies(). A plain per-page async generateMetadata() that does a
normal fetch() (no route restructuring at all) is ALSO fully static/ISR
compatible. So folder structure barely needs to change:

    src/
      lib/
        api.ts          <- add getSeoBySlug(slug)
        seo.ts           <- NEW: resolveMetadata(), buildJsonLd(),
                             shared Organization/Person/WebSite constants
      app/
        api/
          revalidate-seo/route.ts   <- NEW: webhook the admin panel calls
        page.tsx                     <- metadata export -> generateMetadata()
        (template_five)/
          airbnb-clone/page.tsx      <- metadata export -> generateMetadata();
                                          JSX body unchanged
          uber-eats/page.tsx         <- same treatment, repeated per page
          ...

No new route segments, no [slug] folders, no moving page content into a
separate registry. Every page keeps its own file and JSX exactly as-is;
only the `export const metadata = {...}` block is replaced.

DB schema proposed, per page, keyed by slug (see PART 4 below for the full
version) - based on the real fields used in the home page's metadata and
homeSchema. Fields that are IDENTICAL across every page in homeSchema
(Organization node, Person/founder node, WebSite node, openGraph.siteName /
locale / type, robots' exotic sub-fields, twitter.card) are deliberately
NOT stored per page - they live once as constants in src/lib/seo.ts, the
same way Yoast repeats one Organization/WebSite @id reference across every
page and only changes the WebPage node.

Admin panel field list and code sketch given - see PART 5 and PART 6 below.

--------------------------------------------------------------------------------
Q7: "What if we do not keep any fallbacks? And doesn't keeping it dynamic
    (calling the DB) instead of static in the page cause a performance
    issue?"
--------------------------------------------------------------------------------
ANSWER GIVEN (two separate questions):

(a) On dropping fallbacks entirely:
Distinguished two different things called "fallback":
  1. Per-page duplicated hardcoded content (today's metadata block, kept
     alongside the DB version) - fine to drop entirely. No reason to
     maintain the same title/description in two places once the DB is the
     source of truth.
  2. A safety net for when the fetch fails or a slug has no row yet -
     risky to drop entirely. If generateMetadata throws (API down, network
     blip, slug typo with no DB row) and nothing catches it, the error does
     not just mean "missing meta tags" - it fails the ENTIRE page render.
     generateMetadata errors propagate like any Server Component error.
     A wobble in the admin backend would take down the actual page, not
     just its SEO.
  There is also a quieter cost: a page with genuinely no title/description
  (e.g. a new clone page shipped before its SEO row is created in the
  admin panel - an easy thing to forget) gets an auto-generated Google
  title and a randomly-selected meta description snippet - worse, not
  fatal.
  RECOMMENDATION GIVEN: drop the per-page duplication, keep ONE generic
  sitewide safety net (not 97 hand-written fallbacks), e.g.
  { title: "ClonifyNow", description: "Ready-made clone app solutions." }
  wrapped in a .catch() - a one-line insurance policy, not content to
  maintain.

(b) On performance of calling the DB from the page:
No meaningful performance issue for real visitors, as long as the plan
stays on ISR (not full SSR / headers()-based rendering, which was already
ruled out in Q3/Q4). Mechanism explained concretely:
  - With ISR, the DB/API call happens at BUILD TIME and at REGENERATION
    TIME only - never on an actual visitor's request. A visitor gets a
    pre-rendered static HTML file from cache, same speed as a fully
    hardcoded page.
  - Next.js ISR uses stale-while-revalidate: when a page becomes stale
    (past its revalidate window), the NEXT visitor still gets the old
    cached HTML instantly; Next regenerates in the background afterward
    for the visitor after that. Nobody ever waits on the DB call as part
    of a normal pageload.
  - The only person who could feel DB latency is triggering an on-demand
    revalidatePath/revalidateTag call from the admin panel itself after
    Save - an internal admin action, not a customer pageload.
  - The one real cost is at BUILD TIME: `next build` now does ~97 API
    calls instead of zero, extending CI build duration - not anything a
    visitor or Google's crawler experiences.
  Reiterated: the performance risk the user was picturing is real, but it
  is the risk of the SSR/headers()/proxy.ts route already ruled out - this
  plan deliberately avoids that path.

--------------------------------------------------------------------------------
Q8 (this request): "Make me a complete implementation plan step by step for
    each panel and create a txt file with all the questions I have asked
    with their answers and any problems we can face."
--------------------------------------------------------------------------------
ANSWER: this document.


================================================================================
PART 3: FOLDER STRUCTURE CHANGES
================================================================================

BEFORE (current state):

    src/
      app/
        page.tsx                          - static metadata + hand-written
                                             homeSchema JSON-LD object
        layout.tsx                         - static sitewide metadata
        blogs/[slug]/page.tsx              - ALREADY dynamic, generateMetadata
                                             fetching from API (unaffected
                                             by this plan)
        news/[slug]/page.tsx               - ALREADY dynamic, same as above
        (template_five)/
          airbnb-clone/page.tsx            - static metadata + JSX content
          uber-eats/page.tsx               - static metadata + JSX content
          blacklane-clone/page.tsx         - ...
          ... (97 page.tsx files total across all (template_*) groups)
      lib/
        api.ts                             - fetchApi<T>(), blog/news helpers

AFTER (this plan):

    src/
      app/
        api/
          revalidate-seo/
            route.ts                       - NEW: webhook, admin panel calls
                                             this after saving SEO data
        page.tsx                           - CHANGED: generateMetadata()
                                             replaces static metadata;
                                             buildJsonLd() replaces homeSchema
        layout.tsx                         - unchanged (stays static sitewide
                                             defaults; NOT converted to
                                             generateMetadata - see Q3, this
                                             was rejected because it forces
                                             the whole site into SSR)
        blogs/[slug]/page.tsx              - unchanged
        news/[slug]/page.tsx               - unchanged
        (template_five)/
          airbnb-clone/page.tsx            - CHANGED: metadata export ->
                                             generateMetadata(); JSX body
                                             below it is UNTOUCHED
          uber-eats/page.tsx               - same treatment
          ... (all 97, same minimal edit each - no file moves, no new
               folders, no [slug] dynamic segments)
      lib/
        api.ts                             - CHANGED: + getSeoBySlug(slug)
        seo.ts                             - NEW: resolveMetadata(),
                                             buildJsonLd(), shared
                                             Organization/Person/WebSite
                                             JSON-LD constants, sitewide
                                             OG/Twitter/robots defaults

Nothing moves. No [slug] catch-all route. No revival of the removed
config-driven content system. The only structural addition is one new
lib file and one new API route.


================================================================================
PART 4: DATABASE SCHEMA (what gets stored, per page, keyed by slug)
================================================================================

    interface PageSeo {
      slug: string;               // "airbnb-clone", "" for home - the DB key
      path: string;                // "/airbnb-clone" - canonical URL path
      title: string;
      description: string;
      keywords?: string;
      canonical?: string;          // optional override; default = SITE_URL + path
      robots?: {
        index?: boolean;           // default true
        follow?: boolean;          // default true
      };
      openGraph?: {
        title?: string;            // falls back to `title`
        description?: string;      // falls back to `description`
        image?: string;
      };
      twitter?: {
        title?: string;
        description?: string;
        image?: string;
      };
      schema?: {
        type?: string;             // "WebPage" | "Product" | "Service" | "FAQPage"
        name?: string;              // falls back to `title`
        description?: string;       // falls back to `description`
      };
      status?: "draft" | "published";
      updatedAt?: string;
      updatedBy?: string;
    }

Deliberately NOT stored per page (kept as sitewide constants in
src/lib/seo.ts instead, since they are identical across every page in the
existing home page's homeSchema, and re-entering them 97 times would only
invite typos/drift):
  - The Organization node (name, logo, founder, address, sameAs socials,
    founding date, email, phone)
  - The Person/founder node, the WebSite node
  - openGraph.siteName, openGraph.locale, openGraph.type
  - robots' exotic sub-fields (max-snippet, max-video-preview,
    max-image-preview, the nested googleBot object)
  - twitter.card ("summary_large_image")

This mirrors how Yoast (the site's current WordPress SEO plugin) actually
works: it repeats the same Organization/WebSite @id reference on every
page's JSON-LD graph and only the page-specific WebPage node changes.


================================================================================
PART 5: ADMIN PANEL - WHAT TO BUILD, PER PAGE
================================================================================

A single "Edit SEO" form per page/slug, with:
  1. Slug/URL picker (dropdown of known routes, or free text)
  2. SEO Title - with a live character counter (Google truncates ~60 chars)
  3. Meta Description - counter (~155-160 chars)
  4. Keywords (optional/legacy - low ranking value today, kept since
     existing pages already have it)
  5. Canonical URL override (optional - blank = auto-derived from slug)
  6. Robots: two toggles only - "Allow indexing" / "Allow following links"
     (the exotic sub-fields stay hardcoded sitewide, not exposed here)
  7. Open Graph: title override, description override, image upload/URL
  8. Twitter: same three fields, or a "same as Open Graph" checkbox
  9. JSON-LD type dropdown (WebPage / Product / Service / FAQPage) -
     optional/advanced field
 10. A live SERP + social-share preview (like Yoast/RankMath show) - nice
     UX touch, not required for v1
 11. Save button -> writes the PageSeo doc -> calls the revalidation
     webhook for that one slug only


================================================================================
PART 6: HOW IT RENDERS BACK INTO THE PAGE (code sketch, not yet written)
================================================================================

    // src/lib/seo.ts
    export async function resolveMetadata(
      slug: string,
      genericFallback: Metadata   // ONE sitewide generic fallback, not
                                    // per-page duplicated content - see
                                    // Q7(a) above
    ): Promise<Metadata> {
      const seo = await getSeoBySlug(slug).catch(() => null);
      if (!seo) return genericFallback;
      return {
        title: seo.title,
        description: seo.description,
        keywords: seo.keywords,
        alternates: { canonical: seo.canonical ?? `${SITE_URL}${seo.path}` },
        robots: {
          index: seo.robots?.index ?? true,
          follow: seo.robots?.follow ?? true,
          ...GOOGLEBOT_DEFAULTS,             // sitewide constant
        },
        openGraph: {
          ...OG_DEFAULTS,                     // sitewide constant
          title: seo.openGraph?.title ?? seo.title,
          images: [{ url: seo.openGraph?.image ?? DEFAULT_OG_IMAGE }],
        },
        twitter: {
          ...TWITTER_DEFAULTS,                // sitewide constant
          title: seo.twitter?.title ?? seo.title,
        },
      };
    }

    export function buildJsonLd(slug: string, seo: PageSeo) {
      return {
        "@context": "https://schema.org",
        "@graph": [
          ...ORG_JSONLD_GRAPH,   // Organization + Person + WebSite (shared)
          {
            "@type": seo.schema?.type ?? "WebPage",
            "@id": `${SITE_URL}${seo.path}#webpage`,
            url: `${SITE_URL}${seo.path}`,
            name: seo.schema?.name ?? seo.title,
            description: seo.schema?.description ?? seo.description,
            isPartOf: { "@id": `${SITE_URL}/#website` },
            about: { "@id": `${SITE_URL}/#organization` },
          },
        ],
      };
    }

Each page (example: airbnb-clone/page.tsx):

    export async function generateMetadata(): Promise<Metadata> {
      return resolveMetadata("airbnb-clone", GENERIC_FALLBACK);
    }

    export default async function AirbnbClonePage() {
      const seo = await getSeoBySlug("airbnb-clone").catch(() => null);
      return (
        <main>
          {seo && (
            <script
              type="application/ld+json"
              dangerouslySetInnerHTML={{
                __html: JSON.stringify(buildJsonLd("airbnb-clone", seo)),
              }}
            />
          )}
          {/* existing JSX, unchanged */}
        </main>
      );
    }

Revalidation: `export const revalidate = 3600;` gives hourly auto-refresh
for free. The `/api/revalidate-seo` Route Handler (admin panel calls it
after Save, protected by a secret token, using `revalidateTag('seo:'+slug)`)
gives near-instant propagation on top of that.


================================================================================
PART 7: STEP-BY-STEP IMPLEMENTATION ORDER
================================================================================

STEP 1 - Backend (admin panel's own API, outside this Next.js repo)
  1a. Add a `page_seo` collection/table keyed by slug, matching the
      PageSeo shape in PART 4.
  1b. Add endpoints: GET /page-seo/:slug, PUT /page-seo/:slug (or
      equivalent for whatever backend framework the admin API uses),
      plus a list endpoint for the admin UI's page picker.
  1c. Add a webhook-friendly way for the admin panel's Save action to also
      call this Next.js app's /api/revalidate-seo (step 4) with the slug
      and a shared secret.

STEP 2 - This Next.js repo: data layer
  2a. Add `getSeoBySlug(slug: string): Promise<PageSeo | null>` to
      src/lib/api.ts, following the exact pattern of the existing
      getBlogBySlugFromApi function.
  2b. Create src/lib/seo.ts: SITE_URL constant, ORG_JSONLD_GRAPH constant
      (Organization + Person + WebSite nodes, copied from the current
      homeSchema and de-duplicated), OG_DEFAULTS / TWITTER_DEFAULTS /
      GOOGLEBOT_DEFAULTS constants, resolveMetadata(), buildJsonLd().

STEP 3 - Pilot migration (ONE page first, to prove the pattern)
  3a. Pick one page - recommend src/app/(template_five)/airbnb-clone/
      page.tsx since it is the page already being actively worked on in
      this conversation.
  3b. Replace its `export const metadata = {...}` with
      `export async function generateMetadata()` calling resolveMetadata().
  3c. Add `export const revalidate = 3600;` (or chosen interval).
  3d. Manually create one row in the admin backend for this slug (seed
      data) so the pilot has something real to fetch.
  3e. Verify: `npx tsc --noEmit`, `npx eslint`, then `npm run build` to
      confirm it still statically generates (check the build output for
      this route - it should be marked as Static/ISR, not Dynamic).
  3f. Verify the rendered <head> tags and JSON-LD script tag in the
      browser match what was entered in the admin backend.

STEP 4 - Revalidation webhook
  4a. Create src/app/api/revalidate-seo/route.ts: a POST handler that
      checks a shared-secret header/token, reads `slug` from the request
      body or query string, calls `revalidateTag('seo:' + slug)` (see
      note in STEP 4b), and returns 200/401 accordingly.
  4b. Decide revalidatePath vs revalidateTag: if getSeoBySlug's fetch()
      call is tagged (`fetch(url, { next: { tags: ['seo:' + slug] } })`),
      use revalidateTag for more precise invalidation, per the Q5 answer
      above (this is the "upgrade over the base plan" recommendation).
  4c. Wire the admin backend's Save action (from STEP 1c) to call this
      endpoint after every successful save.
  4d. Test: edit the pilot page's SEO in the admin panel, save, confirm
      the live page updates within seconds without a full redeploy.

STEP 5 - Seed existing data (avoid regressions)
  5a. Write a one-time script that reads the current hardcoded `metadata`
      object out of each of the 97 page.tsx files (or simply re-type them
      by hand into the admin panel, given there are 97 and this is a
      one-time cost either way) and POSTs them into the new page_seo
      backend collection as the initial rows.
  5b. This guarantees no page's SEO regresses to the generic fallback the
      moment its file is migrated.

STEP 6 - Roll out to the remaining 96 pages
  6a. Repeat STEP 3b/3c for each remaining page.tsx across all
      (template_*) groups - each is the same small, mechanical edit.
  6b. Do this in small batches (e.g. per template group) and re-run
      `npx tsc --noEmit` + `npx eslint` + `npm run build` after each
      batch, not all 97 at once, to keep any regression easy to bisect.
  6c. Also migrate src/app/page.tsx (home) and src/app/layout.tsx's
      sitewide defaults can stay static (layout.tsx is intentionally NOT
      converted - see PART 3 "AFTER" notes and Q3 above).

STEP 7 - Extend beyond meta tags (optional, later)
  7a. Feed the same PageSeo data into app/sitemap.ts if/when one exists,
      so canonical URLs and last-modified dates stay consistent with the
      admin-entered data.
  7b. Consider Edge Config / KV (see Q5, point 3) only if the page count
      grows substantially or sub-second propagation becomes a real
      requirement - not needed for the current ~97-page scale.


================================================================================
PART 8: PROBLEMS / RISKS TO WATCH FOR
================================================================================

1. generateMetadata throwing crashes the whole page, not just its SEO.
   MITIGATION: always wrap getSeoBySlug() in resolveMetadata() with
   .catch(() => null) and a generic sitewide fallback (see Q7a). Never
   let a metadata fetch failure become a page failure.

2. Forgetting to create an admin-panel SEO row for a brand-new page.
   The page would render with only the generic sitewide fallback title/
   description until someone adds a row. MITIGATION: make "add SEO row"
   part of the page-launch checklist, and/or have the admin panel flag
   pages with no SEO row as a visible warning list.

3. Using headers()/cookies() anywhere in the metadata path silently
   forces that whole route into dynamic (SSR) rendering, losing the ISR/
   static-generation performance benefit this entire plan is built
   around. MITIGATION: keep generateMetadata() to plain fetch() calls
   only, driven by the page's own known slug (a literal string per file),
   never by request headers or the URL at request time.

4. Next.js 16 renamed middleware.js to proxy.js (a real breaking change
   from what most training data / tutorials assume). If anyone later adds
   middleware for an unrelated reason (auth, redirects, etc.), it must be
   named proxy.ts, exporting a `proxy` function, not `middleware.ts`/
   `export function middleware`.

5. Build time grows. next build now performs ~97 API calls instead of
   zero. If the admin backend is slow or briefly unavailable during a
   deploy, the build could fail or take much longer. MITIGATION: keep
   each getSeoBySlug() call individually try/caught (already covered by
   #1's mitigation), and consider a reasonable fetch timeout so one slow
   endpoint cannot stall the entire build.

6. Stale content window. Even with the on-demand webhook, there's a brief
   window between "admin clicks Save" and "revalidation webhook finishes
   processing" where the old page is still being served. This is normal
   and expected for ISR (stale-while-revalidate) - not a bug - but worth
   setting expectations with whoever uses the admin panel: changes are
   "live within seconds," not literally instant.

7. JSON-LD correctness. Structured data errors (wrong @type, missing
   required fields for the chosen schema.org type) don't break the page
   visually but can cause Google Search Console to flag "rich result"
   errors. MITIGATION: keep the JSON-LD `type` dropdown in the admin
   panel limited to a small, tested set of schema.org types (WebPage,
   Product, Service, FAQPage) rather than free text, and validate a
   sample of pages with Google's Rich Results Test after rollout.

8. Revalidation webhook security. The /api/revalidate-seo endpoint must
   require a secret token (e.g. a header checked against an env var) -
   without this, anyone who discovers the URL could trigger unlimited
   revalidations (a minor DoS vector against your own build/regeneration
   capacity) or, if you ever key rows by more than slug, potentially
   probe which slugs exist.

9. Migrating 97 files is mechanical but still 97 individual edits and
   97 individual verifications. Recommend batching by template group
   (STEP 6b) rather than attempting all pages in one pass, so a mistake
   in one batch doesn't block or get lost among the others.

10. Duplicate-content / inconsistent canonical risk. If the `canonical`
    field is left blank for a page whose slug doesn't exactly match its
    real URL path (e.g. trailing slash differences, or a page reachable
    at more than one route), the auto-derived `SITE_URL + path` default
    could point at the wrong URL. MITIGATION: double-check the `path`
    field stored per row actually matches the live route exactly during
    STEP 5 seeding.


================================================================================
END OF DOCUMENT
================================================================================