LUUP One
Architecture Pack

Overview

This architecture pack defines LUUP One as a practical multi-tenant customer commerce platform. It is designed to help an external CTO validate whether the build has the right technical foundations for merchants, ambassadors, customers, missions, referrals, attribution, commissions, wallets, payouts, admin controls, automations, integrations, AI services, and security.

Build Architecture

LUUP runs on a Lovable + Supabase application stack with a Capacitor native shell, an Everflow-backed affiliate engine, Stripe Connect for payments, and the Lovable AI Gateway (Gemini 2.5 Pro) for every generative feature. The CTO should validate the actual implementation against this chain and confirm the handoff from AI-generated build to professional engineering process is in place.

C4 Architecture Model

The C4 model breaks the architecture into clear levels so the CTO can move from a high-level system view into the technical containers and backend components.

C4 Level 1: System Context

This shows where LUUP One sits in the world, who uses it, and what external systems it depends on.

C4 Level 2: Container Diagram

This shows the major technical blocks that make up LUUP One.

C4 Level 3: Component Architecture

Backend component view.

Data Model / ERD

This is one of the most important parts for the CTO. The data model should prove that LUUP One can support multiple merchants, multiple ecosystems, multiple brands, multiple users, multiple roles, referral hierarchies, attribution, commissions, wallets, payouts, and audit logs.

Security and Permissions Model

LUUP One should be designed around clear security principles. Authentication proves who the user is. Authorization controls what they can do. Tenant isolation controls what data they can access.

Authentication Model

Supabase Auth handles identity, sessions, verification and recovery. Email + Google OAuth, with disposable-email blocking and a custom edge hook that routes every auth email through Resend with branded templates.

Role Model

The permission model is intentionally simple. There are three roles: Super Admin, Merchant Admin, and User. A User may act as a customer, influencer, ambassador, or affiliate depending on how they engage with a merchant.

Permission Matrix

This matrix shows which roles can perform core platform actions. Use it as the basis for backend permission checks, not just frontend visibility rules.

Tenant Isolation Model

Tenant isolation is one of the most important parts of LUUP One because multiple merchants, brands, ecosystems, users, campaigns, referrals, wallets, and payouts exist inside the same platform.

Security Architecture Diagram

Every protected action should pass through authentication, role validation, tenant scope validation, permission validation, and audit logging.

Financial Security Model

Because LUUP One handles commissions, wallets, merchant float, payout requests, withdrawal fees, platform fees, refunds, and clawbacks, the financial model must be ledger-based.

Webhook Security Model

External systems are not trusted blindly. LUUP receives webhooks from Stripe, Mux, Everflow, and Smartlead. Each receiver is verify_jwt=false and validates an HMAC signature (Smartlead fails closed if its secret is missing) before persisting the raw payload and triggering downstream logic.

File Upload Security Model

LUUP missions may require screenshots, links, UGC, and proof files. These files should be private, tenant-scoped, and validated before storage. In the assumed build stack, this should use Supabase Storage.

Data Protection Model

LUUP One may store personal data, referral data, payout data, mission data, uploaded files, and earning history. The platform should minimise unnecessary storage and protect sensitive data throughout the lifecycle.

Admin and Audit Model

Every sensitive admin, financial, security, automation, AI, and operational action should be logged so Luup can reconstruct what happened during disputes, fraud reviews, payout reviews, and technical incidents.

The Most Important CTO Question