Master Environment Variables Reference Matrix

This document is the authoritative engineering specification for all environment variables, public build arguments, and server secrets across the Debelu platform. Grounded directly in debelu-backend/.env.example, apps/storefront/.env.example, debelu-marketing/.env.example, and CI/CD deployment configurations, this matrix defines scope, sensitivity, validation formats, and cross-surface alignments.

---

1. Security Architecture & Boundary Principles

Debelu enforces strict separation between public client-side environment configurations and confidential server-side secrets.

graph TD
    subgraph BrowserClientPerimeter [Client Browser & Mobile Sandbox]
        StorefrontClient["apps/storefront (Vite)<br/>Only VITE_* Variables Inlined"]
        MarketingClient["debelu-marketing (Next.js)<br/>Only NEXT_PUBLIC_* Inlined"]
    end

    subgraph ServerSecretPerimeter [Confidential Server Infrastructure]
        BackendAPI["debelu-backend (Railway/Node.js)<br/>SUPABASE_SERVICE_ROLE_KEY<br/>PAYSTACK_SECRET_KEY<br/>GEMINI_API_KEY"]
        EdgeFunctions["Supabase Deno Edge Workers<br/>VAPID_PRIVATE_KEY<br/>META_APP_SECRET"]
        GitHubActions["GitHub Actions Secrets Store<br/>Deployment & Cloud Tokens"]
    end

    BrowserClientPerimeter -.->|Strictly Forbidden from Storing| ServerSecretPerimeter

1.1 Core Rules

1. Public Key Prefixing: Only variables prefixed with VITE_ (Vite) or NEXT_PUBLIC_ (Next.js) are bundled into client JavaScript. Any variable without these prefixes is inaccessible to frontend bundles.
2. Zero Secrets in Client Bundles: Secret keys (PAYSTACK_SECRET_KEY, SUPABASE_SERVICE_ROLE_KEY, GEMINI_API_KEY, R2_SECRET_ACCESS_KEY) must NEVER be assigned VITE_ or NEXT_PUBLIC_ prefixes. Client bundles undergo automated CI scans to detect secret leakage.
3. Fail-Closed Verification: Backend services validate mandatory environment variables at boot via Zod schemas, halting execution with exit code 1 if critical secrets are omitted.

---

2. Backend API Service (debelu-backend)

Configured via debelu-backend/.env (local) or Railway environment variables (production).

