# devbassel/saas_commerce architecture

> Architecture diagram of the GitHub repository devbassel/saas_commerce, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devbassel/saas_commerce
- Repository: https://github.com/devbassel/saas_commerce

## Overview

saas_commerce is a multi-tenant SaaS commerce platform: customers browse tenant storefronts and shop, store teams manage commerce and subscriptions, and platform operators administer tenants and plans. The principal flow runs from storefront or dashboard requests through the API’s tenant-aware authentication and domain services to tenant data and external payment/storage services. The README documents major capabilities that are not fully represented in the excerpts; those branches are included, but their internal call paths are not inferred.

Main entry points: [`apps/api/src/modules/subscriptions/services/subscription.service.ts`](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/subscriptions/services/subscription.service.ts) (Plans and Entitlements), [`apps/api/src/modules/auth/auth.service.ts`](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/auth/auth.service.ts) (Authentication), [`apps/api/src/main.ts`](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/main.ts) (NestJS API), [`apps/api/src/modules/products/products.service.ts`](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/products/products.service.ts) (Product Catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Customer and Admin Apps"]
  node_storefront["Customer Storefront"]
  node_store_dashboard["Store Admin Dashboard<br/>[App.tsx]"]
  node_platform_dashboard["Platform Admin Console<br/>[App.tsx]"]
end

subgraph group_identity["Identity and Tenancy"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_user_service["User and RBAC<br/>[users.service.ts]"]
  node_tenant_manager["Tenant Lifecycle"]
  node_tenant_scope["Tenant Scoping<br/>[tenant-scope.ts]"]
  node_email_otp["Email Verification"]
end

subgraph group_commerce["Commerce Operations"]
  node_catalog["Product Catalog"]
  node_categories["Categories"]
  node_cart["Shopping Cart<br/>[cart.service.ts]"]
  node_orders["Orders and Checkout<br/>[orders.service.ts]"]
  node_coupons["Coupons<br/>[coupons.service.ts]"]
end

subgraph group_platform["Platform Services"]
  node_subscriptions["Plans and Entitlements"]
  node_payments["Stripe Payments"]
  node_storage["Tenant File Storage<br/>[r2.service.ts]"]
end

subgraph group_infrastructure["Data and Integrations"]
  node_api["NestJS API<br/>[main.ts]"]
  node_tenant_db[("Tenant PostgreSQL Schemas")]
  node_cache[("Response Cache")]
  node_stripe["Stripe"]
  node_r2["Cloudflare R2"]
end

node_customer(("Store Customer"))

node_customer -->|"browses and shops"| node_storefront
node_storefront -->|"requests catalog and cart"| node_api
node_store_dashboard -->|"manages store"| node_api
node_platform_dashboard -->|"administers platform"| node_api
node_auth -->|"creates and looks up users"| node_user_service
node_auth -->|"provisions tenants"| node_tenant_manager
node_auth -->|"checks subscription"| node_subscriptions
node_auth -->|"requests and verifies OTP"| node_email_otp
node_catalog -.->|"uses tenant data"| node_tenant_db
node_orders -->|"processes payments"| node_payments
node_payments -->|"integrates with"| node_stripe
node_storage -->|"stores tenant files"| node_r2
node_subscriptions -.->|"stores plans and usage"| node_tenant_db
node_catalog -->|"caches tenant reads"| node_cache
node_catalog -->|"enforces product limits"| node_subscriptions
node_coupons -->|"enforces coupon entitlements"| node_subscriptions
node_orders -->|"enforces checkout limits"| node_subscriptions
node_api -.->|"resolves tenant context"| node_tenant_scope

click node_storefront "https://github.com/devbassel/saas_commerce/tree/main/apps/tenant_store"
click node_store_dashboard "https://github.com/devbassel/saas_commerce/blob/main/apps/store_owner_dashboard/src/App.tsx"
click node_platform_dashboard "https://github.com/devbassel/saas_commerce/blob/main/apps/super_admin_dashboard/src/App.tsx"
click node_api "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/main.ts"
click node_auth "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/auth/auth.service.ts"
click node_user_service "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/users/users.service.ts"
click node_tenant_manager "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/tenants/services/tenant-manager.service.ts"
click node_tenant_scope "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/tenants/utils/tenant-scope.ts"
click node_catalog "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/products/products.service.ts"
click node_categories "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/categories/categories.service.ts"
click node_cart "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/cart/cart.service.ts"
click node_orders "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/orders/orders.service.ts"
click node_coupons "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/coupons/coupons.service.ts"
click node_subscriptions "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/subscriptions/services/subscription.service.ts"
click node_payments "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/payments/stripe.payment.service.ts"
click node_storage "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/common/storage/r2.service.ts"
click node_email_otp "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/email-otp/email-otp.service.ts"
click node_tenant_db "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/common/config/data-source.factory.ts"
click node_cache "https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/common/cache/tenant-cache.service.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_storefront,node_store_dashboard,node_platform_dashboard toneBlue
class node_auth,node_user_service,node_tenant_manager,node_tenant_scope,node_email_otp toneAmber
class node_catalog,node_categories,node_cart,node_orders,node_coupons toneMint
class node_subscriptions,node_payments,node_storage toneRose
class node_api,node_tenant_db,node_cache,node_stripe,node_r2,node_customer toneIndigo
```

## Components

### Customer and Admin Apps

- [Customer Storefront](https://github.com/devbassel/saas_commerce/tree/main/apps/tenant_store): `apps/tenant_store`
- [Store Admin Dashboard](https://github.com/devbassel/saas_commerce/blob/main/apps/store_owner_dashboard/src/App.tsx): `apps/store_owner_dashboard/src/App.tsx`
- [Platform Admin Console](https://github.com/devbassel/saas_commerce/blob/main/apps/super_admin_dashboard/src/App.tsx): `apps/super_admin_dashboard/src/App.tsx`

### Identity and Tenancy

- [Authentication](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/auth/auth.service.ts): `apps/api/src/modules/auth/auth.service.ts`
- [User and RBAC](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/users/users.service.ts): `apps/api/src/modules/users/users.service.ts`
- [Tenant Lifecycle](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/tenants/services/tenant-manager.service.ts): `apps/api/src/modules/tenants/services/tenant-manager.service.ts`
- [Tenant Scoping](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/tenants/utils/tenant-scope.ts): `apps/api/src/modules/tenants/utils/tenant-scope.ts`
- [Email Verification](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/email-otp/email-otp.service.ts): `apps/api/src/modules/email-otp/email-otp.service.ts`

### Commerce Operations

- [Product Catalog](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/products/products.service.ts): `apps/api/src/modules/products/products.service.ts`
- [Categories](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/categories/categories.service.ts): `apps/api/src/modules/categories/categories.service.ts`
- [Shopping Cart](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/cart/cart.service.ts): `apps/api/src/modules/cart/cart.service.ts`
- [Orders and Checkout](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/orders/orders.service.ts): `apps/api/src/modules/orders/orders.service.ts`
- [Coupons](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/coupons/coupons.service.ts): `apps/api/src/modules/coupons/coupons.service.ts`

### Platform Services

- [Plans and Entitlements](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/subscriptions/services/subscription.service.ts): `apps/api/src/modules/subscriptions/services/subscription.service.ts`
- [Stripe Payments](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/modules/payments/stripe.payment.service.ts): `apps/api/src/modules/payments/stripe.payment.service.ts`
- [Tenant File Storage](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/common/storage/r2.service.ts): `apps/api/src/common/storage/r2.service.ts`

### Data and Integrations

- [NestJS API](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/main.ts): `apps/api/src/main.ts`
- [Tenant PostgreSQL Schemas](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/common/config/data-source.factory.ts): `apps/api/src/common/config/data-source.factory.ts`
- [Response Cache](https://github.com/devbassel/saas_commerce/blob/main/apps/api/src/common/cache/tenant-cache.service.ts): `apps/api/src/common/cache/tenant-cache.service.ts`
- **Stripe**
- **Cloudflare R2**

### Other components

- **Store Customer**

## Connections

- Store Customer → Customer Storefront: browses and shops
- Customer Storefront → NestJS API: requests catalog and cart
- Store Admin Dashboard → NestJS API: manages store
- Platform Admin Console → NestJS API: administers platform
- Authentication → User and RBAC: creates and looks up users (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Authentication → Tenant Lifecycle: provisions tenants (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Authentication → Plans and Entitlements: checks subscription (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Authentication → Email Verification: requests and verifies OTP (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Product Catalog → Tenant PostgreSQL Schemas: uses tenant data
- Orders and Checkout → Stripe Payments: processes payments
- Stripe Payments → Stripe: integrates with
- Tenant File Storage → Cloudflare R2: stores tenant files
- Plans and Entitlements → Tenant PostgreSQL Schemas: stores plans and usage
- Product Catalog → Response Cache: caches tenant reads
- Product Catalog → Plans and Entitlements: enforces product limits
- Coupons → Plans and Entitlements: enforces coupon entitlements
- Orders and Checkout → Plans and Entitlements: enforces checkout limits
- NestJS API → Tenant Scoping: resolves tenant context