Marketing & SEO Web Application (`debelu-marketing`)

This document is the authoritative engineering specification for debelu-marketing, the public-facing Next.js 16 web application hosted at debelu.com. Grounded directly in [next.config.js](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-marketing/next.config.js), [package.json](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-marketing/package.json), the App Router hierarchy in app/, and edge instrumentation, this specification details the search engine optimization (SEO) architecture, authentication entrypoints, origin routing matrices, server-side data fetching, and web performance engineering.

1. System Overview & Monorepo Topology

debelu-marketing is the canonical public web portal for Debelu, serving brand marketing, merchant acquisition, campus community guides, legal disclosures, dynamic public vendor stores, authentication gateways, and AI search indexing (llms.txt). It is deployed globally on the Vercel Edge Network at debelu.com.

mermaid

graph TD
    User[Internet Traffic / Organic Search / Campus Social] --> CDN[Vercel Edge Network: debelu.com]
    
    subgraph debelu_marketing [debelu-marketing App Router Topology]
        EdgeHeaders[Edge Headers & Canonical Redirects: next.config.js]
        EdgeHeaders --> PublicRoutes[Public Pages: /about, /pricing, /how-it-works, /trust]
        EdgeHeaders --> AuthFlow[Auth Gateway: /login, /register, /auth]
        EdgeHeaders --> PublicStores[SEO Store Pages: /store/:slug, /stores]
        EdgeHeaders --> SEOCrawler[Search Indexing: /sitemap.xml, /robots.txt, /llms.txt]
        
        AuthFlow -->|Session Handoff| StorefrontRedirect[Redirect -> app.debelu.com/buy]
    end

    subgraph OriginRouting [Cross-Domain Redirection Matrix]
        LegacyApp["/app/:path*"] -->|307 Redirect| SFApp["https://app.debelu.com/buy/:path*"]
        LegacyVendor["/vendor/:path*"] -->|307 Redirect| SFVendor["https://app.debelu.com/sell/:path*"]
        LegacyAdmin["/admin/:path*"] -->|307 Redirect| AdminSite["https://admin.debelu.com/admin/:path*"]
    end

    EdgeHeaders --> LegacyApp
    EdgeHeaders --> LegacyVendor
    EdgeHeaders --> LegacyAdmin

    subgraph UpstreamServices [Data & Shared Assets]
        Core["@debelu/core: Shared Types & Supabase Client"]
        UI["@debelu/ui: Shared Design Tokens & Branding"]
        Sentry["@sentry/nextjs: Server, Edge & Client Telemetry"]
    end

    PublicRoutes --> UI
    PublicStores --> Core
    AuthFlow --> Core
    debelu_marketing --> Sentry

1.1 Technical Stack & Core Invariants

Runtime & Framework: Next.js 16.x (App Router) running React 19.x with React Server Components (RSC) and Server Actions.
Deployment Platform: Vercel Edge Network with automatic preview environments per PR.
Image Pipeline: Next.js Image Optimization with modern format conversion (image/avif, image/webp), remote pattern whitelisting (*.supabase.co, cdn.debelu.com, images.unsplash.com), and 30-day edge cache TTL (minimumCacheTTL: 2592000).
Telemetry: @sentry/nextjs with full lifecycle instrumentation across server, edge, and browser runtimes (instrumentation.ts, sentry.server.config.ts, sentry.edge.config.ts).
Styling: Tailwind CSS v4 + @tailwindcss/postcss utilizing design tokens transpile-linked from @debelu/ui.

2. Cross-Domain Routing & Origin Segregation Matrix

debelu-marketing is the apex domain owner (debelu.com). It acts as the canonical entry point for all legacy URLs, routing users to strictly isolated domain origins while preserving path arguments and query parameters:

mermaid