Variable Name	Sensitive	Required	Target / Default	Purpose & Architectural Rules
NODE_ENV	No	Yes	production | development	Enables production optimizations, structured JSON logging, and Sentry sampling.
PORT	No	Yes	8000 (or injected by Railway)	TCP listening port for the Express HTTP server.
SUPABASE_URL	No	Yes	https://xyzproject.supabase.co	Remote Supabase project API gateway endpoint.
SUPABASE_SERVICE_ROLE_KEY	Yes	Yes	eyJhbGciOiJIUzI1Ni...	High Privilege: Bypasses PostgreSQL Row-Level Security for administrative queries.
SUPABASE_ANON_KEY	No	Yes	eyJhbGciOiJIUzI1Ni...	Public API key used for executing stored procedures on behalf of authenticated users.
SUPABASE_JWT_SECRET	Yes	Yes	64-char Hexadecimal	Cryptographic secret utilized to verify Supabase JWT auth tokens locally.
DATABASE_URL	Yes	Yes	postgresql://postgres:...	Direct PostgreSQL connection string for database migrations and connection pooling.
PAYSTACK_SECRET_KEY	Yes	Yes	sk_live_... / sk_test_...	Financial Secret: Authorizes Paystack checkout payments, verification, and transfers.
PAYSTACK_DVA_BANK	No	Yes	wema-bank (prod) / test-bank	Default commercial banking partner for dedicated virtual account (DVA) top-ups.
GEMINI_API_KEY	Yes	Yes	AIzaSy...	Authorizes Google AI Studio API calls for the Nduzi AI assistant.
GEMINI_MODEL	No	No	gemini-2.5-flash	Configures the underlying Gemini language model identifier.
R2_ACCOUNT_ID	Yes	No	32-char Hexadecimal	Cloudflare account identifier for the R2 image storage bucket.
R2_ACCESS_KEY_ID	Yes	No	32-char String	S3-compatible access key ID for Cloudflare R2 bucket.
R2_SECRET_ACCESS_KEY	Yes	No	64-char String	S3-compatible secret access key for Cloudflare R2 bucket.
R2_PUBLIC_BUCKET	No	No	debelu-product-images	Name of the R2 bucket hosting public product catalog images.
R2_PUBLIC_URL	No	No	https://cdn.debelu.com	CDN base URL serving cached product images.
REDIS_URL	Yes	No	rediss://default:pwd@host:port	Redis connection string for BullMQ distributed queues and cluster-wide rate limiting.
ALLOWED_ORIGINS	No	Yes	https://debelu.com,https://app.debelu.com,https://admin.debelu.com	Whitelist of client web origins allowed to pass CORS checks.
MAINTENANCE_JOBS	No	No	on (or off)	Controls in-process housekeeping cron execution (jobs/maintenance.ts).
WHATSAPP_WEBHOOK_VERIFY_TOKEN	Yes	No	Random 32-char String	Verification token used during Meta WhatsApp Cloud API webhook registration.
META_APP_SECRET	Yes	No	Meta App Secret	Shared secret used to verify Meta WhatsApp webhook HMAC signatures.
TERMII_API_KEY	Yes	No	Termii Key	API key for Termii SMS gateway (used for campus verification PINs).
TERMII_BASE_URL	No	No	https://api.ng.termii.com	Base URL for Termii SMS and wallet balance queries.
GIT_SHA	No	No	Commit SHA	Git commit hash injected by CI for /health diagnostics.
SENTRY_DSN	No	No	Sentry DSN URL	Error reporting ingest URL for backend exceptions.

---

3. Storefront Web & Mobile Application (apps/storefront)

Configured via apps/storefront/.env.local (local) or Cloudflare Pages project settings (production).

Variable Name	Sensitive	Required	Target / Default	Purpose & Description
VITE_SUPABASE_URL	No	Yes	https://xyzproject.supabase.co	Supabase gateway URL for client auth and realtime subscriptions.
VITE_SUPABASE_ANON_KEY	No	Yes	eyJhbGciOiJIUzI1Ni...	Public Supabase anon key; queries are strictly bounded by PostgreSQL RLS.
VITE_PAYSTACK_PUBLIC_KEY	No	Yes	pk_live_... / pk_test_...	Public Paystack key for rendering inline checkout modals.
VITE_API_BASE_URL	No	Yes	https://api.debelu.com/api	Base URL for debelu-backend REST endpoints.
VITE_MARKETING_URL	No	Yes	https://debelu.com	Target origin for public marketing and login redirects.
VITE_APP_URL	No	Yes	https://app.debelu.com	Canonical storefront origin.
VITE_VENDOR_URL	No	Yes	https://app.debelu.com/sell	Deep-link root for merchant and seller views.
VITE_ADMIN_URL	No	Yes	https://admin.debelu.com	Target URL for isolated staff origin redirections.
VITE_COOKIE_DOMAIN	No	Yes	.debelu.com	Shared root domain for cross-subdomain cookie session storage.
VITE_R2_PRODUCT_IMAGES	No	No	true | false	Feature toggle switching image uploads from Supabase to Cloudflare R2.
VITE_VAPID_PUBLIC_KEY	No	No	Base64 URL-safe key	Public VAPID key for Web Push browser notifications.
VITE_GIT_SHA	No	No	Commit SHA	Version tag displayed in mobile settings for troubleshooting.
VITE_SENTRY_DSN	No	No	Sentry DSN URL	Client-side error reporting DSN for React exceptions.

---

4. Marketing & Public Website (debelu-marketing)

Configured via debelu-marketing/.env.local (local) or Vercel project settings (production).

