docs: add complete visual Tenant Creation and RBAC guide
This commit is contained in:
Inamul-hasan-tec
@@ -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
|
||||
```
|
||||
@@ -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 |
|
||||
| :--- | :--- |
|
||||
|
||||
Reference in New Issue
Block a user