Domain & Architecture Glossary
1. Business & Campus Commerce Concepts
Debelu
The core brand identity and philosophy, derived from the Igbo phrase meaning "Keep for me" or "Safeguard". It embodies the platform's mission to protect university students from financial fraud and unfulfilled purchases through digital escrow.
The Seam (Logo & Brand Mark)
The proprietary visual identity of Debelu representing an ancient coin shared between two students, interlocked by a stepped precision tab. It symbolizes the mutual contract between buyer and vendor locked safely in platform escrow.
Operation Campus (orders.operation_campus)
The university campus geographical boundary where an order was originated, fulfilled, and accounted for (e.g., unilag, ui, oau, futo). A mandatory check constraint (23514) ensures that orders cannot cross campus boundaries without explicit platform authorization.
Delivery Hub (campus_delivery_hubs)
Designated physical meeting points within a university campus (e.g., UNILAG New Hall Gate, Moremi Car Park, Faculty of Engineering Quadrangle) verified by Debelu staff as safe, well-lit exchange zones for product inspection and handoff.
Delivery PIN
A cryptographically pseudo-random 4-digit code generated at order creation. The PIN is visible only to the buyer. The buyer shares it verbally with the vendor only after physical inspection and acceptance of the merchandise.
Escrow
A closed-loop financial state where a buyer's payment is held securely in Debelu's custody account until verified fulfillment. The vendor cannot access funds, and the buyer cannot unilaterally claw them back, until the order concludes via PIN verification or formal dispute arbitration.
Escrow Release
The atomic database transaction that transitions locked escrow funds into the vendor's withdrawable wallet ledger balance upon valid submission of the 4-digit Delivery PIN.
Nduzi
The AI shopping assistant and platform guide (Igbo for "Guidance" or "Leader"). Built upon Google Gemini 1.5 Flash, Nduzi assists students with natural language catalog search, campus deal discovery, order tracking, and customer dispute intake.
Vibe
A curated, youth-centric categorization taxonomy (e.g., "Tech Bro Essentials", "Exam Crunch", "Hostel Chef", "Weekend Flex") enabling intuitive, mood-based discovery across diverse product classes.
Flash Sale
Time-delimited promotional commerce campaigns with strictly capped inventory quantities and algorithmic price ceilings, targeted to specific campuses.
2. User Roles & Security Identities
Buyer
The consumer role on Debelu. A registered university student who browses catalogs, communicates via ChatGuard-screened channels, authorizes orders via Paystack, and inspects goods before providing their Delivery PIN.
Vendor (Merchant)
A campus entrepreneur authorized to list products, manage inventory, chat with buyers, fulfill campus orders, and receive bank payouts. Vendors undergo mandatory Tier-1/Tier-2 KYC verification.
Staff
An internal Debelu employee with administrative credentials. Staff access is strictly segregated into tiered roles:
support_agent: Triage support tickets, review ChatGuard flags, assist in dispute inquiries.admin: Manage category commissions, review vendor applications, review moderation cases.superadmin: Access financial ledgers, approve payout batches (Maker-Checker), rotate platform controls, manage staff privileges.
Service Role (service_role)
The backend administrative Supabase JWT identity. Used exclusively for automated server-to-server operations (BullMQ workers, cron jobs, reconciliation daemons). Completely bypasses PostgreSQL Row-Level Security (RLS) policies.
3. Financial, Banking & Escrow Terminology
Kobo
The base integer currency unit of the Nigerian Naira ($100\text{ Kobo} = ₦1.00$). To avoid floating-point rounding errors and precision loss, all financial calculations, database fields, and API payloads across Debelu are denominated strictly in integer Kobo (amount_minor).
Principal
The base item price set by the vendor before any taxes, transaction fees, or campus delivery surcharges are applied.
Commission (Category Commission)
The platform fee deducted by Debelu upon successful escrow release. Commission rates are dynamically configurable per product category (e.g., $5%$ for electronics, $10%$ for fashion, $2%$ for textbooks) via category_commissions.
Fee Snapshot (order_fee_snapshots)
An immutable, frozen record created at order checkout capturing the exact gross total, principal, platform commission rate, and gateway processing fee. Ensures that future commission rate changes do not retroactively alter historical order balances.
Checkout Payment Intent (checkout_payment_intents)
A state-machine entity tracking the complete lifecycle of a buyer's payment attempt: requires_payment_method $\to$ requires_action $\to$ processing $\to$ succeeded $\to$ canceled.
Payout Batch (payout_batches)
An aggregated group of approved vendor withdrawal requests compiled for mass disbursement to Nigerian commercial banks. Subject to mandatory Maker-Checker dual authorization before gateway dispatch.
Payout Transfer Intent (payout_transfer_intents)
An individual transfer instruction representing a disbursement to a single vendor's bank account via the Paystack Transfers API.
Wallet Ledger (wallets & wallet_transactions)
Debelu's internal double-entry accounting ledger. Maintains exact balances for buyer refunds and vendor accumulated earnings, enforcing the mathematical invariant: $$\sum \text{Credits} = \sum \text{Debits}$$
Reconciliation
The automated verification process executed by PayoutTransferReconciliationService that matches external Paystack bank settlement logs against internal database ledgers to detect and resolve discrepancies.
4. Nigerian Banking & Statutory Identity Standards
NUBAN (Nigeria Uniform Bank Account Number)
The 10-digit bank account numbering standard mandated by the Central Bank of Nigeria (CBN). Debelu automatically validates all vendor account numbers against the NIBSS routing algorithm and resolves the account holder's name before approving withdrawals.
NIP (NIBSS Instant Payment)
The interbank electronic funds transfer switch operated by the Nigeria Inter-Bank Settlement System (NIBSS), facilitating real-time gross settlement between Nigerian financial institutions.
BVN (Bank Verification Number)
An 11-digit biometric identification number issued by the Central Bank of Nigeria to curb financial fraud. Stored in zero-knowledge hashed format or verified via certified compliance partners during Tier-2 vendor KYC.
NIN (National Identification Number)
The 11-digit unique national identification number issued by the National Identity Management Commission (NIMC) of Nigeria, required for Tier-2 merchant onboarding.
DVA (Dedicated Virtual Account)
Dynamic, single-use or user-specific bank account numbers generated via Paystack to allow students without debit cards to fund purchases via direct bank transfer.
CBN (Central Bank of Nigeria)
The apex monetary authority and regulatory body governing electronic payments, stored value facilities, and anti-money laundering (AML) operations in Nigeria.
NDPC / NDPA (Nigeria Data Protection Commission / Act 2023)
The statutory regulatory agency and primary legal framework governing data privacy, user consent, and personal data processing in the Federal Republic of Nigeria.
5. Trust, Safety & Moderation Terminology
ChatGuard (ChatGuardService)
The real-time message filtration engine operating across buyer-vendor communications. Automatically detects and redacts off-platform transaction attempts, such as Nigerian phone numbers, NUBAN bank accounts, and fintech payment handles (Opay, Palmpay, Kuda).
PriceGuard (PriceGuardService)
An automated anti-price-gouging engine that calculates dynamic rolling median prices for campus products. Flags listings with price ratios $R \ge 3.0$ (predatory gouging) or $R \le 0.1$ (suspected stolen goods / fraud).
Moderation Case (moderation_cases)
A queued review item created when a product listing, review, user profile, or chat message triggers automated safety flags or user reports.
Vendor Strike (vendor_strikes)
A formal penalty point assessed against a merchant for policy violations (counterfeits, abusive conduct, repeated off-platform diversion). Debelu enforces a 3-Strike Escalation Policy:
- Strike 1: Written warning & 48-hour new listing freeze.
- Strike 2: 7-day complete account suspension & search demotion.
- Strike 3: Permanent merchant ban and asset forfeiture review.
Media Moderation
The automated background pipeline utilizing Google Gemini Vision to inspect uploaded product images for nudity, weapons, narcotics, counterfeit luxury trademarks, or violent imagery before listings go live.
6. Privacy & Data Governance (NDPA / GDPR)
DSAR (Data Subject Access Request)
A formal request by a user under the NDPA 2023 to receive an export of all personal data held by Debelu. Handled programmatically via SubjectPrivacyExportService.
Right to be Forgotten (RTBF) / Erasure Plan
The statutory right of a user to request account deletion. Debelu executes a structured Erasure Plan: personal identifiers and profiles are purged across 7 erasable tables, while transactional records (orders, payments, tax ledgers) are retained in anonymized format for 7 years to satisfy statutory CBN requirements.
PII (Personally Identifiable Information)
Any data point that directly or indirectly identifies an individual, including full names, matriculation numbers, phone numbers, email addresses, and residential hostel room numbers.
Zero-CDE (Zero Cardholder Data Environment)
The security architectural boundary under PCI-DSS v4.0 SAQ-A ensuring that Debelu servers, databases, and logs never touch, transmit, or store Primary Account Numbers (PAN), CVVs, or card PINs.
7. Technical & System Architecture Terminology
RLS (Row-Level Security)
PostgreSQL's native data isolation mechanism. RLS policies evaluate auth.uid() against table foreign keys on every query, ensuring that users can only read or mutate their own records at the database engine level.
Circuit Breaker (circuitBreakers.ts)
A software resiliency pattern that monitors downstream external dependencies (Paystack, Gemini, Supabase). If downstream failure rates exceed defined thresholds ($> 50%$), the circuit trips open, immediately failing fast to protect backend worker threads from saturation.
Idempotency Key (Idempotency-Key)
A unique client-generated UUIDv4 header transmitted on mutating HTTP requests (POST /api/orders/checkout, POST /api/payouts/dispatch). Guarantees that unstable mobile network retries cannot result in duplicate orders or duplicate bank charges.
CSP Nonce / Hash (vite.csp-nonce.ts)
Cryptographic SHA-256 hashes generated at build time for all inline bootstrap scripts, injected into Content Security Policy (CSP) headers to prevent Cross-Site Scripting (XSS) on static edge deployments.
Deep Link
Standardized mobile URL schemes (https://debelu.com/orders/:id, debelu://orders/:id) configured via Android Intent Filters and Apple Universal Links to seamlessly transition mobile users from browser links into the native Capacitor shell.
Session Handoff
A cryptographic protocol allowing users authenticated on the public marketing site (debelu-marketing) to seamlessly navigate into the authenticated storefront SPA (apps/storefront) via short-lived, signed single-use URL tokens without re-entering credentials.
Maker-Checker (4-Eyes Principle)
An enterprise security governance pattern requiring that two separate staff members authorize high-consequence operations (The Maker initiates the proposal; The Checker reviews and executes).
SBOM (Software Bill of Materials)
A formal, machine-readable inventory of all software dependencies, libraries, and hierarchical modules bundled into the platform, maintained in CycloneDX JSON format (sbom.json) to mitigate supply chain vulnerabilities.