Variable Name	Sensitive	Required	Target / Default	Purpose & Description
NEXT_PUBLIC_SUPABASE_URL	No	Yes	https://xyzproject.supabase.co	Public Supabase URL for login and registration forms.
NEXT_PUBLIC_SUPABASE_ANON_KEY	No	Yes	eyJhbGciOiJIUzI1Ni...	Public Supabase key for client authentication.
NEXT_PUBLIC_API_URL	No	Yes	https://api.debelu.com/api	Backend API URL for public status checks.
NEXT_PUBLIC_STOREFRONT_URL	No	Yes	https://app.debelu.com	Target destination for post-login session handoff.
NEXT_PUBLIC_POSTHOG_KEY	No	No	PostHog Project API Key	Product analytics tracking key.
NEXT_PUBLIC_POSTHOG_HOST	No	No	https://app.posthog.com	Host endpoint for PostHog telemetry ingestion.
SENTRY_AUTH_TOKEN	Yes	No	Sentry Auth Token	Required in CI/build environments for source map uploads.
SENTRY_DSN	No	No	Sentry DSN URL	Next.js server, edge, and browser error tracking DSN.

---

5. Supabase Edge Functions Secrets

Managed via supabase secrets set or the Supabase Cloud dashboard.

Secret Key Name	Used By Function	Sensitivity	Purpose & Description
PAYSTACK_SECRET_KEY	paystack-webhook	High	Verifies HMAC SHA-512 signatures on inbound Paystack payment webhooks.
META_WHATSAPP_TOKEN	deliver-notification	High	Bearer token authorizing Meta WhatsApp Cloud API message delivery.
WHATSAPP_PHONE_NUMBER_ID	deliver-notification	Normal	Meta registered phone identifier for transactional messaging.
TERMII_API_KEY	deliver-notification	High	API key for Termii SMS fallback delivery.
VAPID_PRIVATE_KEY	deliver-notification	High	Private cryptographic key for signing Web Push notification payloads.
SUPABASE_SERVICE_ROLE_KEY	All Edge Functions	High	Bypasses RLS to record webhook transactions and notification logs.

---

6. GitHub Actions CI/CD Secrets

Configured in GitHub Repository Settings (Settings $\rightarrow$ Secrets and variables $\rightarrow$ Actions).

Secret Identifier	Target Workflow	Purpose & Description
CLOUDFLARE_API_TOKEN	storefront-release.yml	Authorizes deployment of static build assets to Cloudflare Pages.
CLOUDFLARE_ACCOUNT_ID	storefront-release.yml	Cloudflare account identifier for Pages projects.
RAILWAY_TOKEN	backend-deploy.yml	API token triggering Docker build and deployment on Railway.
VERCEL_TOKEN	marketing-deploy.yml	Authorizes deployment of Next.js marketing application to Vercel.
VERCEL_ORG_ID	marketing-deploy.yml	Vercel team/organization identifier.
VERCEL_PROJECT_ID	marketing-deploy.yml	Target Vercel project identifier for debelu.com.
SENTRY_AUTH_TOKEN	All Build Workflows	Authenticates CLI source map uploads during release builds.

---

7. Cross-Surface Alignment Table

To prevent broken cross-domain links or authentication failures, the following values must align identically across all surfaces:

flowchart LR
    subgraph ConfigAlignment [Cross-Surface Alignment Invariants]
        direction TB
        V1["Supabase URL & Anon Key"] -->|Identical In| SF["apps/storefront"]
        V1 -->|Identical In| MKT["debelu-marketing"]
        V1 -->|Identical In| ADM["debelu-admin"]
        
        V2["Paystack Keys"] -->|Public pk_* In| SF
        V2 -->|Secret sk_* In| BE["debelu-backend & Edge Functions"]
        
        V3["Origin URLs"] -->|Allowed in CORS| BE
        V3 -->|Used in Redirects| MKT & SF
    end

---

8. Document Revision History

Revision	Date	Lead Author	Scope of Changes	Status
1.0.0	2026-10-05	Principal DevOps Engineer	Complete enterprise master environment variables specification covering all 4 surfaces, edge functions, CI secrets, and cross-surface alignments.	Active Living Standard