multitenetsaas/specs/001-1-target-sectors/data-model.md

Data Model

Core Entities

Tenant

Purpose: Represents a business organization with isolated data and workspace

Fields:

• id (UUID): Primary key
• name (String): Business name
• slug (String): URL-friendly identifier
• email (String): Primary contact email
• phone (String): Business phone number
• address (JSON): Business address (Malaysian format)
• business_type (Enum): RETAIL, HEALTHCARE, EDUCATION, LOGISTICS, BEAUTY
• subscription_plan (Enum): STARTER, GROWTH, PRO, ENTERPRISE
• pricing_model (Enum): SUBSCRIPTION, PERPETUAL
• status (Enum): PENDING, ACTIVE, SUSPENDED, TERMINATED
• logo_url (String): Company logo
• settings (JSON): Tenant-specific settings
• created_at (DateTime): Tenant creation timestamp
• updated_at (DateTime): Last update timestamp
• trial_ends_at (DateTime): Trial period end
• subscription_ends_at (DateTime): Current subscription end

Relationships:

• Has many Users
• Has many Subscriptions
• Has many Modules (through subscriptions)
• Has many Business Data entities

User

Purpose: Individuals within tenant organizations with roles and permissions

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• email (String): User email (unique within tenant)
• first_name (String): User first name
• last_name (String): User last name
• phone (String): User phone number
• role (Enum): ADMIN, MANAGER, STAFF, VIEWER
• status (Enum): PENDING, ACTIVE, INACTIVE, DISABLED
• last_login (DateTime): Last login timestamp
• created_at (DateTime): User creation timestamp
• updated_at (DateTime): Last update timestamp
• auth_methods (JSON): Enabled authentication methods
• mfa_enabled (Boolean): Multi-factor authentication status
• password_hash (String): Encrypted password

Relationships:

• Belongs to Tenant
• Has many Permissions
• Has many Audit Logs

Subscription

Purpose: Defines pricing plan, billing cycle, and module access for tenants

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• plan_type (Enum): STARTER, GROWTH, PRO, ENTERPRISE
• billing_cycle (Enum): MONTHLY, YEARLY, ONE_TIME
• status (Enum): ACTIVE, CANCELLED, EXPIRED, PENDING
• starts_at (DateTime): Subscription start date
• ends_at (DateTime): Subscription end date
• renews_at (DateTime): Next renewal date
• amount (Decimal): Subscription amount
• currency (String): Currency code (MYR)
• payment_method (String): Payment method token
• module_limit (Integer): Number of modules allowed
• user_limit (Integer): Number of users allowed
• features (JSON): Enabled features
• created_at (DateTime): Subscription creation timestamp
• updated_at (DateTime): Last update timestamp

Relationships:

• Belongs to Tenant
• Has many Subscription Modules
• Has many Payment Transactions

Module

Purpose: Industry-specific business functionality packages

Fields:

• id (UUID): Primary key
• name (String): Module name
• slug (String): URL-friendly identifier
• description (String): Module description
• industry (Enum): RETAIL, HEALTHCARE, EDUCATION, LOGISTICS, BEAUTY
• version (String): Module version
• status (Enum): ACTIVE, INACTIVE, BETA
• features (JSON): Module features
• requirements (JSON): System requirements
• created_at (DateTime): Module creation timestamp
• updated_at (DateTime): Last update timestamp

Relationships:

• Has many Subscription Modules
• Has many Module Permissions

Subscription Module

Purpose: Links subscriptions to specific modules

Fields:

• id (UUID): Primary key
• subscription_id (UUID): Foreign key to Subscription
• module_id (UUID): Foreign key to Module
• status (Enum): ACTIVE, INACTIVE, EXPIRED
• activated_at (DateTime): Activation timestamp
• expires_at (DateTime): Expiration timestamp
• settings (JSON): Module-specific settings

Relationships:

• Belongs to Subscription
• Belongs to Module

Payment Transaction

Purpose: Records of billing and payments

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• subscription_id (UUID): Foreign key to Subscription
• type (Enum): CHARGE, REFUND, CREDIT, ADJUSTMENT
• amount (Decimal): Transaction amount
• currency (String): Currency code (MYR)
• status (Enum): PENDING, COMPLETED, FAILED, REFUNDED
• payment_method (String): Payment method used
• transaction_id (String): External transaction ID
• description (String): Transaction description
• created_at (DateTime): Transaction creation timestamp
• updated_at (DateTime): Last update timestamp

Relationships:

• Belongs to Tenant
• Belongs to Subscription

Industry-Specific Models

Retail Module

Product

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• name (String): Product name
• sku (String): Stock keeping unit
• description (String): Product description
• category (String): Product category
• price (Decimal): Product price
• cost (Decimal): Product cost
• stock_quantity (Integer): Current stock
• reorder_point (Integer): Reorder threshold
• supplier_id (UUID): Supplier reference
• status (Enum): ACTIVE, INACTIVE, DISCONTINUED
• created_at (DateTime): Creation timestamp
• updated_at (DateTime): Last update timestamp

Sale

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• invoice_number (String): Invoice number
• customer_id (UUID): Customer reference
• subtotal (Decimal): Sale subtotal
• tax (Decimal): Tax amount
• total (Decimal): Sale total
• payment_method (String): Payment method
• status (Enum): PENDING, COMPLETED, REFUNDED
• created_at (DateTime): Sale timestamp
• updated_at (DateTime): Last update timestamp

Healthcare Module

Patient

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• medical_record_number (String): Medical record number
• first_name (String): Patient first name
• last_name (String): Patient last name
• ic_number (String): Malaysian IC number
• date_of_birth (Date): Date of birth
• gender (Enum): MALE, FEMALE, OTHER
• phone (String): Phone number
• email (String): Email address
• address (JSON): Patient address
• blood_type (String): Blood type
• allergies (JSON): Known allergies
• medical_conditions (JSON): Medical conditions
• created_at (DateTime): Creation timestamp
• updated_at (DateTime): Last update timestamp

