Vendor Lifecycle Architecture

---

1. Executive Summary & The Vendor Journey

Campus merchants are the supply engine of Debelu. Because merchants sell physical items directly to fellow students within residential campuses, the vendor lifecycle is engineered around verified accountability, catalog integrity, and safe settlement.

stateDiagram-v2
    [*] --> ApplicationSubmitted : Vendor Application + Student ID Upload
    ApplicationSubmitted --> KYCVerification : Staff Verification & Document Check
    
    KYCVerification --> Approved : Compliance Clearance
    KYCVerification --> Rejected : Fraud / Non-Student / Duplicate Application
    
    Approved --> StoreSetup : Link NUBAN Bank & Configure Hub Pickup
    
    state ActiveMerchant {
        [*] --> CatalogManagement : List Products & Upload Media
        CatalogManagement --> OrderFulfillment : Receive Escrow Order
        OrderFulfillment --> DeliveryHandover : Courier / Hub Handover
        DeliveryHandover --> PayoutAccrual : Buyer Shares Delivery PIN
        PayoutAccrual --> PayoutDispatched : Batch Payout to Bank Account
    }

    StoreSetup --> ActiveMerchant
    
    ActiveMerchant --> Probation : Strike 2 Incurred (Listing Freeze)
    Probation --> ActiveMerchant : 30-Day Probation Satisfied
    ActiveMerchant --> Suspended : Strike 3 or Wire Fraud
    Suspended --> [*] : Permanent Deplatforming & Liquidation

---

2. Vendor Application & Identity Gatekeeping

Grounded in [debelu-backend/src/services/VendorService.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/services/VendorService.ts), merchant onboarding enforces strict security checks before an application can be created:

2.1 Pre-Flight Constraints

1. Emergency Onboarding Control: Evaluates assertSubsystemAvailable('vendorOnboardingDisabled'). If platform operations freezes onboarding, submissions halt immediately.
2. Account Status Assertions: User must have an active profiles.role === 'user'. Existing vendors, staff, or suspended accounts cannot re-apply.
3. Private Storage Isolation:

   // Enforces that uploaded ID documents reside strictly within user's private storage path
   if (!String(data.studentIdUrl || '').startsWith(`identity-verification/${userId}/`)) {
       throw new AppError('Upload your student ID before submitting', 400);
   }

4. Unique Store Slug Check: Store URLs (e.g. debelu.com/store/campus-kicks) are globally unique (/^[a-z0-9-]{1,40}$/). Collisions throw 409 Conflict.

---

3. KYC Verification & The Staff Approval Workspace

Applications are ingested into public.vendor_applications:

• Student Status Verification: Verification of matriculation numbers and student ID cards against participating university portals.
• Approval Trigger: When approved in the admin portal:
  • User role in public.profiles updates atomically from 'user' to 'vendor'.
  • Storefront profile initializes with is_verified = true and status = 'active'.

---

4. Bank Detail Binding & Virtual Accounts

Before a vendor can publish listings or receive orders:

1. NUBAN Bank Account Resolution: Vendor provides 10-digit account number and bank code. Verified via Paystack Resolve Account API (GET /bank/resolve).
2. Recipient Code Generation: Paystack creates a transfer recipient token (RCP_...) stored securely in public.vendor_bank_details.
3. The 24-Hour Cooldown Clock: Updating bank details resets vendor_bank_details.updated_at = now(), automatically locking withdrawals for 24 hours to prevent unauthorized fund diversion.

---

5. Catalog Governance & Change Tracking

Vendors publish products through ProductService:

graph TD
    subgraph Product Creation Pipeline
        INPUT[Vendor Product Payload] --> PG[PriceGuard Anomaly Check]
        INPUT --> MM[MediaModeration Gemini Vision]
        INPUT --> CF[Content & Prohibited Words Filter]
    end

    subgraph State & Listing Mutation
        PG -->|Price Ratio Valid| APPROVED_PUB[Active Marketplace Listing]
        PG -->|Gouging / Suspicious Underpricing| FLAG[Quarantine Queue in ModerationCase]
        MM -->|Prohibited Media / Phone Watermark| FLAG
        CF -->|Disintermediation Intent| FLAG
    end

    subgraph Audit & Historical Versioning
        APPROVED_PUB --> AUDIT[public.listing_changes Append-Only Log]
    end

Listing Modification Tracking (listing_changes)

To prevent "bait-and-switch" scams (e.g., selling a legitimate phone, then modifying the description to a broken case while orders are pending):

• Every mutation to price, name, images, or specifications generates an immutable audit record in public.listing_changes.
• Orders snapshot the product details at checkout time, immunizing existing buyers from vendor edits.

---

6. Fulfillment, Earnings & Dual-Authorization Payouts

1. Order Notification: Vendor receives push and email alerts upon successful escrow capture.
2. Fulfillment Modes:
   • Campus Hub Dropoff: Vendor delivers package to campus hub; runner logs intake.
   • Direct Student Meetup: Vendor meets buyer at agreed campus landmark (library, student union).
3. Delivery PIN Verification: Vendor requests the 4-digit PIN upon handover and inputs it via the Vendor Dashboard. Successful verification unlocks escrow.
4. Earnings & Batch Payouts:
   • Net earnings ($Total - Commission - Logistics$) credit the vendor's wallet balance.
   • Payouts are batched and disbursed via ReviewedPayoutBatchService and CanonicalPayoutTransfer directly to the vendor's verified NUBAN bank account.

---

7. Moderation, Strikes & Account Lifecycle

Vendors operate under the automated 3-Strike Governance Policy:

• Strike 1 (Warning): In-app warning for minor infractions (e.g., unfulfilled order, ChatGuard contact leak).
• Strike 2 (Probation): 7-day listing freeze; removal from campus trending algorithms.
• Strike 3 (Suspension): Account frozen; listings hidden; pending escrow quarantined for 90 days.
• Appeals: Managed via [ModerationAppealService.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/services/ModerationAppealService.ts) and reviewed by independent staff arbiters.