LUUP One
Architecture Pack
A CTO-ready architecture reference for validating the LUUP One build across platform structure, system context, containers, components, data relationships, security, permissions, financial controls, webhooks, automation, AI services, and operational readiness.
This pack explains how LUUP One should be structured as a multi-tenant customer commerce platform connecting merchants, customers, ambassadors, creators, missions, referrals, attribution, commissions, wallets, payouts, admin operations, automations, AI services, and external integrations.
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.
What this pack covers
- How LUUP One sits in the wider ecosystem
- Which users and external systems interact with the platform
- The expected Lovable, Supabase, GitHub, n8n, and AI services architecture
- How the main application containers fit together
- How backend components should be organised
- How the data model should support merchants, ecosystems, referrals, commissions, wallets, and payouts
- How roles, permissions, and tenant isolation should work
- How financial events, webhooks, files, and audit logs should be secured
- What the external CTO should validate before beta, paid merchants, and scale
Core validation question
Is LUUP One built as a real multi-tenant SaaS platform, or is it a high-fidelity prototype that needs a production-grade backend?
Build Architecture Assumption
This architecture pack assumes LUUP One is being built using a modern Lovable and Supabase-based application architecture. The CTO should validate whether the actual implementation follows this structure and whether the handoff from AI-generated build to professional engineering process has been handled correctly.
Expected technical stack
What the CTO should confirm
- The Lovable frontend is connected to a real Supabase backend
- The source code is connected to GitHub and owned by LUUP
- Supabase Auth is used properly for user identity and session management
- PostgreSQL is being used as the database foundation
- Row Level Security is enabled and tested
- Business logic is handled through backend functions, not only frontend code
- Supabase Storage is configured with private buckets where needed
- Edge Functions are used for sensitive operations
- n8n is used only for appropriate automations, not critical financial logic without controls
- External API keys are stored securely
- AI services are called from secure backend functions, not directly from the frontend
- Production and staging environments are separated
- The app can be maintained by engineers outside Lovable
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.
System Context
Container Architecture
Component Architecture
Code-Level Detail
For the external CTO review, Levels 1 to 3 are enough to assess whether the build has the right architectural foundations.
C4 Level 1: System Context
This shows where LUUP One sits in the world, who uses it, and what external systems it depends on.
LUUP One Platform
Platform users
Luup Admin Team
Merchant / Brand Team
Ambassador / Creator / Customer Advocate
End Customer
External systems
Stripe
PayPal
Bank Transfer Process
Everflow
Shopify / Commerce Store
Email / Notifications Provider
Supabase Storage
Analytics / Logging
n8n Automation Layer
AI Services
C4 Level 2: Container Diagram
This shows the major technical blocks that make up LUUP One.
Lovable React / Vite Frontend
- Mission discovery
- Ecosystem joining
- Profile setup
- Referral links
- Storefronts
- Wallet view
- Earnings tracking
- Payout requests
- Leaderboards
- Badges and gamification
GitHub
- The project is connected to GitHub
- LUUP owns the repository
- Changes can be reviewed through pull requests
- Engineers can work on the codebase outside Lovable
- Deployment and rollback practices are clear
Merchant Dashboard
- Merchant onboarding
- Plan selection
- Billing card setup
- Wallet top-up
- Mission creation
- Product management
- Submission review
- Ambassador management
- Campaign analytics
- Revenue and ROI reporting
- Team member management
Admin Dashboard
- Merchant management
- User management
- Platform fee configuration
- Commission rules
- Payout reviews
- Manual adjustments
- Fraud flags
- White-label settings
- Audit logs
- System-wide reporting
Supabase Edge Functions / Backend APIs
- Authentication checks
- Role checks
- Tenant scoping
- Mission logic
- Referral logic
- Commission calculations
- Wallet transactions
- Payout requests
- Merchant settings
- Admin actions
- Data validation
- Secure external API calls
- AI service calls
- Webhook processing support
- API responses
Supabase Auth
- Signup
- Login
- Password reset
- Email verification
- Session management
- Role assignment
- OAuth, if used
- Multi-factor authentication, if introduced later
Supabase PostgreSQL
- Users
- Merchants
- Brands
- Ecosystems
- Missions
- Submissions
- Products
- Referral links
- Clicks
- Orders
- Commission rules
- Commissions
- Wallets
- Wallet transactions
- Payouts
- Billing records
- Audit logs
Supabase Storage
- User avatars
- Merchant logos
- Mission images
- Product images
- Screenshot proofs
- Uploaded UGC
- Campaign files
Webhook Processor
- Stripe
- PayPal
- Everflow
- Shopify
- Payment succeeded
- Subscription created
- Order created
- Order refunded
- Conversion tracked
- Payout failed
- Wallet top-up completed
Commission Engine
- Tier 1 commission
- Tier 2 commission
- Tier 3 commission
- Tier 4 commission
- Mission rewards
- Referral rewards
- Platform fees
- Refund clawbacks
- Pending versus cleared commissions
Configurable per merchant, campaign, or ecosystem.
Wallet Ledger Service
Tracks all money movements.
- Pending commission
- Approved commission
- Cleared balance
- Withdrawal request
- Withdrawal fee
- Payout completed
- Payout failed
- Refund reversal
- Manual adjustment
- Merchant wallet top-up
- Merchant spend
- Platform fee deduction
n8n Automation Layer
- Internal alerts
- Admin notifications
- CRM sync
- Email workflows
- Data enrichment
- Scheduled checks
- Operational handoffs
- Non-critical integration glue
AI Orchestration Layer
- AI-assisted mission creation
- Content suggestions
- Campaign recommendations
- Support workflows
- Data enrichment
- Admin productivity tools
Notification Service
- Mission updates
- Submission approvals
- Submission rejections
- Payout updates
- Wallet changes
- Merchant billing notices
- Campaign alerts
- Admin alerts
Analytics and Reporting Layer
- Merchant GMV
- Revenue generated
- Clicks
- Conversions
- Commission paid
- Mission performance
- Ambassador ranking
- Campaign ROI
- Luup platform revenue
- Payout liability
- User growth
C4 Level 3: Component Architecture
Backend component view.
Component responsibilities
User Service
- User profiles
- Account creation
- Identity
- Avatar
- Display name
- Contact details
- Status
- Account suspension
Tenant / Workspace Service
- Merchant workspaces
- Brand workspaces
- Ecosystem access
- Tenant boundaries
- User membership
- Role assignment per workspace
Merchant Service
- Merchant profile
- Merchant settings
- Billing status
- Wallet funding status
- Commission settings
- Platform fee settings
- Team members
- Store connections
Ecosystem Service
- Theme
- Branding
- Missions
- Products
- Users
- Ranks
- Badges
- Commission rules
- Campaign logic
Mission Service
- Mission creation
- Mission editing
- Mission status
- Mission capacity
- Mission deadlines
- Reward rules
- Mission visibility
- Mission duplication
- Mission analytics
Submission Review Service
- User submissions
- Proof uploads
- Approval
- Rejection
- Reviewer feedback
- Submission history
- Fraud flags
- Bulk approvals
Product Service
- Product catalogue
- Product images
- Product pricing
- Product categories
- Product tags
- Featured products
- Storefront products
- Affiliate link generation
Referral Service
- Referral codes
- Referral links
- Ambassador links
- Customer referral links
- Storefront links
- Referral tree
- Referral ownership
- Referral hierarchy
Attribution Service
- Click tracking
- Signup tracking
- Customer attribution
- Order attribution
- Repeat purchase attribution
- First-click or last-click rules
- Everflow data matching
- Manual attribution corrections
Order Service
- Order creation
- Order value
- Customer ID
- Merchant ID
- Product line items
- Refund status
- Cancellation status
- Attribution status
- Commission status
Commission Engine
- Tier 1 commission
- Tier 2 commission
- Tier 3 commission
- Tier 4 commission
- Mission rewards
- Product-specific commission
- Merchant-specific rules
- Refund clawbacks
- Fee deductions
- Pending and cleared states
Wallet Ledger Service
- User wallet
- Merchant float wallet
- Platform fee wallet
- Ledger entries
- Balance calculation
- Pending funds
- Cleared funds
- Adjustments
- Reversals
Payout Service
- Payout requests
- Minimum payout threshold
- Payout approval
- Payout method
- Payout status
- Payout failure
- Payout retry
- Withdrawal fees
- Payout audit logs
Billing Service
- Merchant subscriptions
- Stripe billing
- Plan changes
- Card setup
- Subscription renewal
- Failed payments
- Trial status
- Wallet top-ups
- Invoices
Admin Service
- View all merchants
- View all users
- Pause merchants
- Suspend users
- Adjust wallet transactions
- Configure platform fees
- Resolve disputes
- Approve payouts
- Manage white-label settings
Audit Log Service
- Role changed
- Mission created
- Mission approved
- Commission generated
- Wallet adjusted
- Payout requested
- Payout approved
- Merchant fee changed
- Webhook received
- Admin override performed
Notification Service
File Upload Service
Automation Orchestration Service
AI Orchestration Service
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.
The data model should support
- Multiple merchants
- Multiple ecosystems
- Multiple brands
- Multiple users
- Multiple roles
- Referral hierarchies
- Attribution
- Commissions
- Wallets
- Payouts
- Audit logs
Do not include detailed table definitions in this section. The ERD and high-level entity relationship model are enough for this page.
Core entity groups
Identity and access
- Users
- Profiles
- User roles
- Merchant team members
- Ecosystem memberships
Merchant and ecosystem structure
- Merchants
- Brands
- Ecosystems
- Products
- Missions
Campaign participation
- Mission submissions
- Mission rewards
- Badges
- Leaderboards
Referral and attribution
- Referral links
- Clicks
- Customers
- Orders
- Order items
Commission and wallet logic
- Commission rules
- Commissions
- Wallets
- Wallet transactions
- Payout requests
- Billing subscriptions
Governance and audit
- Audit logs
- Admin actions
- Webhook events
- Financial adjustments
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 proves who the user is
Authorization controls what they can do
Tenant isolation controls what data they can access
Audit logs record important actions
Financial actions must be ledger-based
External webhooks must be verified
Sensitive files must be private
No sensitive logic should live only in the frontend
AI service calls must happen through backend-controlled functions
Automation workflows must not bypass security or financial controls
Authentication Model
The authentication layer should provide secure identity, session handling, verification, and recovery. In the assumed build stack, this should be handled by Supabase Auth.
Minimum supported authentication
- Email and password
- Email verification
- Password reset
- Secure session management
- Supabase Auth integration
Recommended authentication
- Google OAuth
- Multi-factor authentication for admins
- Multi-factor authentication for merchant owners
- Session revocation
- Device/session visibility
- Strong password rules
- Clear separation between staging and production users
Role Model
The permission model should support platform-level roles, merchant-level roles, and user-level roles. A user may have different permissions in different merchant workspaces or ecosystems.
Platform-level roles
Super Admin
Luup internal owner-level access.
- View all merchants
- View all users
- View all payouts
- Configure platform fees
- Manage white-label settings
- Suspend merchants
- Suspend users
- Approve high-risk payouts
- Create admin users
- Access audit logs
Admin Operator
Luup internal ops role.
- View merchants
- View users
- Review submissions
- Review payouts
- Handle support
- Flag fraud
- View audit logs
- Change platform fees
- Create super admins
- Delete critical records
- Change financial settings without approval
Finance Admin
Luup internal finance role.
- View merchant float balances
- View payout requests
- Approve payouts
- Reject payouts
- View wallet ledgers
- Export finance reports
- Create missions
- Change campaign settings
- Change platform configuration
Merchant-level roles
Merchant Owner
- Manage merchant settings
- Manage billing
- Add card details
- Top up wallet
- Create missions
- Approve submissions
- Manage products
- Invite team members
- View reporting
- Export data
- Configure commission rules, if allowed
Merchant Admin
- Create missions
- Edit missions
- Approve submissions
- Manage products
- View ambassadors
- View analytics
- Invite limited team members
- Change billing
- Change ownership
- Change platform fees
- Approve large payouts unless permitted
Campaign Manager
- Create and edit missions
- View mission performance
- Review submissions
- Message participants
- Access billing
- Access payout settings
- Adjust wallets
- Invite finance users
Reviewer
- View assigned submissions
- Approve submissions
- Reject submissions
- Add reviewer feedback
- Create missions
- Access billing
- View full financial reports
- Adjust rewards manually
Finance Viewer
- View invoices
- View wallet top-ups
- View commission liability
- Export finance reports
- Approve submissions
- Create missions
- Change billing method
- Approve payouts
User-level roles
Ambassador / Creator
- Join ecosystems
- Complete profile
- Join missions
- Submit proof
- Generate referral links
- View own clicks, sales, and earnings
- Request payouts
- View own wallet ledger
- Access merchant dashboards
- Approve submissions
- Change commissions
- View other users' earnings
- Access another ecosystem unless joined
Customer Advocate
Similar to ambassador, but may have fewer advanced creator features.
- Refer friends
- Access referral links
- Earn customer rewards
- View own earnings
- Request payouts, if enabled
End Customer
- Purchase through referral links
- Create an account, if needed
- Join later as an advocate, if enabled
- Access dashboard
- View commissions
- Access private mission data
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.
| Action | Super Admin | Admin Operator | Finance Admin | Merchant Owner | Merchant Admin | Campaign Manager | Reviewer | Ambassador |
|---|---|---|---|---|---|---|---|---|
| View all merchants | Yes | Yes | Limited | No | No | No | No | No |
| Create merchant | Yes | Yes | No | No | No | No | No | No |
| Suspend merchant | Yes | Limited | No | No | No | No | No | No |
| Manage billing | Yes | No | View only | Yes | No | No | No | No |
| Top up merchant wallet | Yes | No | Yes | Yes | No | No | No | No |
| Create mission | Yes | Yes | No | Yes | Yes | Yes | No | No |
| Edit mission | Yes | Yes | No | Yes | Yes | Yes | No | No |
| Approve submission | Yes | Yes | No | Yes | Yes | Yes | Yes | No |
| Reject submission | Yes | Yes | No | Yes | Yes | Yes | Yes | No |
| Join mission | No | No | No | No | No | No | No | Yes |
| Submit proof | No | No | No | No | No | No | No | Yes |
| Generate referral link | No | No | No | No | No | No | No | Yes |
| View own earnings | No | No | No | No | No | No | No | Yes |
| View all user earnings | Yes | Limited | Yes | Merchant only | Merchant only | No | No | No |
| Adjust wallet | Yes | No | Limited | No | No | No | No | No |
| Request payout | No | No | No | No | No | No | No | Yes |
| Approve payout | Yes | No | Yes | Optional | No | No | No | No |
| View audit logs | Yes | Yes | Finance only | Merchant only | No | No | No | No |
| Change platform fees | Yes | No | No | No | No | No | No | No |
| Manage team members | Yes | No | No | Yes | Limited | No | No | No |
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.
Recommended tenant boundary
The recommended tenant boundary is merchant_id as the commercial workspace boundary.
- brand_id for brands under a merchant
- ecosystem_id for verticals or white-label environments
- user_id for individual user ownership
Core rule
Every sensitive table should be scoped by at least one of these:
- merchant_id
- brand_id
- ecosystem_id
- user_id
Scope examples
Need merchant_id and ecosystem_id.
Need merchant_id and brand_id.
Need merchant_id.
Need merchant_id and earning_user_id.
Need owner_type and owner_id.
Need user_id and wallet_id.
Need actor_user_id and merchant_id where relevant.
Access control rules
Merchant data access
Ecosystem access
Wallet access
A merchant can only view merchant float wallets where wallet.owner_type = merchant and wallet.owner_id = merchant_id they belong to.
Admin access
Supabase Row Level Security validation
- RLS should be enabled on sensitive tables
- Policies should scope data by merchant_id, ecosystem_id, brand_id, or user_id
- Users should not be able to access data by changing IDs in URLs or API calls
- Service role keys must not be exposed in frontend code
- Admin cross-tenant access should be performed through secure backend functions
- RLS policies should be tested with real test users across different roles
Security Architecture Diagram
Every protected action should pass through authentication, role validation, tenant scope validation, permission validation, and audit logging.
Every protected action should pass through
- Authentication
- Role validation
- Tenant scope validation
- Permission validation
- Row Level Security where applicable
- 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.
Ledger-based wallet principle
Required protections
Webhook Security Model
External systems should not be trusted blindly. Webhooks from Stripe, Everflow, Shopify, and PayPal must be verified, stored, processed once, and logged.
Required webhook controls
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.
Personal data LUUP may store
- Name
- Profile image
- Country
- Payment method references
- Payout method references
- Referral activity
- Mission submissions
- Wallet and earning history
Recommended controls
- Encrypt data in transit
- Encrypt data at rest
- Hash sensitive identifiers where possible
- Avoid storing unnecessary payment data
- Use Stripe or payment providers for card data
- Use private Supabase Storage buckets
- Allow user data deletion where legally required
- Keep audit logs for financial and compliance reasons
- Create a clear data retention policy
- Keep AI prompts and outputs out of sensitive records unless necessary
- Avoid sending unnecessary personal or financial data to AI providers
- Separate staging and production data
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.
Actions to log
Audit log should include
- Actor user ID
- Action
- Entity type
- Entity ID
- Merchant scope
- Old value, where needed
- New value, where needed
- Timestamp
- IP hash
- Metadata
- Source system
- Related webhook event, where relevant
- Related automation workflow, where relevant
CTO Review Checklist
Use this checklist during the external CTO review. Each item should be validated against the actual LUUP One build, not just the design or prototype.
Architecture
9 items- Is the platform multi-tenant?To validate
- Is tenant isolation enforced at backend/database level?To validate
- Is the app one codebase for multiple ecosystems?To validate
- Are white-label settings configurable?To validate
- Can merchants self-onboard?To validate
- Are integrations real or mocked?To validate
- Is the Lovable frontend connected to a real Supabase backend?To validate
- Is the codebase connected to GitHub?To validate
- Can engineers maintain the codebase outside Lovable?To validate
Data
7 items- Is there a proper relational data model?To validate
- Are commissions traceable to orders?To validate
- Are wallet balances ledger-based?To validate
- Are audit logs implemented?To validate
- Are refunds and clawbacks handled?To validate
- Is PostgreSQL being used as the database foundation?To validate
- Are database relationships, constraints, and indexes appropriate?To validate
Security
8 items- Are permissions enforced server-side?To validate
- Can merchants access only their own data?To validate
- Is Supabase Row Level Security enabled and tested?To validate
- Are webhook signatures verified?To validate
- Are API keys stored securely?To validate
- Are uploaded files private?To validate
- Are payout actions logged?To validate
- Are service role keys kept out of frontend code?To validate
Financial logic
7 items- Is the 4-tier commission model configurable?To validate
- Are pending and cleared balances separate?To validate
- Can users withdraw only cleared funds?To validate
- Are failed payouts handled?To validate
- Are duplicate payouts prevented?To validate
- Are merchant float balances tracked?To validate
- Is n8n prevented from bypassing financial controls?To validate
Automation and AI
6 items- Is n8n used only for appropriate non-critical workflows?To validate
- Are n8n workflows logged and monitored?To validate
- Are AI API calls made through backend functions?To validate
- Are AI API keys hidden from the frontend?To validate
- Is sensitive personal or financial data kept out of AI prompts where possible?To validate
- Are AI outputs reviewed or validated before affecting important records?To validate
Recommended Architecture Pack Structure
For the external CTO, present the architecture in this order so the review starts with product truth, moves into system design, then validates data, flows, security, automation, AI usage, and roadmap.
- 01Truth Table
Built, partially built, mocked, not built.
- 02Build Architecture Assumption
Lovable, React, Vite, Supabase Auth, PostgreSQL, Supabase Storage, Edge Functions, GitHub, n8n, external services, and AI APIs.
- 03System Context
Who uses LUUP One and what systems it connects to.
- 04Container Architecture
Frontend, backend, database, storage, webhooks, commission engine, wallet ledger, n8n automation layer, AI orchestration layer.
- 05Data Model / ERD
Core entities and relationships.
- 06Key Flows
Merchant onboarding, mission creation, ambassador activation, attribution and commission, wallet and payout, refund and clawback.
- 07Security and Permissions
Roles, tenant isolation, Row Level Security, backend permission checks, webhook security, file security, audit logs.
- 08Automation and AI Controls
Where n8n and AI services are appropriate, where they are not appropriate, and what controls are required.
- 09Technical Debt and Roadmap
What must be fixed before beta, before paid merchants, and before scale.
Final Assessment
The robustness of LUUP One does not come from AI-generated code alone. It comes from using standard technologies, source-code ownership, PostgreSQL as the database foundation, proper Row Level Security, secure backend-controlled business logic, scalable infrastructure options, and professional engineering review processes.
Conclusion
A Lovable and Supabase application that is connected to GitHub, reviewed using professional engineering tools, protected by Row Level Security, and deployed using accepted software engineering practices can legitimately be described as a robust and scalable modern web application architecture suitable for SaaS products, internal business systems, customer portals, CRM platforms, and AI-enabled business applications.
The Most Important CTO Question
Is LUUP One built as a real multi-tenant SaaS platform, or is it a high-fidelity prototype that needs a production-grade backend?
This architecture pack gives the review structure needed to answer that honestly and professionally.
Recommended next stepValidate the real build against this architecture, then produce a truth table showing what is built, partially built, mocked, or missing.