Production Multi-Cloud Deployment Architecture

This document is the authoritative operational specification for production build pipelines, continuous integration gates, multi-cloud hosting topologies, DNS orchestration, and rollback standard operating procedures across the Debelu platform. Grounded directly in [.github/workflows/monorepo-ci.yml](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/.github/workflows/monorepo-ci.yml), [storefront-release.yml](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/.github/workflows/storefront-release.yml), [sync-cloudflare-dns.mjs](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/scripts/sync-cloudflare-dns.mjs), and cloud provider configurations, this specification establishes our zero-downtime deployment lifecycle.

---

1. Production Deployment Topology

Debelu distributes workloads across specialized cloud platforms to achieve high availability, low mobile latency across Nigerian networks, and zero-CDE payment boundaries:

graph TD
    subgraph ClientDNS [Cloudflare DNS & Edge Network]
        Apex["debelu.com (Apex Domain)"]
        SubApp["app.debelu.com (Storefront)"]
        SubAPI["api.debelu.com (Backend API)"]
        SubAdmin["admin.debelu.com (Isolated Admin)"]
        SubCDN["cdn.debelu.com (Media Assets)"]
    end

    subgraph HostingProviders [Multi-Cloud Hosting Infrastructure]
        Vercel["Vercel Edge Network<br/>debelu-marketing (Next.js 16)"]
        CFPagesApp["Cloudflare Pages<br/>apps/storefront (React 19 / Vite SPA)"]
        CFPagesAdmin["Cloudflare Pages<br/>debelu-admin (Isolated Operations Console)"]
        Railway["Railway Container Runtime<br/>debelu-backend (Docker Node 20 LTS)"]
        CFR2["Cloudflare R2 Bucket<br/>debelu-product-images"]
    end

    subgraph DatabaseCloud [Supabase Managed Cloud]
        Postgres[(Managed PostgreSQL 16 Cluster)]
        EdgeWorkers[Supabase Deno Edge Functions]
    end

    Apex --> Vercel
    SubApp --> CFPagesApp
    SubAdmin --> CFPagesAdmin
    SubAPI --> Railway
    SubCDN --> CFR2

    Railway --> Postgres
    EdgeWorkers --> Postgres
    CFPagesApp --> Railway
    CFPagesAdmin --> Railway
    Vercel --> Railway

1.1 Infrastructure Inventory

Service / Surface	Production Domain	Cloud Host	Build / Runtime Engine	Deployment Trigger
Marketing Portal	debelu.com	Vercel	Next.js 16 App Router (Node.js Edge)	Automated Git push to main via Vercel GitHub App.
Buyer & Vendor Storefront	app.debelu.com	Cloudflare Pages	Static React 19 / Vite 6 SPA	GitHub Actions (storefront-release.yml) on merge to main.
Admin Operations Console	admin.debelu.com	Cloudflare Pages	Static Vite SPA (Strictly isolated origin)	GitHub Actions (admin-release.yml) on merge to main.
Backend REST API	api.debelu.com	Railway	Multi-Stage Docker (Node.js 20 LTS Alpine)	Railway GitHub Trigger on changes in debelu-backend/.
Database & Auth	*.supabase.co	Supabase	Managed PostgreSQL 16 + GoTrue Auth	Supabase CLI (supabase db push) / Migration pipelines.
Serverless Functions	*.supabase.co/functions/v1	Supabase	Deno Edge Isolates	Supabase CLI (supabase functions deploy).
Catalog Media Storage	cdn.debelu.com	Cloudflare R2	S3-Compatible Object Store + Cloudflare CDN	Asynchronous backend uploads via @aws-sdk/client-s3.

---

2. GitHub Actions CI/CD Pipeline (monorepo-ci.yml)

Every pull request and merge to main triggers the authoritative verification pipeline in [.github/workflows/monorepo-ci.yml](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/.github/workflows/monorepo-ci.yml):

flowchart TD
    PR[Pull Request Opened / Updated] --> ParallelSplit{Parallel CI Jobs}
    
    subgraph Job1_Verify [Job: verify (ubuntu-latest)]
        Install[1. npm ci: Locked Dependency Tree] --> Audit[2. npm audit: Reject High/Critical CVEs]
        Audit --> TypeCheck[3. npm run type-check: Multi-Workspace Strict Typing]
        TypeCheck --> Lint[4. npm run lint: ESLint 9 Flat Config]
        Lint --> Tests[5. npm test: Vitest & Jest Unit Tests]
        Tests --> Build[6. npm run build: Turbo Build All Apps]
        Build --> ReactRuntime[7. check-react-runtime.cjs: Assert Single React 19]
        ReactRuntime --> Playwright[8. Playwright: Chromium a11y & Route Smoke Tests]
        Playwright --> SBOM[9. generate-sbom.mjs: Generate & Archive CycloneDX SBOM]
    end

    subgraph Job2_Database [Job: database-flows (Service Container)]
        PostgresService[(Service: postgres:16)] --> RunFlows[scripts/db-flow-tests.sh: Replay 97 Migrations]
        RunFlows --> ConcurrencyChecks[Execute Native Concurrency & Race Tests]
    end

    ParallelSplit --> Job1_Verify
    ParallelSplit --> Job2_Database
    
    Job1_Verify --> Mergeable{All Gates Passed?}
    Job2_Database --> Mergeable
    Mergeable -->|Yes| Approved[PR Cleared for Review & Merge]
    Mergeable -->|No| Blocked[PR Blocked: Detailed Diagnostic Logs Emitted]

2.1 Critical CI Verification Stages

