diff --git a/docs/core_saas_and_rbac_engine/COMPLETE_TENANT_CREATION_AND_RBAC_GUIDE.md b/docs/core_saas_and_rbac_engine/COMPLETE_TENANT_CREATION_AND_RBAC_GUIDE.md new file mode 100644 index 0000000..0cdf405 --- /dev/null +++ b/docs/core_saas_and_rbac_engine/COMPLETE_TENANT_CREATION_AND_RBAC_GUIDE.md @@ -0,0 +1,237 @@ +# 📘 Complete Guide: Multi-Tenant Provisioning & RBAC Security Engine + +> **For Engineers, QA Specialists, and Product Stakeholders** +> This guide explains the entire journey of how a **new company (Tenant)** is onboarded from scratch, and how **Roles and Permissions (RBAC)** control access to every screen, button, and API in the system. + +--- + +## 📑 Table of Contents +1. [What is a Tenant? (The Apartment Analogy)](#1-what-is-a-tenant-the-apartment-analogy) +2. [End-to-End Tenant Creation Lifecycle](#2-end-to-end-tenant-creation-lifecycle) +3. [The RBAC Security Architecture](#3-the-rbac-security-architecture) +4. [The 7 Permission Keys for Every Module](#4-the-7-permission-keys-for-every-module) +5. [Real-World Role Configurations](#5-real-world-role-configurations) +6. [How the Security Guard (Middleware) Works at Runtime](#6-how-the-security-guard-middleware-works-at-runtime) +7. [Platform SuperAdmin Impersonation (Support Mode)](#7-platform-superadmin-impersonation-support-mode) +8. [Database Visual Schema & Relationship Map](#8-database-visual-schema--relationship-map) + +--- + +## 1. What is a Tenant? (The Apartment Analogy) + +Imagine this software is a **giant cloud apartment building**: + +``` + ┌─────────────────────────────────────────┐ + │ OUR PIM CLOUD SERVER │ + └────────────────────┬────────────────────┘ + │ + ┌───────────────────────────────────┼───────────────────────────────────┐ + ▼ ▼ ▼ +┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐ +│ 🏢 Tenant A │ │ 🏢 Tenant B │ │ 🏢 Tenant C │ +│ (Nike Workspace) │ │ (Apple Workspace) │ │ (Sony Workspace) │ +│ │ │ │ │ │ +│ • Their own staff │ │ • Their own staff │ │ • Their own staff │ +│ • Their shoe catalog │ │ • Their electronics │ │ • Their audio gear │ +│ • Their media photos │ │ • Their media photos │ │ • Their media photos │ +└───────────────────────┘ └───────────────────────┘ └───────────────────────┘ +``` + +- **Tenant Isolation**: Every database table has a `tenant_id` column. When Nike logs in, their queries automatically execute with `WHERE tenant_id = 19`. It is physically impossible for Nike to see Apple's products or staff. + +--- + +## 2. End-to-End Tenant Creation Lifecycle + +When a new client signs up (or a Platform SuperAdmin clicks **"Create New Tenant"**), the backend executes an automated **6-step provisioning pipeline** inside a single safe transaction: + +```mermaid +sequenceDiagram + autonumber + actor Admin as Platform SuperAdmin + participant API as POST /api/v1/platform/tenants + participant DB as PostgreSQL Database + participant Seed as Auto-Provisioning Engine + participant Email as Notification Engine + + Admin->>API: Submit Tenant Form (Name: "Acme Corp", Admin Email: "boss@acme.com") + + rect rgb(240, 248, 255) + Note over API,DB: Step 1: Create Workspace Account + API->>DB: INSERT INTO tenants (name, code, status, plan_id) VALUES ('Acme Corp', 'acme_corp', 'active', 'enterprise') + DB-->>API: Returns new Tenant ID (e.g. tenant_id = 25) + + Note over API,DB: Step 2: Seed Default System Roles + API->>Seed: Provision Default Roles for Tenant 25 + Seed->>DB: INSERT INTO roles (TENANT_ADMIN, CATALOG_MANAGER, VIEWER) + + Note over API,DB: Step 3: Bind Permissions to Roles + Seed->>DB: Link all 12 Permission Nodes to TENANT_ADMIN with full 7-point flags + + Note over API,DB: Step 4: Create Initial Root Admin User + API->>DB: INSERT INTO users (email: 'boss@acme.com', password_hash, tenant_id: 25) + API->>DB: INSERT INTO user_roles (user_id, role_id: 'TENANT_ADMIN') + + Note over API,DB: Step 5: Seed Starter Taxonomy Primitives + Seed->>DB: INSERT starter Units (Piece, Set, Kilogram, Gram) + Seed->>DB: INSERT default Attribute Groups (General Specs, Physical Dimensions) + end + + API->>Email: Send Welcome Email & Password Setup Link to boss@acme.com + API-->>Admin: HTTP 201 Created (Tenant 25 Ready & Fully Operational) +``` + +--- + +## 3. The RBAC Security Architecture + +RBAC (Role-Based Access Control) decouples **People** from **Permissions** using a 3-layer hierarchy: + +``` +┌───────────────────────────┐ +│ 1. USERS │ physical people who log in (Alice, Bob, Charlie) +└─────────────┬─────────────┘ + │ assigned to (via user_roles) + ▼ +┌───────────────────────────┐ +│ 2. ROLES │ job badges (Tenant Admin, Photographer, Pricing Specialist) +└─────────────┬─────────────┘ + │ contains (via role_permissions) + ▼ +┌───────────────────────────┐ +│ 3. PERMISSION NODES │ system modules (Products, Media DAM, Channels, Users) +└───────────────────────────┘ +``` + +--- + +## 4. The 7 Permission Keys for Every Module + +For **every single module** in the system, there are **7 granular action switches**: + +```mermaid +graph TD + Module["🚪 System Module (e.g. Products)"] --> K1["👀 can_view: Search, browse, and view details"] + Module --> K2["➕ can_create: Click 'New Product' and save drafts"] + Module --> K3["✏️ can_edit: Modify descriptions, prices, specs"] + Module --> K4["🗑️ can_delete: Soft-delete or archive records"] + Module --> K5["🚀 can_alter: Publish products or alter schema"] + Module --> K6["📥 can_import: Bulk import CSV / Excel files"] + Module --> K7["📤 can_export: Download data to Excel / JSON"] +``` + +### Complete System Modules Registry: +| Module Code | Module Name | What It Controls | +| :--- | :--- | :--- | +| `products` | Product Catalog | Master product SKUs, prices, stock, and descriptions | +| `variants` | Product Variants | Matrix generator, color/size axes, and child SKU overrides | +| `families` | Product Families | Family blueprints, required attribute sets, and asset rules | +| `categories` | Categories | Hierarchical taxonomy tree and category assignments | +| `attributes` | Attributes & Sets | Dynamic specs, dropdown options, and attribute sets | +| `brands` | Brands | Manufacturer brands and allowed brand rules | +| `units` | Units of Measure | Measurement units (kg, pcs, cm) and conversion factors | +| `assets` | Digital Assets (DAM) | Image uploads, document attachments, and asset types | +| `channels` | Channels | Shopify, Amazon, and Custom CSV export integrations | +| `users` | Users & Roles | Inviting staff, creating roles, and assigning permissions | +| `audit_logs` | Audit Logs | Inspecting who changed what, timestamps, and IP history | +| `settings` | System Settings | Theme customization, organization branding, and billing | + +--- + +## 5. Real-World Role Configurations + +Here is how different job titles are configured using the 7-action matrix: + +### Role 1: "Junior Catalog Editor" (Intern) +- `products`: `can_view` ✅, `can_create` ✅, `can_edit` ✅, `can_delete` ❌, `can_alter` ❌, `can_export` ❌ +- `assets`: `can_view` ✅, `can_create` ✅ +- `users` & `settings`: All ❌ (Cannot view or change team members) + +### Role 2: "Photographer / Media Specialist" +- `assets`: `can_view` ✅, `can_create` ✅, `can_edit` ✅, `can_delete` ✅ +- `products`: `can_view` ✅ (To attach images), `can_edit` ❌ (Cannot change prices or stock) + +### Role 3: "Catalog Supervisor / Brand Manager" +- `products`: All 7 keys ✅ (Including `can_alter` to publish products to live sales channels) +- `families` & `categories`: All 7 keys ✅ + +--- + +## 6. How the Security Guard (Middleware) Works at Runtime + +Whenever a user takes any action in the application, the security guard inspects the request in **under 2 milliseconds**: + +``` +[ User clicks "Delete Product" in Browser ] + │ + ▼ +[ API Request: DELETE /api/v1/products/80c68220... ] + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 👮 SECURITY GUARD (permission.middleware.js) │ +│ │ +│ 1. Verify JWT Token ──► User ID 42 (Alice) │ +│ 2. Check User Type ──► Tenant User (tenant_id = 19) │ +│ 3. Check Admin Role ──► Is Alice TENANT_ADMIN? (No) │ +│ 4. Check Alice's Role ──► "Junior Catalog Editor" │ +│ 5. Check 'products' node ──► Is `can_delete` TRUE? │ +│ │ +│ ❌ Result: `can_delete` is FALSE! │ +└──────────────────────────────┬──────────────────────────────┘ + │ + ▼ + ┌──────────────────────────────────────────┐ + │ ⛔ HTTP 403 Forbidden Response: │ + │ "Insufficient permissions for action: │ + │ delete on module: products" │ + └──────────────────────────────────────────┘ +``` + +The database query **never runs**, the product is **never touched**, and an attempt log is written to `audit_logs`. + +--- + +## 7. Platform SuperAdmin Impersonation (Support Mode) + +If a customer (e.g. Tenant 19) opens a support ticket saying *"My attribute dropdown is stuck"*: + +1. A **Platform SuperAdmin** does NOT need the customer's password. +2. The SuperAdmin opens the Platform Admin dashboard and clicks **"Troubleshoot Tenant 19"**. +3. The frontend sends the header: + `x-impersonated-tenant-id: 19` +4. The backend context middleware detects this and temporarily scopes the session to Tenant 19 in **Audit-Tracked Support Mode**. +5. All actions taken while impersonating are stamped with `isImpersonating: true` in the audit logs. + +--- + +## 8. Database Visual Schema & Relationship Map + +```mermaid +erDiagram + TENANTS ||--o{ USERS : "contains" + TENANTS ||--o{ ROLES : "owns custom" + TENANTS ||--o{ PRODUCTS : "owns" + TENANTS ||--o{ ASSETS : "owns" + + USERS ||--o{ USER_ROLES : "assigned" + ROLES ||--o{ USER_ROLES : "links" + + ROLES ||--o{ ROLE_PERMISSIONS : "defines" + PERMISSION_NODES ||--o{ ROLE_PERMISSIONS : "guarded by" + + USERS ||--o{ AUDIT_LOGS : "executes" +``` + +--- + +## 🎯 Quick Verification Reference + +```bash +# 1. Verify Backend is running and routes are live +curl -sI http://localhost:5002/api/v1/categories + +# 2. Check TypeScript build integrity +cd productcatalogue_frontend && npx tsc --noEmit +``` diff --git a/docs/core_saas_and_rbac_engine/README.md b/docs/core_saas_and_rbac_engine/README.md index 19f3dc9..75f7bac 100644 --- a/docs/core_saas_and_rbac_engine/README.md +++ b/docs/core_saas_and_rbac_engine/README.md @@ -4,7 +4,15 @@ Welcome to the architectural and operational knowledge base for the **Core Multi --- -## 📑 Manuals & Reference Guides +## 🌟 Featured Comprehensive Guides + +| Guide | Target Audience & Contents | +| :--- | :--- | +| **[`COMPLETE_TENANT_CREATION_AND_RBAC_GUIDE.md`](file:///Users/maskantech/Desktop/PIM/docs/core_saas_and_rbac_engine/COMPLETE_TENANT_CREATION_AND_RBAC_GUIDE.md)** | **⭐ Start Here!** Plain-English, visual, end-to-end guide explaining Tenant Provisioning (the 6-step lifecycle), the 3 layers of RBAC, the 7-action permission flags, real-world role setups, runtime middleware guard, and support impersonation mode. | + +--- + +## 📑 In-Depth Engineering Manuals | File | Scope & Contents | | :--- | :--- |