SEO Architecture & Web Performance Optimization

This document is the authoritative engineering specification for Search Engine Optimization (SEO), AI search agent indexing, Google Core Web Vitals (CWV) budgets, and caching topologies across the Debelu platform. Grounded directly in [debelu-marketing/next.config.js](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-marketing/next.config.js), [sitemap.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-marketing/app/sitemap.ts), [robots.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-marketing/app/robots.ts), [lighthouserc.json](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-marketing/lighthouserc.json), and image optimization pipelines, this specification establishes our digital discoverability and performance invariants.

---

1. Technical SEO Architecture (debelu-marketing)

debelu-marketing is the canonical public web portal at debelu.com. It is architected for maximum organic search crawlability, fast indexation of campus merchants, and structured AI search agent discovery.

graph TD
    SearchEngines[Google / Bing / Yandex Crawlers] --> Robots[robots.ts: Allow Storefronts & Block Admin]
    AIAgents[Gemini / Perplexity / ChatGPT Scrapers] --> LLMsTxt[llms.txt: Structured Machine-Readable Context]
    
    Robots --> Sitemap[sitemap.ts: Dynamic Multi-Campus Sitemap Index]
    Sitemap --> StaticRoutes[25 Static Pages: /about, /how-it-works, /pricing, /faq]
    Sitemap --> PublicStores[Public Vendor Stores: /store/[slug]]
    
    StaticRoutes --> JSONLD[Schema.org JSON-LD Structured Data]
    PublicStores --> JSONLD

1.1 Dynamic XML Sitemap Generation (app/sitemap.ts)

The sitemap dynamically crawls published vendor profiles and university landing pages from Supabase:

• Change Frequencies:
  • Homepage and campus landing pages: daily (priority: 1.0).
  • Public vendor stores (/store/:slug): weekly (priority: 0.8).
  • Help articles and legal disclosures: monthly (priority: 0.5).
• Timestamp Integrity: Inlines <lastmod> timestamps derived from the entity's updated_at column to ensure efficient search engine re-indexing.

1.2 Robots Policy (app/robots.ts)

// debelu-marketing/app/robots.ts
export default function robots() {
  return {
    rules: [
      {
        userAgent: '*',
        allow: ['/', '/store/*', '/legal/*', '/help/*', '/llms.txt'],
        disallow: ['/admin/*', '/auth/*', '/api/*', '/delete-account'],
      },
    ],
    sitemap: 'https://debelu.com/sitemap.xml',
  };
}

1.3 Schema.org JSON-LD Structured Data

Pages embed rich, structured metadata conforming to Schema.org standards:

• Marketplace Root: {"@type": "Organization", "name": "Debelu", "url": "https://debelu.com"}.
• Vendor Storefronts: {"@type": "Store", "name": "...", "areaServed": "University of Lagos"}.
• Product Listings: {"@type": "Product", "offers": {"@type": "Offer", "priceCurrency": "NGN", "price": "..."}}.
• FAQ Page: {"@type": "FAQPage", "mainEntity": [...]}.

1.4 AI Search Indexing Standard (/llms.txt)

Debelu implements the open llms.txt standard at https://debelu.com/llms.txt. It exposes a concise markdown summary of platform capabilities, closed-loop escrow guarantees, university campus hubs, and developer documentation to generative AI answer engines.

---

2. Storefront Metadata & PWA Optimization (apps/storefront)

While apps/storefront is a single-page application (SPA), it maintains strict discoverability and link-preview fidelity:

1. Dynamic OpenGraph & Twitter Cards: Utilizes react-helmet-async ([SEO.tsx](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/apps/storefront/src/components/SEO.tsx)) to inject dynamic page titles, descriptions, and canonical URLs when products or stores are shared over WhatsApp, Twitter, or Telegram.
2. PWA Manifest (public/manifest.json): Configures standalone mobile display mode, orientation locks, brand theme colors (#1B5E20), and high-resolution maskable app icons.

---

3. Core Web Vitals (CWV) Performance Budgets

Debelu enforces strict performance budgets audited via Lighthouse CI (lighthouserc.json) on every pull request:

graph LR
    subgraph CoreWebVitals [Google Core Web Vitals Thresholds]
        LCP["Largest Contentful Paint (LCP)<br/>Target: <= 2.2s (75th Percentile)"]
        INP["Interaction to Next Paint (INP)<br/>Target: <= 150ms (75th Percentile)"]
        CLS["Cumulative Layout Shift (CLS)<br/>Target: <= 0.05"]
    end

    subgraph Optimizations [Architectural Enablers]
        LCP --> R2CDN[Cloudflare R2 WebP/AVIF CDN + Inlined Critical CSS]
        INP --> Split[React 19 Lazy Routes + Lightweight Hugeicons]
        CLS --> Aspect[Explicit Image Aspect Ratios + Skeleton Loaders]
    end

3.1 Lighthouse CI Budget Thresholds (lighthouserc.json)

Audit Category	Minimum CI Passing Score	Action on Breach
Performance	$\ge 90$ / 100	PR blocked; assets audited for bundle size regressions.
Accessibility (a11y)	$\ge 95$ / 100	PR blocked; contrasts and focus rings audited.
Best Practices	$\ge 95$ / 100	PR blocked; console errors and HTTPS warnings resolved.
Search Engine Optimization (SEO)	$\ge 95$ / 100	PR blocked; missing meta tags or link titles corrected.

---

4. Image Optimization Pipeline & CDN Topology

Images represent the largest bandwidth consumer on mobile campus networks. Debelu uses an optimized multi-stage image pipeline:

sequenceDiagram
    autonumber
    participant Vendor as Merchant Browser
    participant API as debelu-backend / R2
    participant CDN as Cloudflare Edge CDN
    participant Client as Student Mobile Browser

    Vendor->>API: Uploads raw JPEG/PNG (Max 5 MB)
    API->>API: Validates MIME type & dimensions
    API->>API: Stores master asset in Cloudflare R2 bucket
    
    Client->>CDN: GET /cdn.debelu.com/products/img_123.jpg?w=640&format=webp
    CDN->>CDN: On-the-fly conversion to WebP / AVIF
    CDN-->>Client: Returns optimized 42 KB WebP image (Cache TTL: 30 days)

4.1 Next.js Image Component Configuration

• Modern formats enabled: image/avif, image/webp.
• Device size breakpoints: [640, 750, 828, 1080, 1200, 1920].
• Long-term edge cache: minimumCacheTTL: 2592000 (30 days).

---

5. Caching & Edge Content Delivery

Layer / Surface	Cache Engine	Invalidation Trigger / TTL
Public Store Pages	Next.js ISR (Incremental Static Regeneration)	Hourly revalidation (revalidate: 3600) or on product publish.
Storefront Static Assets	Cloudflare Pages Edge CDN	Immutable hash-stamped assets cached for 1 year (max-age=31536000, immutable).
Backend API Endpoints	Redis Cache Middleware (cacheMiddleware.ts)	Category lists: 3600s; Trending products: 60s; Search: Uncached (0s).
Client-Side Data	TanStack React Query v5	staleTime: 30_000 (30s); background refetches on network reconnect.

---

6. Document Revision History

Revision	Date	Lead Author	Scope of Changes	Status
1.0.0	2026-10-05	Principal Performance Engineer	Complete enterprise SEO and web performance specification covering dynamic sitemaps, JSON-LD, llms.txt, Core Web Vitals, and R2 image pipelines.	Active Living Standard