Licensing Architecture v1

Payment & Provisioning Flow

1. Customer → /store/checkout
   ↓
2. Stripe Checkout Session Created
   ↓
3. Customer Completes Payment
   ↓
4. Stripe Webhook → /api/store/licenses/webhook
   ↓
5. Idempotency Check (processed_stripe_events)
   ↓
6. Transactional Provisioning:
   a. Create Tenant
   b. Generate License Key (hashed)
   c. Create Admin User
   d. Send Welcome Email with Magic Link
   ↓
7. Audit Log (provisioning_events)
   ↓
8. Customer Receives Access

Tenant Isolation Model

Database Level (RLS)

Row Level Security enabled on all tenant tables
tenant_id extracted from JWT user_metadata
Automatic filtering on SELECT queries
Service role bypasses RLS for admin operations

Application Level

withTenant middleware validates tenant context
Requests without tenant_id are rejected
Tenant context injected into all protected routes

License Enforcement

Check	Action on Failure
License exists	Block access, log violation
License not expired	Block access, log violation
Feature entitled	Block feature, log violation
User limit not exceeded	Block new user creation
Charge disputed/refunded	Suspend license immediately

Audit Trail

Tracked Events (provisioning_events)

payment_received
tenant_created
license_created
admin_created
email_sent
provisioning_failed (with error details)

All events include correlation_id (payment_intent_id) for end-to-end tracing.

Roadmap (Non-Blocking)

PlannedRedis-backed job queue for high-volume processing

PlannedAdmin dashboard for provisioning status monitoring

PlannedAutomated license renewal reminders

PlannedUsage-based billing integration

Security Controls

Payment Safety

• Stripe webhook signature verification
• Idempotency prevents duplicate processing
• Controlled checkout mode available

Data Isolation

• Row Level Security on all tenant tables
• Tenant context required for protected routes
• License keys stored as hashes

Provisioning

• Transactional with rollback on failure
• Admin user auto-created with magic link
• Full audit trail for debugging

Revenue Protection

• Dispute/refund triggers license suspension
• License violations logged
• Feature entitlement enforcement