Appointment

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• patient_id (UUID): Foreign key to Patient
• doctor_id (UUID): Foreign key to User (doctor)
• appointment_date (DateTime): Appointment date and time
• duration (Integer): Duration in minutes
• status (Enum): SCHEDULED, CONFIRMED, COMPLETED, CANCELLED, NO_SHOW
• type (Enum): CONSULTATION, FOLLOW_UP, PROCEDURE
• notes (Text): Appointment notes
• reminder_sent (Boolean): Reminder sent status
• created_at (DateTime): Creation timestamp
• updated_at (DateTime): Last update timestamp

Education Module

Student

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• student_id (String): Student ID
• first_name (String): Student first name
• last_name (String): Student last name
• date_of_birth (Date): Date of birth
• grade_level (String): Grade level
• parent_id (UUID): Parent user reference
• enrollment_date (Date): Enrollment date
• status (Enum): ACTIVE, INACTIVE, GRADUATED)
• emergency_contact (JSON): Emergency contact information
• created_at (DateTime): Creation timestamp
• updated_at (DateTime): Last update timestamp

Class

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• name (String): Class name
• grade_level (String): Grade level
• teacher_id (UUID): Teacher user reference
• max_students (Integer): Maximum students
• schedule (JSON): Class schedule
• academic_year (String): Academic year
• status (Enum): ACTIVE, INACTIVE)
• created_at (DateTime): Creation timestamp
• updated_at (DateTime): Last update timestamp

Logistics Module

Shipment

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• tracking_number (String): Tracking number
• order_id (String): Order reference
• sender_id (UUID): Sender reference
• recipient_id (UUID): Recipient reference
• origin (JSON): Origin address
• destination (JSON): Destination address
• weight (Decimal): Package weight
• dimensions (JSON): Package dimensions
• status (Enum): PENDING, IN_TRANSIT, DELIVERED, FAILED)
• estimated_delivery (DateTime): Estimated delivery
• actual_delivery (DateTime): Actual delivery
• carrier (String): Shipping carrier
• created_at (DateTime): Creation timestamp
• updated_at (DateTime): Last update timestamp

Vehicle

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• plate_number (String): Vehicle plate number
• type (String): Vehicle type
• capacity (Decimal): Vehicle capacity
• driver_id (UUID): Driver user reference
• status (Enum): ACTIVE, INACTIVE, MAINTENANCE)
• location (JSON): Current location
• last_maintenance (Date): Last maintenance date
• next_maintenance (Date): Next maintenance date
• created_at (DateTime): Creation timestamp
• updated_at (DateTime): Last update timestamp

Beauty Module

Client

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• first_name (String): Client first name
• last_name (String): Client last name
• phone (String): Phone number
• email (String): Email address
• date_of_birth (Date): Date of birth
• address (JSON): Client address
• preferences (JSON): Service preferences
• notes (Text): Client notes
• loyalty_points (Integer): Loyalty points
• created_at (DateTime): Creation timestamp
• updated_at (DateTime): Last update timestamp

Service

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• name (String): Service name
• description (String): Service description
• duration (Integer): Duration in minutes
• price (Decimal): Service price
• category (String): Service category
• status (Enum): ACTIVE, INACTIVE)
• created_at (DateTime): Creation timestamp
• updated_at (DateTime): Last update timestamp

Audit & Compliance Models

AuditLog

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• user_id (UUID): Foreign key to User
• action (String): Action performed
• entity_type (String): Type of entity affected
• entity_id (UUID): ID of entity affected
• old_values (JSON): Previous values
• new_values (JSON): New values
• ip_address (String): User IP address
• user_agent (String): User agent
• timestamp (DateTime): Event timestamp

DataRetention

Fields:

• id (UUID): Primary key
• tenant_id (UUID): Foreign key to Tenant
• entity_type (String): Type of data
• entity_id (UUID): ID of entity
• deletion_date (DateTime): Scheduled deletion date
• status (Enum): ACTIVE, DELETED, ARCHIVED)
• created_at (DateTime): Creation timestamp
• updated_at (DateTime): Last update timestamp

Relationships Summary

Tenant (1) → Many Users
Tenant (1) → Many Subscriptions
Tenant (1) → Many AuditLogs
Tenant (1) → Many DataRetention

Subscription (1) → Many SubscriptionModules
Subscription (1) → Many PaymentTransactions

Module (1) → Many SubscriptionModules

User (1) → Many AuditLogs

Validation Rules

Tenant Validation

• Name must be unique across all tenants
• Email must be valid format
• Phone number must follow Malaysian format
• Business type must be one of the supported industries

User Validation

• Email must be unique within tenant
• Role must be valid for user's permissions
• Password must meet security requirements

Subscription Validation

• Plan type must match module limits
• Billing cycle must be valid for plan type
• Amount must match plan pricing

Data Isolation

• All queries must include tenant_id filter
• Foreign key relationships must respect tenant boundaries
• Cross-tenant data access must be explicitly prevented

Compliance Requirements

PDPA 2010 Compliance

• All personal data must be encrypted at rest
• Data access must be logged and auditable
• Data retention policies must be enforced
• User consent must be obtained and recorded

Healthcare Data Protection

• Patient data must have additional access controls
• Medical records must have audit trails
• Emergency access must be logged and reviewed
• Data backup procedures must be HIPAA-compliant

Financial Data Protection

• Payment information must be tokenized
• Financial transactions must have audit trails
• Access to financial data must be restricted
• Compliance with Bank Negara Malaysia requirements