1. Dependency Audit (npm audit --audit-level=high --omit=dev): Automatically blocks builds containing known high or critical severity CVEs in production dependencies.
2. React Runtime Consistency (check-react-runtime.cjs): Verifies that apps/storefront/dist and debelu-admin/dist bundle a single, unified React 19 runtime, preventing context isolation bugs across symlinks.
3. Accessibility Smoke Tests (Playwright): Executes automated accessibility audits against the compiled storefront build using @axe-core/playwright.
4. Isolated PostgreSQL Flow Tests (db-flow-tests.sh): Boots a clean postgres:16 service container, applies all 97 migrations sequentially from scratch, and runs the entire automated database test harness.

---

3. Surface-Specific Deployment Playbooks

3.1 Storefront Deployment (Cloudflare Pages)

• Workflow: .github/workflows/storefront-release.yml
• Build Command: npm run build --workspace=@debelu/storefront
• Output Directory: apps/storefront/dist
• Deployment Mechanics: Assets are uploaded to Cloudflare Pages via Wrangler CLI:

  wrangler pages deploy apps/storefront/dist --project-name=debelu-storefront --commit-dirty=true

• Preview Deployments: Every pull request generates an ephemeral Cloudflare preview environment with a unique preview hash URL for visual QA.

3.2 Marketing Site Deployment (Vercel)

• Framework Preset: Next.js
• Root Directory: debelu-marketing
• Build Command: next build
• Output Directory: .next
• Edge Network Optimization: Static marketing assets and ISR store pages cache globally across Vercel edge nodes.

3.3 Backend API Deployment (Railway)

• Container Build: Multi-stage Dockerfile executing on Railway's container infrastructure.
• Port Binding: Automatically binds to $PORT assigned by Railway (default 8000).
• Health Check Invariants: Railway evaluates GET /health/ready. Traffic is not routed to a newly provisioned container until the readiness probe confirms live PostgreSQL and Redis connections.

3.4 Supabase Database & Edge Functions

• Database Migrations: Applied via Supabase CLI in CI/CD:

  supabase db push --project-ref <project_ref>

• Edge Functions: Deployed independently to Supabase global edge nodes:

  supabase functions deploy paystack-webhook --project-ref <project_ref>
  supabase functions deploy deliver-notification --project-ref <project_ref>

---

4. DNS Architecture & Edge Routing (sync-cloudflare-dns.mjs)

Debelu manages all apex and subdomain DNS records through Cloudflare:

flowchart LR
    Apex["debelu.com"] -->|CNAME cname.vercel-dns.com| Vercel[Vercel Marketing Portal]
    App["app.debelu.com"] -->|CNAME debelu-storefront.pages.dev| CFPages[Cloudflare Pages Storefront]
    Admin["admin.debelu.com"] -->|CNAME debelu-admin.pages.dev| CFAdmin[Cloudflare Pages Admin]
    API["api.debelu.com"] -->|CNAME railway.app| Railway[Railway Backend Cluster]
    CDN["cdn.debelu.com"] -->|Custom Domain| R2[Cloudflare R2 Storage Bucket]

4.1 DNS Synchronization Script

Run [scripts/sync-cloudflare-dns.mjs](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/scripts/sync-cloudflare-dns.mjs) to verify and align DNS records:

node scripts/sync-cloudflare-dns.mjs

• TLS Mode: Enforces Full (Strict) SSL/TLS encryption across Cloudflare.
• Always Use HTTPS: Enabled globally with HSTS preloading.

---

5. Rollback Procedures & Failure Recovery

stateDiagram-v2
    [*] --> HealthyRelease
    HealthyRelease --> IncidentDetected: SEV-1 Alert or Sentry Error Spike
    
    state IncidentDetected {
        [*] --> ClassifySurface
        ClassifySurface --> StorefrontRollback: Storefront Regression
        ClassifySurface --> MarketingRollback: Marketing Regression
        ClassifySurface --> BackendRollback: Backend Regression
        ClassifySurface --> DatabaseRollback: Database Invariant Breach
    }
    
    StorefrontRollback --> AtomicPagesRollback: Instantaneous Previous Deployment Switch
    MarketingRollback --> VercelRollback: Instantaneous Vercel Instant Rollback
    BackendRollback --> RailwayRollback: Redeploy Previous Docker SHA
    DatabaseRollback --> CompensatingMigration: Deploy Forward-Only Compensating Migration

5.1 Cloudflare Pages Instant Rollback (Storefront)

1. Open the Cloudflare Dashboard $\rightarrow$ Workers & Pages $\rightarrow$ debelu-storefront.
2. Navigate to Deployments. Locate the last verified healthy deployment ID.
3. Click Actions $\rightarrow$ Rollback to this deployment.
4. Rollback executes atomically within $< 30$ seconds globally.

5.2 Vercel Instant Rollback (Marketing)

1. Open the Vercel Dashboard for debelu.com.
2. Locate the prior production deployment in the Deployments tab.
3. Click Instant Rollback. Traffic reverts immediately without rebuilding.

5.3 Railway Rollback (Backend API)

1. Open Railway Dashboard $\rightarrow$ debelu-backend service.
2. Under Deployments, click the menu on the previous successful container deployment.
3. Select Redeploy. Railway starts the previous image and executes zero-downtime traffic cutover.

5.4 Database Rollback Protocol

• Strict Prohibition: Never run SQL DROP TABLE or DROP COLUMN commands against production data during an outage.
• Compensating Migration: Author and deploy a forward-only migration (e.g., dropping a trigger or disabling a constraint) to restore operational stability, as documented in [database-migrations.md](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/docs/reference/database-migrations.md).

---

6. Document Revision History

Revision	Date	Lead Author	Scope of Changes	Status
1.0.0	2026-10-05	Principal DevOps Engineer	Complete enterprise deployment specification covering multi-cloud topologies, GitHub Actions CI/CD pipelines, surface playbooks, DNS routing, and instant rollback procedures.	Active Living Standard