flowchart TD
    ApexReq[Request to debelu.com] --> Match{Path Prefix}
    Match -->|/app or /app/:path*| R1["307 Redirect -> https://app.debelu.com/buy/:path*"]
    Match -->|/vendor or /vendor/:path*| R2["307 Redirect -> https://app.debelu.com/sell/:path*"]
    Match -->|/admin or /admin/:path*| R3["307 Redirect -> https://admin.debelu.com/admin/:path*"]
    Match -->|/privacy| R4["301 Permanent -> /legal/privacy"]
    Match -->|/terms| R5["301 Permanent -> /legal/terms"]
    Match -->|/support/*| R6["301 Permanent -> /help/*"]
    Match -->|Public Marketing Path| RSC[Render Next.js React Server Component]

2.1 Canonical Redirect Table (from `next.config.js`)

Inbound Path	HTTP Status	Target Destination	Architectural Purpose
`/app`	`307 Temporary`	`https://app.debelu.com/buy`	Routes legacy buyer bookmarks to isolated storefront origin.
`/app/:path*`	`307 Temporary`	`https://app.debelu.com/buy/:path*`	Preserves product and order deep-links during domain transition.
`/vendor`	`307 Temporary`	`https://app.debelu.com/sell`	Routes legacy vendor bookmarks to isolated storefront portal.
`/vendor/:path*`	`307 Temporary`	`https://app.debelu.com/sell/:path*`	Preserves vendor management links during domain transition.
`/admin`	`307 Temporary`	`https://admin.debelu.com/admin/overview`	Enforces strict administrative origin isolation.
`/admin/:path*`	`307 Temporary`	`https://admin.debelu.com/admin/:path*`	Hard redirect for all staff tools.
`/privacy`	`301 Permanent`	`/legal/privacy`	Canonical NDPA privacy policy URL structure.
`/terms`	`301 Permanent`	`/legal/terms`	Canonical Terms of Service URL structure.
`/support`	`301 Permanent`	`/help`	Customer service help desk unification.
`/help/faq`	`301 Permanent`	`/faq`	Frequently Asked Questions directory simplification.

3. App Router Directory Structure & Page Inventory

The marketing codebase utilizes the Next.js 16 App Router (app/ directory), leveraging nested layouts, streaming server components, and route handlers:

debelu-marketing/app/
├── layout.tsx                              # Root HTML shell, fonts, meta tags, Sentry provider
├── page.tsx                                # High-conversion brand homepage
├── providers.tsx                           # Client context wrappers (Theme, I18n, Toast)
├── robots.ts                               # Dynamic robots.txt generation
├── sitemap.ts                              # Dynamic multi-campus sitemap index
├── error.tsx                               # Root error boundary with retry triggers
├── not-found.tsx                           # Brand 404 page with navigation fallbacks
├── loading.tsx                             # Global skeleton loader
├── (public marketing pages)
│   ├── about/                              # Company mission, team, and university partnerships
│   ├── brand/                              # Brand asset downloads, press kits, logos
│   ├── buy/                                # Campus marketplace buyer landing page
│   ├── careers/                            # Open student ambassador and engineering roles
│   ├── changelog/                          # Platform feature release log
│   ├── contact/                            # University administration contact & support forms
│   ├── delete-account/                     # Statutory NDPA/GDPR account erasure intake
│   ├── faq/                                # Categorized buyer and vendor FAQs
│   ├── help/                               # Comprehensive customer help center
│   ├── how-it-works/                       # Visual guide to escrow protection & PIN handoffs
│   ├── legal/                              # Terms, NDPA Privacy, Cookie Policy, Guidelines
│   ├── nduzi/                              # Deep dive on the Nduzi campus AI assistant
│   ├── press/                              # Press releases and media coverage
│   ├── pricing/                            # Transparent vendor commission structure
│   ├── security/                           # Trust, defense-in-depth, and bounty disclosures
│   ├── sell/                               # Student vendor acquisition and onboarding guide
│   ├── status/                             # Public platform operational uptime mirror
│   └── trust-and-safety/                   # Fraud prevention, ChatGuard, and escrow mechanics
├── (auth entrypoints)
│   ├── login/                              # Sign-in portal with email and social OAuth
│   ├── register/                           # Buyer and vendor registration flows
│   └── auth/                               # Callback handlers and session handoff logic
├── (dynamic seo pages)
│   ├── store/[slug]/                       # Public SSR vendor storefront pages
│   └── stores/                             # Public campus vendor directory
└── llms.txt/
    └── route.ts                            # Structured AI context document for LLM scrapers

4. Authentication & Cross-App Session Handoff

The marketing site serves as the unified authentication gateway for consumer accounts. When a user authenticates via password, OTP, or Google OAuth, the session is handed off to the isolated storefront application via a secure token transfer:

mermaid

sequenceDiagram
    autonumber
    participant Buyer as Student Browser
    participant MktAuth as debelu.com/login
    participant Supa as Supabase Auth Gateway
    participant Storefront as app.debelu.com (Storefront)

    Buyer->>MktAuth: Submits credentials or clicks Google OAuth
    MktAuth->>Supa: Authenticates user & issues session tokens
    Supa-->>MktAuth: Returns JWT Access Token & Refresh Token
    MktAuth->>MktAuth: Encodes session into secure fragment hash (#access_token=...)
    MktAuth->>Storefront: 302 Redirect to app.debelu.com/#access_token=...&refresh_token=...
    Note over Storefront: Storefront executes consumeSessionHandoff()
    Storefront->>Storefront: Stores tokens in secure local storage & wipes URL hash
    Storefront-->>Buyer: Renders personalized Buyer / Vendor portal

This pattern ensures that authentication state is preserved across isolated origin domains without exposing sensitive credentials in HTTP server request logs or referrer headers.

5. SEO Architecture & LLM Indexing

Debelu implements a modern dual-indexing strategy: standard search engines (Google, Bing) receive structured schema markup, while generative AI agents (ChatGPT, Gemini, Perplexity) receive curated machine-readable context via llms.txt.

5.1 Dynamic Sitemap & Robots Generation (`sitemap.ts`, `robots.ts`)

robots.ts: Automatically disables indexing on administrative paths and private token endpoints while granting full crawling permissions for /store/*, /legal/*, /help/*, and /llms.txt.
sitemap.ts: Queries public vendor records and campus listings to generate a dynamic, priority-ranked sitemap with explicit <lastmod> timestamps and change frequencies.

5.2 The `llms.txt` Endpoint (`app/llms.txt/route.ts`)

Conforming to the emerging open standard for AI agent crawling, Debelu exposes a structured markdown document at https://debelu.com/llms.txt:

typescript

// debelu-marketing/app/llms.txt/route.ts
export async function GET() {
  const content = `# Debelu Campus Marketplace - Technical & Platform Manifest

> Debelu is Nigeria's premier hyperlocal campus marketplace providing peer-to-peer commerce, verified student vendors, closed-loop financial escrow, and the Nduzi AI assistant.

## Core Capabilities
- Hyperlocal Campus Commerce: University-specific trading hubs (UNILAG, UNN, UI, OAU, FUTO, etc.).
- Closed-Loop Escrow: Payments held until buyer confirms receipt via a 6-digit delivery PIN.
- Nduzi AI Assistant: Gemini-powered multimodal conversational agent for product discovery.
- Trust & Safety: ChatGuard regex protection preventing off-platform financial fraud.

## Key URLs
- Platform Overview: https://debelu.com
- Merchant Registration: https://debelu.com/sell
- Trust & Safety Architecture: https://debelu.com/trust-and-safety
- Developer Documentation: https://docs.debelu.com
`;
  return new Response(content, {
    headers: {
      'Content-Type': 'text/plain; charset=utf-8',
      'Cache-Control': 'public, max-age=86400, s-maxage=86400',
    },
  });
}

6. HTTP Security Perimeter & Header Hardening

In [next.config.js](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-marketing/next.config.js), Debelu applies strict HTTP response headers conforming to Google and Apple security standards across all marketing routes:

javascript

// debelu-marketing/next.config.js:47-72
headers: [
  { key: 'X-Content-Type-Options', value: 'nosniff' },
  { key: 'X-Frame-Options', value: 'DENY' },
  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
  { key: 'Strict-Transport-Security', value: 'max-age=31536000; includeSubDomains; preload' },
  { key: 'Cross-Origin-Opener-Policy', value: 'same-origin' },
  { key: 'Cross-Origin-Resource-Policy', value: 'cross-origin' },
  { key: 'X-XSS-Protection', value: '0' },
  { key: 'Content-Security-Policy', value: "default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' https: data: blob:; font-src 'self' https: data:; connect-src 'self' https://*.supabase.co https://*.supabase.in https://*.debelu.com https://debelu-backend-production.up.railway.app https://*.sentry.io https://vercel.live; object-src 'none'; base-uri 'self'; frame-ancestors 'none'; form-action 'self'" }
]

7. Performance Engineering & Core Web Vitals

To maximize organic search ranking and mobile conversion on cellular connections across Nigerian universities, debelu-marketing enforces rigorous performance budgets:

Static Generation (SSG): Informational pages (/about, /pricing, /how-it-works) are pre-rendered into static HTML at build time.
Incremental Static Regeneration (ISR): Public store pages (/store/[slug]) revalidate on an hourly cadence (revalidate: 3600), serving instant cached HTML while updating vendor inventory in the background.
Asset Optimization: Fonts are loaded via next/font with zero layout shift; critical SVG icons are inlined.

8. Build, Testing & Deployment Pipelines

8.1 Build & Verification Commands

bash

# Type check the marketing application
npm run type-check --workspace=debelu-marketing

# Run unit tests via Vitest
npm run test --workspace=debelu-marketing

# Compile Next.js production build
npm run build --workspace=debelu-marketing

# Run local production server
npm run start --workspace=debelu-marketing

8.2 Vercel Deployment Workflow

Deployments are triggered automatically via GitHub Actions:

Preview Deployments: Spun up on every pull request with unique preview URLs for visual QA and Lighthouse CI auditing (lighthouserc.json).
Production Deployment: Merges to main deploy instantly to the Vercel Edge Network with zero downtime.

9. Document Revision History

Revision	Date	Lead Author	Scope of Changes	Status
`1.0.0`	2026-10-05	Principal Web Architect	Initial enterprise specification detailing Next.js 16 App Router, cross-domain origin routing, session handoff protocol, SEO/LLM indexing, and security hardening.	Active Living Standard

Marketing & SEO Web Application (debelu-marketing) ​

1. System Overview & Monorepo Topology ​

1.1 Technical Stack & Core Invariants ​

2. Cross-Domain Routing & Origin Segregation Matrix ​

2.1 Canonical Redirect Table (from next.config.js) ​

3. App Router Directory Structure & Page Inventory ​

4. Authentication & Cross-App Session Handoff ​

5. SEO Architecture & LLM Indexing ​

5.1 Dynamic Sitemap & Robots Generation (sitemap.ts, robots.ts) ​

5.2 The llms.txt Endpoint (app/llms.txt/route.ts) ​

6. HTTP Security Perimeter & Header Hardening ​

7. Performance Engineering & Core Web Vitals ​

8. Build, Testing & Deployment Pipelines ​

8.1 Build & Verification Commands ​

8.2 Vercel Deployment Workflow ​

9. Document Revision History ​

Marketing & SEO Web Application (`debelu-marketing`)

1. System Overview & Monorepo Topology

1.1 Technical Stack & Core Invariants

2. Cross-Domain Routing & Origin Segregation Matrix

2.1 Canonical Redirect Table (from `next.config.js`)

3. App Router Directory Structure & Page Inventory

4. Authentication & Cross-App Session Handoff

5. SEO Architecture & LLM Indexing

5.1 Dynamic Sitemap & Robots Generation (`sitemap.ts`, `robots.ts`)

5.2 The `llms.txt` Endpoint (`app/llms.txt/route.ts`)

6. HTTP Security Perimeter & Header Hardening

7. Performance Engineering & Core Web Vitals

8. Build, Testing & Deployment Pipelines

8.1 Build & Verification Commands

8.2 Vercel Deployment Workflow

9. Document Revision History