Tier-1 Living Documentation, Escrow Contracts, API Specifications & Operational Runbooks
High-level platform topology, domain-driven design, core state machines, and threat models.
| Document | Description |
|---|---|
| System Overview | Platform topology, multi-cloud infrastructure, C4 context diagrams, and external integrations |
| Escrow & Order Lifecycle | End-to-end payment collection → escrow locking → Delivery PIN verification → net payout state machine |
| Vendor Lifecycle | Vendor onboarding, Tiered KYC verification, product catalog governance, seller tiers, and strike system |
| Campus Operations | University campus commerce, student ambassador network, localized pickup hubs, and hostel logistics |
| Trust & Safety Architecture | ChatGuard (disintermediation shield), PriceGuard (anti-gouging), MediaModeration, and user safety |
| Financial Reconciliation & Settlement | Double-entry escrow ledger, Paystack settlement reconciliation, dual-authorization payouts, and wallet adjustments |
| Platform Governance & Change Management | The 4-Eyes Principle (Maker-Checker), configuration proposal lifecycle, commission rules, and staff RBAC |
| Authentication & Role-Based Access | Supabase Auth, JWT verification, session management, multi-role matrix, and RLS enforcement |
| Security Architecture & Threat Modeling | STRIDE threat model, OWASP Top 10 mitigations, API perimeter defenses, and database RLS policies |
| Nduzi AI Assistant Architecture | Gemini-powered multimodal conversational agent, intent routing, function calling tools, and semantic memory |
| Customer Support & Dispute System | Multi-channel ticketing, in-app chat escalation, dispute state transitions, and staff arbitration flows |
| Architecture Decision Records (ADR) | Canonical decision log capturing technical context, alternatives considered, and consequences |
Data privacy, financial compliance, anti-money laundering, and cardholder data boundary standards.
| Document | Description |
|---|---|
| Data Privacy & NDPR Compliance | Nigeria Data Protection Act/NDPR/GDPR posture, DSAR export engine, Right to Erasure, and PII inventory |
| Financial Compliance, AML & KYC Standards | Central Bank of Nigeria (CBN) regulatory scope, Tiered KYC (BVN/NIN), AML velocity monitoring, and SAR |
| PCI-DSS Scoping & Cardholder Data Demarcation | Self-Assessment Questionnaire A (SAQ-A) qualification, client tokenization, and zero-CDE footprint guarantee |
Step-by-step developer guides, monorepo conventions, test suites, and terminology.
| Document | Description |
|---|---|
| Domain Glossary | Canonical definitions for all Debelu business concepts, financial terminology, and technical acronyms |
| Local Environment Setup | Prerequisites, local Supabase emulation, master environment variable setup, and dev servers boot |
| Monorepo Workflow & Tooling | npm workspaces, Turborepo pipeline caching, shared package linking, and dependency management |
| Testing Strategy & Test Suites | Unit testing (Vitest/Jest), integration tests, Pact contract testing, Playwright E2E, and load testing |
| Contributing Standards & Code Style | Git branching strategy, Conventional Commits, TypeScript strictness, and automated CI review gates |
Independent surface guides for the storefront, backend, marketing, native mobile, and shared packages.
| Document | Description |
|---|---|
| Storefront Web Application | React 18 SPA, Vite, TanStack Query, Zustand state stores, Tailwind design tokens, and Cloudflare Pages |
| Backend API Service | Express API, 38 route modules, 64 domain services, BullMQ queues, middleware pipelines, and Fly.io compute |
| Marketing & Public Site | Next.js 15, App Router, Incremental Static Regeneration (ISR), technical SEO, auth entry points, and Vercel |
| Mobile Application (Capacitor) | Capacitor iOS and Android native packaging, push notifications, biometric auth, deep linking, and PWA |
| Shared Packages & Design System | @debelu/ui shared component library, @debelu/core business utilities, and design token synchronization |
Exhaustive technical contracts, database schemas, API specs, and configuration matrices.
| Document | Description |
|---|---|
| REST API Endpoints Catalog | Exhaustive catalog of all 38 backend route namespaces, HTTP verbs, payload parameters, and auth gates |
| API Standards, Versioning & Contracts | REST design principles, RFC 7807 Problem Details error catalog, Idempotency-Key spec, and rate limits |
| Webhook Specifications & Protocols | Paystack payment/transfer webhooks, WhatsApp API webhooks, HMAC SHA-512 signatures, and replay deduplication |
| Database Schema & Data Models | Postgres entity catalog, foreign key relationships, performance indexes, and Row-Level Security policies |
| Database Migration History & Guidelines | Chronological log of 97+ Supabase migrations, migration naming rules, and production deployment safety |
| Supabase Edge Functions | Deno serverless edge functions (paystack-webhook, notification dispatchers), deployment, and secrets |
| Master Environment Variables Matrix | Comprehensive cross-surface environment matrix across development, preview, staging, and production |
| Feature Flags Catalog | Unleash feature flag system, gradual rollout strategies, percentage targets, and emergency kill switches |
| Accessibility Standards (WCAG 2.1 AA) | Contrast compliance, keyboard navigation traps, ARIA guidelines, screen reader semantics, and axe-core tests |
| Internationalization (i18n) | i18next framework, locale detection, language resource bundles, and currency/date formatting conventions |
| SEO & Web Performance Optimization | Dynamic XML sitemaps, OpenGraph metadata, Core Web Vitals (LCP, INP, CLS), and cache-control headers |
| Scripts & Tooling Catalog | 60+ repository utility scripts: database smoke tests, seeders, verification probes, and automation tools |
Production infrastructure management, multi-cloud topology, monitoring, and release governance.
| Document | Description |
|---|---|
| Production Deployments & Topology | Multi-cloud CI/CD deployment pipelines (Fly.io, Cloudflare, Vercel), branch automation, and rollbacks |
| Disaster Recovery & Business Continuity (BCP) | Quantified RTO/RPO SLAs, Supabase PITR database restoration, multi-cloud regional failover, and BCP drills |
| SLOs, SLAs & Production Monitoring | Service Level Objectives (99.95% checkout), error budget burn rate alerts, health check probes, and Sentry |
| Monitoring, Observability & Alerting | Sentry distributed error tracking, 7-point deep health check engine, CWV telemetry, and Winston JSON logging |
| Incident Response Playbook | SEV-1 to SEV-4 incident classification, incident commander roles, war room protocols, and blameless RCAs |
| Release Process & Changelog Standards | Semantic Versioning (SemVer), pre-release verification gates, automated changelog generation, and SBOM |
Step-by-step Standard Operating Procedures for on-call engineers, dispute arbiters, and financial operations.
| Runbook | Purpose | Target Role |
|---|---|---|
| Payout Failure & Exception Resolution | Troubleshooting failed vendor bank transfers, Paystack exceptions, NUBAN verification, and retries | Financial Operations & On-Call |
| Escrow Dispute Arbitration | Evidence collection, decision matrix, and manual fund release/refund via Maker-Checker command services | Support Lead & Arbiters |
| Vendor Suspension & Enforcement | Immediate account freezes, delisting products, withholding payouts, handling in-flight orders, and appeals | Trust & Safety Team |
| Secrets & Credential Rotation | Zero-downtime rotation protocol for Paystack, Supabase, JWT, Gemini, and Cloudflare credentials | DevOps & Platform Leads |
Archived technical migration receipts, deployment checklists, and specific observation logs.
| Document | Category | Date / Reference |
|---|---|---|
| API Key Setup Guide | Legacy Setup | Third-party credential configuration |
| Production Operations Guide | Legacy Operations | Baseline service operations and access runbook |
| Infrastructure Migration Plan | Migration Plan | Multi-cloud hosting migration roadmap |
| DNS Migration Plan | Migration Plan | Cloudflare DNS cutover strategy |
| Browser Migration Runbook | Platform Runbook | Browser engine compatibility migration |
| Command Center Implementation Status | System Status | Operations command center implementation tracker |
| Command Center Migration Checklist | Checklist | Pre-flight and post-flight operational checklist |
| Command Center Production Migration Receipt | Audit Receipt | Production migration verification record (2026-10-05) |
| Command Center Queue Observations | Diagnostics | BullMQ background worker queue telemetry |
| Command Center Recovery Playbook | Playbook | Command center disaster and recovery procedures |
| Native Command Concurrency Verification | Verification | Concurrency and lock contention verification receipt |
| Product Improvement Audit | Audit Log | Platform-wide UX and performance improvement audit (2026-10-02) |
| Subject Privacy Export Delivery | Privacy Audit | Technical implementation notes for DSAR export delivery |
| Expanded Owned Privacy Exports | Privacy Audit | Expanded entity export inventory for compliance |
| Privacy Erasure Inventory Plans | Privacy Audit | Initial technical blueprint for data erasure pipelines |
| Privacy Erasure Inventory Next Slice | Privacy Audit | Incremental table deletion mapping for RTBF |
| Payout Exception Observations | Financial Audit | Technical observation log of payout transfer exceptions |
| Support Notification Outbox | Infrastructure | Transactional outbox pattern notes for customer support |
