Platform Governance & Change Management Architecture

---

1. Executive Summary & The "4-Eyes Principle"

In high-assurance e-commerce and financial platforms, a fundamental threat vector is the unilateral insider threat or administrative operational blunder:

• An individual developer, support agent, or compromised staff credential modifying platform fee percentages, altering withdrawal limits, or granting arbitrary permissions.
• Accidental platform disruption through untested global setting overrides.

To mitigate this risk, Debelu implements the 4-Eyes Principle (Maker-Checker Governance) across all critical platform domains: $$\text{Change Enforcement} = \text{Proposal (Maker with AAL2)} + \text{Independent Review (Checker with AAL2)} \implies \text{Atomic Execution}$$

No single human or system role possesses the capability to unilaterally modify platform fees, category commissions, withdrawal ceilings, or security policies in production.

sequenceDiagram
    autonumber
    actor Maker as Staff Member (Maker)
    participant Svc as PlatformConfigurationProposalService
    participant DB as Postgres (RPC Security Definer)
    actor Checker as Senior Admin / Director (Checker)
    participant Cache as Redis Platform Controls Cache

    Maker->>Svc: 1. submit(proposalId, expectedRevision, patch, reason, aal)
    Note over Svc: Validates patch contains sensitive keys & reason <= 2000 chars
    Svc->>DB: 2. submit_platform_configuration_proposal()
    DB-->>Svc: 3. Returns Proposal Receipt (State: pending)
    
    Note over Svc,Checker: Time passes (Inspection & Audit Window)

    Checker->>Svc: 4. review(proposalId, approve: true, note, aal)
    Note over Svc: Enforces: Checker !== Maker AND Checker has AAL2 MFA
    Svc->>DB: 5. review_platform_configuration_proposal()
    DB->>DB: 6. Check expectedRevision === currentRevision
    DB->>DB: 7. Atomic UPDATE public.platform_settings & revision = revision + 1
    DB->>DB: 8. Insert Immutable Activation Receipt in audit_logs
    DB-->>Svc: 9. Returns Executed Receipt
    Svc->>Cache: 10. forgetPlatformControls() (Immediate Cache Eviction)

---

2. Platform Configuration Proposal Engine

The global configuration governing fee rates, security posture, and campus whitelists is managed exclusively via PlatformConfigurationProposalService ([debelu-backend/src/services/PlatformConfigurationProposalService.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/services/PlatformConfigurationProposalService.ts)).

2.1 Governed Configuration Attributes

Every proposed mutation must contain at least one sensitive parameter:

const patch = z.object({
  maintenanceMode: z.boolean().optional(),
  maintenanceMessage: z.string().max(280).nullable().optional(),
  featuredCampuses: z.array(z.string().min(1).max(200)).max(100).optional(),
  platformFeePercentage: z.number().min(0).max(50).refine(n => Math.abs(n * 100 - Math.round(n * 100)) < 1e-8).optional(),
  maxWithdrawalAmount: z.number().int().min(1000).max(100000000).optional(),
  autoApproveVendorKYC: z.boolean().optional(),
  requireStaffMfa: z.boolean().optional(),
  staffSessionTimeoutMinutes: z.number().int().min(5).max(720).optional(),
}).strict().refine(p => 
  ['platformFeePercentage', 'maxWithdrawalAmount', 'autoApproveVendorKYC', 'requireStaffMfa', 'staffSessionTimeoutMinutes'].some(k => k in p),
  { message: "Proposal must target at least one sensitive platform parameter" }
);

2.2 Authenticator Assurance Levels (AAL2 Enforcement)

• Proposing or reviewing platform configuration changes mandates AAL2 (Multi-Factor Authentication via TOTP or WebAuthn).
• Any request presenting AAL1 tokens (password only) is rejected with 403 Forbidden (42501), forcing staff re-authentication before governance actions can execute.

2.3 Optimistic Locking & Expiration

• Revision Check: Proposals require an expected_revision. If a competing proposal executes while review is underway, the subsequent review fails with 409 Conflict (40001 Serialization Failure).
• Automatic Expiration: Unreviewed proposals automatically shift to expired after their expires_at window lapses, preventing stale policy changes from applying without fresh review.

---

3. Category Commission Proposal Engine

In addition to the global platform fee, category-specific commissions (e.g., Electronics 5%, Fashion 10%, Textbook Exchange 2%) are governed by CategoryCommissionProposalService ([debelu-backend/src/services/CategoryCommissionProposalService.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/debelu-backend/src/services/CategoryCommissionProposalService.ts)).

3.1 Commission Mutation Lifecycle

stateDiagram-v2
    [*] --> Pending : submit(categoryId, revision, override, reason)
    
    Pending --> Executed : review(approve: true) [Distinct Checker]
    Pending --> Rejected : review(approve: false)
    Pending --> Expired : Time elapsed > expires_at
    Pending --> Stale : Base Category Revision Mutated
    
    Executed --> [*] : category_revision = revision + 1
    Rejected --> [*]
    Expired --> [*]
    Stale --> [*]

3.2 Backward Compatibility & Frozen History Invariant

• Executing a category commission proposal updates public.categories.commission_override and increments category_revision.
• Zero Historical Impact: Orders placed prior to the commission execution retain their original fee_snapshot basis points, preserving accounting accuracy and preventing vendor fee disputes.

---

4. Role-Based Access Control (RBAC) & Command Lifecycle

Debelu enforces fine-grained permissioning across staff operations via StaffAccessCommandService and StaffInvitationService:

erDiagram
    profiles ||--o| admin_roles : "assigned"
    admin_roles ||--o{ audit_logs : "records mutation"

    profiles {
        uuid id PK
        text role
        text status
        uuid admin_role_id FK
        jsonb admin_permissions
    }

    admin_roles {
        uuid id PK
        text slug
        boolean is_system
        jsonb permissions
        text_array campus_scope
    }

4.1 Granular Permissions Matrix

• canViewFinanceReports: Read-only access to ledger exports and settlement metrics.
• canApprovePayouts: Required to act as Checker on ReviewedPayoutBatch and PayoutTransferReconciliation.
• canManageOrders: Access to campus order case triage and dispute arbitration.
• canManageProducts: Access to moderation queue and listing restrictions.
• canManageUsers: Account suspension, strike management, and staff invitations.

4.2 Immutable Audit Invariant

Every administrative action, proposal decision, impersonation session, or role elevation emits an append-only row to public.audit_logs. Direct DELETE, UPDATE, or TRUNCATE operations on audit_logs are revoked at the Postgres engine level.