# 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