Samir Boulahtit
f141cc4e6a
Move 39 documentation files from top-level docs/ into each module's docs/ folder, accessible via symlinks from docs/modules/. Create data-model.md files for 10 modules with full schema documentation. Replace originals with redirect stubs. Remove empty guide stubs. Modules migrated: tenancy, billing, loyalty, marketplace, orders, messaging, cms, catalog, inventory, hosting, prospecting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
161 lines
4.6 KiB
Markdown
161 lines
4.6 KiB
Markdown
# Tenancy Data Model
|
|
|
|
## Entity Relationship Overview
|
|
|
|
```
|
|
┌──────────────┐
|
|
│ Platform │
|
|
└──────┬───────┘
|
|
│ 1:N
|
|
▼
|
|
┌──────────────┐ ┌─────────────────┐
|
|
│ Merchant │────▶│ MerchantDomain │
|
|
└──────┬───────┘ 1:N └─────────────────┘
|
|
│ 1:N
|
|
▼
|
|
┌──────────────┐ ┌─────────────┐ ┌──────────────┐
|
|
│ Store │────▶│ StoreUser │────▶│ Role │
|
|
└──────┬───────┘ 1:N └──────┬──────┘ └──────────────┘
|
|
│ │
|
|
│ ▼
|
|
│ ┌──────────────┐
|
|
│ │ User │
|
|
│ └──────────────┘
|
|
│
|
|
├────▶ StoreDomain (1:N)
|
|
└────▶ StorePlatform (N:M bridge to Platform)
|
|
```
|
|
|
|
## Core Entities
|
|
|
|
### Platform
|
|
|
|
Top-level SaaS instance. All merchants and stores belong to a platform.
|
|
|
|
| Column | Type | Description |
|
|
|--------|------|-------------|
|
|
| `id` | Integer | Primary key |
|
|
| `name` | String | Platform name |
|
|
| `code` | String | Unique platform code |
|
|
| `is_active` | Boolean | Platform enabled/disabled |
|
|
|
|
### Merchant
|
|
|
|
Business entity that owns one or more stores.
|
|
|
|
| Column | Type | Description |
|
|
|--------|------|-------------|
|
|
| `id` | Integer | Primary key |
|
|
| `name` | String | Business name |
|
|
| `owner_user_id` | Integer | FK to User — the merchant owner |
|
|
| `contact_email` | String | Primary contact email |
|
|
| `is_active` | Boolean | Merchant active status |
|
|
|
|
### Store
|
|
|
|
A storefront belonging to a merchant. Central entity for multi-tenant scoping.
|
|
|
|
| Column | Type | Description |
|
|
|--------|------|-------------|
|
|
| `id` | Integer | Primary key |
|
|
| `merchant_id` | Integer | FK to Merchant |
|
|
| `name` | String | Store name |
|
|
| `code` | String | Unique store code (used in URLs) |
|
|
| `is_active` | Boolean | Store active status |
|
|
|
|
### User
|
|
|
|
Admin users at platform, merchant, or store level.
|
|
|
|
| Column | Type | Description |
|
|
|--------|------|-------------|
|
|
| `id` | Integer | Primary key |
|
|
| `email` | String | Unique email |
|
|
| `username` | String | Username |
|
|
| `role` | UserRole | `super_admin`, `platform_admin`, `merchant_owner`, `store_member` |
|
|
| `hashed_password` | String | Bcrypt password hash |
|
|
| `is_active` | Boolean | Account active status |
|
|
|
|
### StoreUser
|
|
|
|
Membership link between users and stores, with role assignment.
|
|
|
|
| Column | Type | Description |
|
|
|--------|------|-------------|
|
|
| `id` | Integer | Primary key |
|
|
| `store_id` | Integer | FK to Store |
|
|
| `user_id` | Integer | FK to User |
|
|
| `role_id` | Integer | FK to Role (NULL for owners) |
|
|
| `is_active` | Boolean | Membership active |
|
|
| `invitation_token` | String | Pending invitation token |
|
|
| `invitation_accepted_at` | DateTime | When invitation was accepted |
|
|
|
|
### Role
|
|
|
|
Permission roles for store team members.
|
|
|
|
| Column | Type | Description |
|
|
|--------|------|-------------|
|
|
| `id` | Integer | Primary key |
|
|
| `store_id` | Integer | FK to Store |
|
|
| `name` | String | Role name (Manager, Staff, etc.) |
|
|
| `permissions` | JSON | Array of permission strings |
|
|
|
|
## Supporting Entities
|
|
|
|
### AdminPlatform
|
|
|
|
Links admin users to platforms they can manage.
|
|
|
|
### StorePlatform
|
|
|
|
N:M bridge between stores and platforms.
|
|
|
|
### StoreDomain
|
|
|
|
Custom domain configuration for stores.
|
|
|
|
### MerchantDomain
|
|
|
|
Custom domain configuration for merchants.
|
|
|
|
### EmailVerificationToken
|
|
|
|
Tokens for verifying email addresses during registration.
|
|
|
|
### UserPasswordResetToken
|
|
|
|
Tokens for password reset flow.
|
|
|
|
### AdminAuditLog
|
|
|
|
Audit trail for admin actions.
|
|
|
|
### AdminSession
|
|
|
|
Active admin login sessions.
|
|
|
|
### AdminSetting
|
|
|
|
Platform/store-level admin settings (key-value).
|
|
|
|
### PlatformAlert
|
|
|
|
System alerts displayed to platform admins.
|
|
|
|
### PlatformModule
|
|
|
|
Tracks which modules are enabled per platform.
|
|
|
|
### ApplicationLog
|
|
|
|
Application log entries for the monitoring module.
|
|
|
|
## Key Relationships
|
|
|
|
- A **Platform** has many **Merchants** (via StorePlatform)
|
|
- A **Merchant** has many **Stores** and one **owner User**
|
|
- A **Store** has many **StoreUsers** (team members)
|
|
- A **StoreUser** has one **Role** (except owners who have all permissions)
|
|
- **User.role** determines the user type: `super_admin` > `platform_admin` > `merchant_owner` > `store_member`
|