@valentine-efagene/qshelter-common 2.0.94 → 2.0.96

package/prisma/schema.prisma.backup

@@ -0,0 +1,2601 @@
+// =============================================================================
+// QSHELTER UNIFIED DATABASE SCHEMA
+// =============================================================================
+// This schema contains all database models for the QShelter platform
+// Organized by domain for better readability
+// =============================================================================
+
+generator client {
+  provider   = "prisma-client"
+  output     = "../generated/client"
+  engineType = "client"
+}
+
+datasource db {
+  provider = "mysql"
+}
+
+// =============================================================================
+// ENUMS - Database-enforced value constraints
+// =============================================================================
+
+enum PhaseCategory {
+  QUESTIONNAIRE // Configurable form fields with validation
+  DOCUMENTATION // Document upload and approval workflow
+  PAYMENT // Installment-based payment collection
+}
+
+enum PhaseType {
+  // QUESTIONNAIRE phases
+  PRE_APPROVAL // Eligibility questionnaire (income, employment, etc.)
+  UNDERWRITING // System evaluation of eligibility
+
+  // DOCUMENTATION phases
+  KYC
+  VERIFICATION
+
+  // PAYMENT phases
+  DOWNPAYMENT
+  MORTGAGE
+  BALLOON
+
+  // Generic
+  CUSTOM
+}
+
+enum PaymentFrequency {
+  MONTHLY
+  BIWEEKLY
+  WEEKLY
+  ONE_TIME
+  CUSTOM
+}
+
+enum ContractStatus {
+  DRAFT
+  PENDING
+  ACTIVE
+  COMPLETED
+  CANCELLED
+  TERMINATED
+  TRANSFERRED // Contract was transferred to a different property
+}
+
+enum TransferRequestStatus {
+  PENDING
+  APPROVED
+  REJECTED
+  IN_PROGRESS
+  COMPLETED
+  FAILED
+}
+
+enum PhaseStatus {
+  PENDING
+  IN_PROGRESS
+  AWAITING_APPROVAL
+  ACTIVE
+  COMPLETED
+  SKIPPED
+  FAILED
+  SUPERSEDED // Phase replaced by payment method change
+}
+
+enum StepType {
+  UPLOAD
+  REVIEW
+  SIGNATURE
+  APPROVAL
+  EXTERNAL_CHECK
+  WAIT
+  GENERATE_DOCUMENT // Triggers document generation (offer letters, contracts, etc.)
+  PRE_APPROVAL // Customer answers eligibility questionnaire
+  UNDERWRITING // System evaluates DTI, score, eligibility
+}
+
+enum StepStatus {
+  PENDING
+  IN_PROGRESS
+  COMPLETED
+  FAILED
+  SKIPPED
+  NEEDS_RESUBMISSION // User must re-upload or correct something (after rejection)
+  ACTION_REQUIRED // User action needed (generic - check actionReason)
+  AWAITING_REVIEW // Submitted, waiting for admin/system review
+}
+
+/// When a step event attachment should trigger
+enum StepTrigger {
+  ON_COMPLETE // When step is approved/completed
+  ON_REJECT // When step is rejected
+  ON_SUBMIT // When step is submitted for review
+  ON_RESUBMIT // When step is resubmitted after rejection
+  ON_START // When step transitions to IN_PROGRESS
+}
+
+/// When a phase event attachment should trigger
+enum PhaseTrigger {
+  ON_ACTIVATE // When phase is activated (becomes current)
+  ON_COMPLETE // When phase is completed (all steps/payments done)
+  ON_CANCEL // When phase is cancelled
+  ON_PAYMENT_RECEIVED // When any payment is received (for PAYMENT phases)
+  ON_ALL_PAYMENTS_RECEIVED // When all payments in phase are complete
+}
+
+enum InstallmentStatus {
+  PENDING
+  PAID
+  OVERDUE
+  PARTIALLY_PAID
+  WAIVED
+}
+
+enum PaymentStatus {
+  INITIATED
+  PENDING
+  COMPLETED
+  FAILED
+  REFUNDED
+}
+
+enum ApprovalDecision {
+  APPROVED
+  REJECTED
+  REQUEST_CHANGES
+}
+
+// =============================================================================
+// CONTRACT TERMINATION / CANCELLATION ENUMS
+// =============================================================================
+
+enum TerminationType {
+  BUYER_WITHDRAWAL // Buyer wants to cancel (voluntary)
+  SELLER_WITHDRAWAL // Seller/developer cancels
+  MUTUAL_AGREEMENT // Both parties agree to terminate
+  PAYMENT_DEFAULT // Buyer failed payment obligations
+  DOCUMENT_FAILURE // Buyer failed to provide required documents
+  FRAUD // Fraudulent activity detected
+  FORCE_MAJEURE // External circumstances (disaster, etc.)
+  PROPERTY_UNAVAILABLE // Property no longer available
+  REGULATORY // Regulatory/legal requirement
+  OTHER // Other reasons (with notes)
+}
+
+enum TerminationStatus {
+  REQUESTED // Initial request submitted
+  PENDING_REVIEW // Awaiting admin review
+  PENDING_REFUND // Approved, awaiting refund processing
+  REFUND_IN_PROGRESS // Refund being processed
+  REFUND_COMPLETED // Refund completed
+  COMPLETED // Termination fully executed (no refund or refund done)
+  REJECTED // Termination request rejected
+  CANCELLED // Termination request was cancelled
+}
+
+enum TerminationInitiator {
+  BUYER
+  SELLER
+  ADMIN
+  SYSTEM
+}
+
+enum CompletionCriterion {
+  DOCUMENT_APPROVALS
+  PAYMENT_AMOUNT
+  STEPS_COMPLETED
+}
+
+enum DocumentStatus {
+  DRAFT
+  PENDING
+  PENDING_SIGNATURE
+  SENT
+  VIEWED
+  SIGNED
+  APPROVED
+  REJECTED
+  EXPIRED
+  CANCELLED
+}
+
+enum OfferLetterType {
+  PROVISIONAL
+  FINAL
+}
+
+enum OfferLetterStatus {
+  DRAFT
+  GENERATED
+  SENT
+  VIEWED
+  SIGNED
+  EXPIRED
+  CANCELLED
+}
+
+enum ContractEventType {
+  CONTRACT_CREATED
+  CONTRACT_STATE_CHANGED
+  PHASE_ACTIVATED
+  PHASE_COMPLETED
+  STEP_COMPLETED
+  STEP_REJECTED
+  DOCUMENT_SUBMITTED
+  DOCUMENT_APPROVED
+  DOCUMENT_REJECTED
+  PAYMENT_INITIATED
+  PAYMENT_COMPLETED
+  PAYMENT_FAILED
+  INSTALLMENTS_GENERATED
+  CONTRACT_SIGNED
+  CONTRACT_TERMINATED
+  CONTRACT_TRANSFERRED
+  UNDERWRITING_COMPLETED
+  OFFER_LETTER_GENERATED
+}
+
+enum ContractEventGroup {
+  STATE_CHANGE
+  PAYMENT
+  DOCUMENT
+  NOTIFICATION
+  WORKFLOW
+}
+
+enum EventActorType {
+  USER
+  SYSTEM
+  WEBHOOK
+  ADMIN
+}
+
+enum RefundStatus {
+  PENDING
+  APPROVED
+  REJECTED
+  PROCESSING
+  COMPLETED
+  FAILED
+  CANCELLED
+}
+
+// =============================================================================
+// EVENT-DRIVEN WORKFLOW ENUMS
+// =============================================================================
+
+/// Handler Type - What kind of action the handler performs
+/// These are business-friendly names that admins can understand
+enum EventHandlerType {
+  SEND_EMAIL // Send an email notification to recipient(s)
+  SEND_SMS // Send an SMS text message
+  SEND_PUSH // Send a push notification
+  CALL_WEBHOOK // Call an external API/webhook
+  ADVANCE_WORKFLOW // Advance or complete a workflow step
+  RUN_AUTOMATION // Execute internal business logic
+}
+
+/// Actor Type - Who triggered an event
+enum ActorType {
+  USER
+  API_KEY
+  SYSTEM
+  WEBHOOK
+}
+
+/// Workflow Event Status
+enum WorkflowEventStatus {
+  PENDING
+  PROCESSING
+  COMPLETED
+  FAILED
+  SKIPPED
+}
+
+/// Handler Execution Status
+enum ExecutionStatus {
+  PENDING
+  RUNNING
+  COMPLETED
+  FAILED
+  RETRYING
+  SKIPPED
+}
+
+/// Permission effect (Allow/Deny)
+enum PermissionEffect {
+  ALLOW
+  DENY
+}
+
+// =============================================================================
+// USER & AUTH DOMAIN
+// =============================================================================
+
+model User {
+  id                     String             @id @default(cuid())
+  email                  String             @unique
+  password               String?
+  phone                  String?            @unique
+  firstName              String?
+  lastName               String?
+  isActive               Boolean            @default(true)
+  isEmailVerified        Boolean            @default(false)
+  googleId               String?
+  avatar                 String?
+  // Legacy: Optional direct tenant association (for backward compatibility)
+  // New: Use tenantMemberships for multi-tenant federation
+  tenantId               String?
+  tenant                 Tenant?            @relation(fields: [tenantId], references: [id], onDelete: SetNull)
+  // Federated: User can belong to multiple tenants with different roles
+  tenantMemberships      TenantMembership[]
+  // Legacy: Support multiple roles via explicit join table `UserRole`
+  userRoles              UserRole[]
+  walletId               String?            @unique
+  wallet                 Wallet?            @relation(fields: [walletId], references: [id])
+  createdAt              DateTime           @default(now())
+  updatedAt              DateTime           @updatedAt
+  emailVerifiedAt        DateTime?
+  emailVerificationToken String?
+  lastLoginAt            DateTime?
+  refreshTokens          RefreshToken[]
+  passwordResets         PasswordReset[]
+  suspensions            UserSuspension[]
+  emailPreferences       EmailPreference[]
+  deviceEndpoints        DeviceEndpoint[]
+  socials                Social[]
+
+  // Relations to other domains
+  properties       Property[]
+  contracts        Contract[]        @relation("ContractBuyer")
+  soldContracts    Contract[]        @relation("ContractSeller")
+  contractPayments ContractPayment[] @relation("ContractPayer")
+
+  // Documentation step assignments and approvals
+  assignedSteps DocumentationStep[]         @relation("DocumentationStepAssignee")
+  stepApprovals DocumentationStepApproval[] @relation("DocumentationStepApprover")
+  uploadedDocs  ContractDocument[]          @relation("DocumentUploader")
+
+  // Payment method changes
+  paymentMethodChangeRequests PaymentMethodChangeRequest[] @relation("ChangeRequestor")
+  reviewedChangeRequests      PaymentMethodChangeRequest[] @relation("ChangeReviewer")
+
+  // Contract terminations
+  initiatedTerminations ContractTermination[] @relation("TerminationInitiator")
+  reviewedTerminations  ContractTermination[] @relation("TerminationReviewer")
+
+  // Offer letters
+  offerLettersGenerated OfferLetter[] @relation("OfferLetterGenerator")
+  offerLettersSent      OfferLetter[] @relation("OfferLetterSender")
+
+  // Property transfer requests
+  transferRequestsSubmitted PropertyTransferRequest[] @relation("TransferRequestor")
+  transferRequestsReviewed  PropertyTransferRequest[] @relation("TransferReviewer")
+
+  // Unified approval requests
+  approvalRequestsSubmitted ApprovalRequest[] @relation("ApprovalRequestor")
+  approvalRequestsAssigned  ApprovalRequest[] @relation("ApprovalAssignee")
+  approvalRequestsReviewed  ApprovalRequest[] @relation("ApprovalReviewer")
+
+  // Contract refunds
+  requestedRefunds ContractRefund[] @relation("RefundRequester")
+  approvedRefunds  ContractRefund[] @relation("RefundApprover")
+  processedRefunds ContractRefund[] @relation("RefundProcessor")
+
+  @@index([email])
+  @@index([tenantId])
+  @@map("users")
+}
+
+model Role {
+  id          String             @id @default(cuid())
+  name        String
+  description String?
+  // Tenant-scoping: NULL = global template, set = tenant-specific role
+  tenantId    String?
+  tenant      Tenant?            @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  // System roles cannot be deleted (admin, user, etc.)
+  isSystem    Boolean            @default(false)
+  isActive    Boolean            @default(true)
+  // Legacy: UserRole for backward compatibility
+  userRoles   UserRole[]
+  // New: TenantMembership for federated users
+  memberships TenantMembership[]
+  permissions RolePermission[]
+  createdAt   DateTime           @default(now())
+  updatedAt   DateTime           @updatedAt
+
+  @@unique([name, tenantId]) // Unique name per tenant (null tenantId = global)
+  @@index([tenantId])
+  @@map("roles")
+}
+
+/// Permission defines a path pattern + HTTP methods + effect
+/// Supports path-based authorization matching the authorizer's policy structure
+model Permission {
+  id          String           @id @default(cuid())
+  name        String // Descriptive name: "Read Users", "Manage Properties"
+  description String?
+  // Path pattern: /users, /users/:id, /properties/*, etc.
+  path        String
+  // HTTP methods: ["GET"], ["GET", "POST"], ["*"] - stored as JSON
+  methods     Json             @default("[]")
+  // Allow or Deny this path/methods
+  effect      PermissionEffect @default(ALLOW)
+  // Tenant-scoping: NULL = global template, set = tenant-specific
+  tenantId    String?
+  tenant      Tenant?          @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  // System permissions cannot be deleted
+  isSystem    Boolean          @default(false)
+  roles       RolePermission[]
+  createdAt   DateTime         @default(now())
+  updatedAt   DateTime         @updatedAt
+
+  @@unique([path, tenantId]) // Unique path per tenant
+  @@index([tenantId])
+  @@map("permissions")
+}
+
+model RolePermission {
+  roleId       String
+  permissionId String
+  role         Role       @relation(fields: [roleId], references: [id], onDelete: Cascade)
+  permission   Permission @relation(fields: [permissionId], references: [id], onDelete: Cascade)
+  createdAt    DateTime   @default(now())
+
+  @@id([roleId, permissionId])
+  @@map("role_permissions")
+}
+
+/// Legacy: Direct user-role assignment (global, not tenant-scoped)
+/// @deprecated Use TenantMembership for tenant-scoped role assignments
+model UserRole {
+  userId    String
+  roleId    String
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  role      Role     @relation(fields: [roleId], references: [id], onDelete: Cascade)
+  createdAt DateTime @default(now())
+
+  @@id([userId, roleId])
+  @@map("user_roles")
+}
+
+/// Tenant Membership: Links users to tenants with specific roles
+/// Enables federated users across multiple tenants with different roles per tenant
+model TenantMembership {
+  id        String   @id @default(cuid())
+  userId    String
+  tenantId  String
+  roleId    String
+  // Whether this membership is active
+  isActive  Boolean  @default(true)
+  // Whether this is the user's default tenant (for login without specifying tenant)
+  isDefault Boolean  @default(false)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  user   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+  tenant Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  role   Role   @relation(fields: [roleId], references: [id], onDelete: Restrict)
+
+  @@unique([userId, tenantId]) // User can only have one membership per tenant
+  @@index([tenantId])
+  @@index([userId])
+  @@map("tenant_memberships")
+}
+
+model Tenant {
+  id        String   @id @default(cuid())
+  name      String
+  subdomain String   @unique
+  isActive  Boolean  @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Back-relations for multitenancy
+  users          User[]
+  properties     Property[]
+  paymentPlans   PaymentPlan[]
+  paymentMethods PropertyPaymentMethod[]
+  contracts      Contract[]
+
+  // RBAC: Tenant-scoped roles and permissions
+  roles       Role[]
+  permissions Permission[]
+  // Federated user memberships
+  memberships TenantMembership[]
+
+  // Payment method changes
+  paymentMethodChangeRequests PaymentMethodChangeRequest[]
+  documentRequirementRules    DocumentRequirementRule[]
+
+  // Contract terminations
+  contractTerminations ContractTermination[]
+
+  // Offer letters and templates
+  documentTemplates DocumentTemplate[]
+  offerLetters      OfferLetter[]
+
+  // API keys for third-party integrations
+  apiKeys ApiKey[]
+
+  // Event-driven workflow
+  eventChannels  EventChannel[]
+  eventTypes     EventType[]
+  eventHandlers  EventHandler[]
+  workflowEvents WorkflowEvent[]
+
+  // Property transfer requests
+  propertyTransferRequests PropertyTransferRequest[]
+
+  // Unified approval requests
+  approvalRequests ApprovalRequest[]
+
+  // Contract refunds
+  contractRefunds ContractRefund[]
+
+  @@index([subdomain])
+  @@map("tenants")
+}
+
+// =============================================================================
+// API KEYS - Third-party integration credentials
+// =============================================================================
+// ApiKey enables partners/integrations to authenticate via token exchange.
+// 
+// Flow:
+// 1. Admin creates API key for a partner (POST /api-keys)
+// 2. System generates secret, stores in Secrets Manager, returns id.secret ONCE
+// 3. Partner calls token endpoint with id.secret (POST /api-keys/:id/token)
+// 4. Token endpoint validates via Secrets Manager, returns short-lived JWT
+// 5. Partner uses JWT for API requests; authorizer validates + resolves scopes
+//
+// Security:
+// - Raw secret stored ONLY in AWS Secrets Manager (secretRef = ARN)
+// - Secret returned only once at creation; admin must rotate if lost
+// - Scopes define allowed operations (e.g., ["contract:read", "payment:read"])
+// - Short-lived JWTs (5-15 min) minimize exposure on key compromise
+// =============================================================================
+
+model ApiKey {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Identification
+  name        String // Human-readable name (e.g., "Paystack Integration")
+  description String? @db.Text // Optional description
+  provider    String // Partner/vendor name (e.g., "paystack", "flutterwave")
+
+  // Secret management (NEVER store raw secret in DB)
+  secretRef String // AWS Secrets Manager ARN or name
+
+  // Permissions - scopes this API key is allowed to request
+  // Examples: ["contract:read", "payment:*", "property:read"]
+  scopes Json // JSON array of scope strings
+
+  // Lifecycle
+  enabled    Boolean   @default(true)
+  expiresAt  DateTime? // Optional expiration date
+  lastUsedAt DateTime? // Updated on each token exchange
+  revokedAt  DateTime? // Set when key is revoked
+  revokedBy  String? // User ID who revoked
+
+  // Audit
+  createdBy String? // User ID who created
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([tenantId])
+  @@index([provider])
+  @@index([enabled])
+  @@map("api_keys")
+}
+
+model RefreshToken {
+  id        String   @id @default(cuid())
+  // Use the JWT `jti` for indexed lookups and keep the raw JWT (optional)
+  jti       String?  @unique @db.VarChar(255)
+  token     String?  @db.LongText
+  userId    String
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  expiresAt DateTime
+  createdAt DateTime @default(now())
+
+  @@index([userId])
+  @@index([expiresAt])
+  @@map("refresh_tokens")
+}
+
+model PasswordReset {
+  id        String    @id @default(cuid())
+  token     String    @unique
+  userId    String
+  user      User      @relation(fields: [userId], references: [id], onDelete: Cascade)
+  expiresAt DateTime
+  usedAt    DateTime?
+  createdAt DateTime  @default(now())
+
+  @@index([userId])
+  @@index([expiresAt])
+  @@map("password_resets")
+}
+
+model UserSuspension {
+  id          String    @id @default(cuid())
+  userId      String
+  user        User      @relation(fields: [userId], references: [id], onDelete: Cascade)
+  reason      String
+  suspendedAt DateTime  @default(now())
+  expiresAt   DateTime?
+  liftedAt    DateTime?
+
+  @@index([userId])
+  @@map("user_suspensions")
+}
+
+model EmailPreference {
+  id                  String   @id @default(cuid())
+  userId              String
+  user                User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  marketingEmails     Boolean  @default(true)
+  transactionalEmails Boolean  @default(true)
+  propertyAlerts      Boolean  @default(true)
+  paymentReminders    Boolean  @default(true)
+  createdAt           DateTime @default(now())
+  updatedAt           DateTime @updatedAt
+
+  @@index([userId])
+  @@map("email_preferences")
+}
+
+model DeviceEndpoint {
+  id        String   @id @default(cuid())
+  userId    String
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  endpoint  String // Push notification endpoint
+  platform  String // ios, android, web
+  isActive  Boolean  @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([userId])
+  @@map("device_endpoints")
+}
+
+model Social {
+  id        String   @id @default(cuid())
+  userId    String
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  provider  String // google, facebook, twitter, etc
+  socialId  String // ID from the social provider
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([provider, socialId])
+  @@index([userId])
+  @@map("socials")
+}
+
+model OAuthState {
+  id        String   @id @default(cuid())
+  state     String   @unique
+  expiresAt DateTime
+  createdAt DateTime @default(now())
+
+  @@index([state])
+  @@index([expiresAt])
+  @@map("oauth_states")
+}
+
+model Wallet {
+  id           String        @id @default(cuid())
+  balance      Float         @default(0)
+  currency     String        @default("USD")
+  user         User?
+  transactions Transaction[]
+  createdAt    DateTime      @default(now())
+  updatedAt    DateTime      @updatedAt
+
+  @@map("wallets")
+}
+
+model Transaction {
+  id          String   @id @default(cuid())
+  walletId    String
+  wallet      Wallet   @relation(fields: [walletId], references: [id], onDelete: Cascade)
+  amount      Float
+  type        String // CREDIT, DEBIT
+  status      String // PENDING, COMPLETED, FAILED
+  reference   String?
+  description String?
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  @@index([walletId])
+  @@map("transactions")
+}
+
+model Settings {
+  id        String   @id @default(cuid())
+  key       String   @unique
+  value     String   @db.Text
+  category  String?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([category])
+  @@map("settings")
+}
+
+// =============================================================================
+// PROPERTY DOMAIN
+// =============================================================================
+// Property = listing/project (e.g., "Sunrise Estate")
+// PropertyVariant = configuration with specs & price (e.g., "3-Bed Corner - Finished")
+// PropertyUnit = individual sellable unit (e.g., "Unit A1")
+// =============================================================================
+
+model Property {
+  id             String         @id @default(cuid())
+  tenantId       String
+  tenant         Tenant         @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  userId         String
+  user           User           @relation(fields: [userId], references: [id], onDelete: Cascade)
+  title          String
+  category       String // SALE, RENT, LEASE
+  propertyType   String // APARTMENT, HOUSE, LAND, COMMERCIAL, ESTATE, TOWNHOUSE
+  country        String
+  currency       String // USD, NGN, etc
+  city           String
+  district       String?
+  zipCode        String?
+  streetAddress  String?
+  longitude      Float?
+  latitude       Float?
+  status         String         @default("DRAFT") // DRAFT, PUBLISHED, SOLD_OUT, ARCHIVED
+  description    String?        @db.Text
+  displayImageId String?
+  displayImage   PropertyMedia? @relation("DisplayImage", fields: [displayImageId], references: [id], onDelete: SetNull)
+  isPublished    Boolean        @default(false)
+  publishedAt    DateTime?
+  createdAt      DateTime       @default(now())
+  updatedAt      DateTime       @updatedAt
+
+  // Relations
+  documents      PropertyDocument[]
+  media          PropertyMedia[]             @relation("PropertyMedia")
+  amenities      PropertyAmenity[] // Shared amenities (gym, pool, security)
+  paymentMethods PropertyPaymentMethodLink[]
+  variants       PropertyVariant[]
+
+  @@index([tenantId])
+  @@index([userId])
+  @@index([category])
+  @@index([propertyType])
+  @@index([city])
+  @@index([status])
+  @@map("properties")
+}
+
+model PropertyMedia {
+  id         String   @id @default(cuid())
+  propertyId String
+  property   Property @relation("PropertyMedia", fields: [propertyId], references: [id], onDelete: Cascade)
+  url        String
+  type       String // IMAGE, VIDEO
+  caption    String?
+  order      Int      @default(0)
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+
+  displayForProperties Property[] @relation("DisplayImage")
+
+  @@index([propertyId])
+  @@map("property_media")
+}
+
+model PropertyDocument {
+  id         String   @id @default(cuid())
+  propertyId String
+  property   Property @relation(fields: [propertyId], references: [id], onDelete: Cascade)
+  name       String
+  url        String
+  type       String // TITLE_DEED, SURVEY_PLAN, etc
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+
+  @@index([propertyId])
+  @@map("property_documents")
+}
+
+model Amenity {
+  id         String                   @id @default(cuid())
+  name       String                   @unique
+  category   String? // PROPERTY, VARIANT, BOTH - helps filter which amenities to show
+  icon       String? // Icon name/URL for UI
+  createdAt  DateTime                 @default(now())
+  updatedAt  DateTime                 @updatedAt
+  properties PropertyAmenity[]
+  variants   PropertyVariantAmenity[]
+
+  @@index([category])
+  @@map("amenities")
+}
+
+// =============================================================================
+// PROPERTY VARIANT & UNIT MODELS
+// =============================================================================
+
+// PropertyVariant = specific configuration with its own price and amenities
+// e.g., "3-Bedroom Corner Piece - Fully Finished", "2-Bedroom Standard - Carcass"
+model PropertyVariant {
+  id         String   @id @default(cuid())
+  propertyId String
+  property   Property @relation(fields: [propertyId], references: [id], onDelete: Cascade)
+
+  name        String // "Corner Piece - Finished", "Standard - Carcass"
+  description String? @db.Text
+
+  // Specifications
+  nBedrooms     Int?
+  nBathrooms    Int?
+  nParkingSpots Int?
+  area          Float? // Square meters/feet
+
+  // Pricing
+  price       Float
+  pricePerSqm Float? // Computed or set manually
+
+  // Inventory counters (denormalized for performance, updated via triggers/service)
+  totalUnits     Int @default(1)
+  availableUnits Int @default(1)
+  reservedUnits  Int @default(0)
+  soldUnits      Int @default(0)
+
+  // Status
+  status    String   @default("AVAILABLE") // AVAILABLE, LOW_STOCK, SOLD_OUT, ARCHIVED
+  isActive  Boolean  @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Relations
+  amenities PropertyVariantAmenity[]
+  units     PropertyUnit[]
+  media     PropertyVariantMedia[]
+
+  @@index([propertyId])
+  @@index([status])
+  @@index([price])
+  @@map("property_variants")
+}
+
+// PropertyVariantAmenity = amenities specific to a variant
+// e.g., "Finished Kitchen", "Smart Home System", "Private Garden"
+model PropertyVariantAmenity {
+  variantId String
+  amenityId String
+  variant   PropertyVariant @relation(fields: [variantId], references: [id], onDelete: Cascade)
+  amenity   Amenity         @relation(fields: [amenityId], references: [id], onDelete: Cascade)
+  createdAt DateTime        @default(now())
+
+  @@id([variantId, amenityId])
+  @@map("property_variant_amenities")
+}
+
+// PropertyVariantMedia = images/videos specific to a variant
+model PropertyVariantMedia {
+  id        String          @id @default(cuid())
+  variantId String
+  variant   PropertyVariant @relation(fields: [variantId], references: [id], onDelete: Cascade)
+  url       String
+  type      String // IMAGE, VIDEO, FLOOR_PLAN, 3D_TOUR
+  caption   String?
+  order     Int             @default(0)
+  createdAt DateTime        @default(now())
+  updatedAt DateTime        @updatedAt
+
+  @@index([variantId])
+  @@map("property_variant_media")
+}
+
+// PropertyUnit = individual sellable/rentable unit within a variant
+// e.g., "Unit A1", "Block B - Flat 3", "Plot 15"
+model PropertyUnit {
+  id        String          @id @default(cuid())
+  variantId String
+  variant   PropertyVariant @relation(fields: [variantId], references: [id], onDelete: Cascade)
+
+  unitNumber  String // "A1", "B-3", "Plot 15"
+  floorNumber Int? // For apartments
+  blockName   String? // "Block A", "Tower 1"
+
+  // Unit-specific overrides (if different from variant)
+  priceOverride Float? // If this specific unit has a different price
+  areaOverride  Float? // If this specific unit has a different area
+  notes         String? @db.Text // Internal notes about this unit
+
+  // Status tracking
+  status String @default("AVAILABLE") // AVAILABLE, RESERVED, SOLD, RENTED, UNAVAILABLE
+
+  // Reservation/hold
+  reservedAt    DateTime?
+  reservedUntil DateTime?
+  reservedById  String?
+
+  // Ownership tracking (once sold)
+  ownerId String?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Relations
+  contracts Contract[]
+
+  // Transfer requests targeting this unit
+  transferRequests PropertyTransferRequest[]
+
+  @@unique([variantId, unitNumber])
+  @@index([variantId])
+  @@index([status])
+  @@map("property_units")
+}
+
+model PropertyAmenity {
+  propertyId String
+  amenityId  String
+  property   Property @relation(fields: [propertyId], references: [id], onDelete: Cascade)
+  amenity    Amenity  @relation(fields: [amenityId], references: [id], onDelete: Cascade)
+  createdAt  DateTime @default(now())
+
+  @@id([propertyId, amenityId])
+  @@map("property_amenities")
+}
+
+// =============================================================================
+// PAYMENT PLAN DOMAIN - Reusable installment structure templates
+// =============================================================================
+
+// PaymentPlan = reusable structure for how payments are scheduled
+// Examples: "Monthly360" (360 monthly payments), "Weekly52", "OneTime"
+model PaymentPlan {
+  id          String  @id @default(cuid())
+  tenantId    String? // NULL = global template available to all tenants
+  tenant      Tenant? @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  name        String
+  description String? @db.Text
+  isActive    Boolean @default(true)
+
+  // Structure configuration
+  paymentFrequency       PaymentFrequency
+  customFrequencyDays    Int?
+  numberOfInstallments   Int? // Fixed number (1 for one-time, 360 for 30yr monthly) - NULL if flexible
+  calculateInterestDaily Boolean          @default(false)
+  gracePeriodDays        Int              @default(0)
+
+  // Flexible term configuration (for user-selectable duration like mortgages)
+  // If these are set, numberOfInstallments is ignored and user selects within range
+  allowFlexibleTerm Boolean @default(false) // true = user can select term within range
+  minTermMonths     Int? // e.g., 60 (5 years minimum)
+  maxTermMonths     Int? // e.g., 360 (30 years maximum)
+  termStepMonths    Int? // e.g., 12 (increments of 1 year) - NULL = any month allowed
+
+  // Age-based constraints (for mortgage eligibility)
+  maxAgeAtMaturity Int? // e.g., 65 - user's age + term cannot exceed this
+
+  // Fund collection behavior
+  // true = we collect funds via wallet/gateway (e.g., downpayment)
+  // false = external payment, we only track/reconcile (e.g., bank mortgage)
+  collectFunds Boolean @default(true)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Used by property payment method phases (templates)
+  methodPhases  PropertyPaymentMethodPhase[]
+  // Used by instantiated payment phases
+  paymentPhases PaymentPhase[]
+
+  @@unique([tenantId, name]) // Unique per tenant, or globally if tenantId is null
+  @@index([tenantId])
+  @@map("payment_plans")
+}
+
+// =============================================================================
+// PROPERTY PAYMENT METHOD DOMAIN - Product offerings per property
+// =============================================================================
+
+// PropertyPaymentMethod = how a property can be purchased (e.g., "Standard Mortgage", "Cash", "Rent-to-Own")
+model PropertyPaymentMethod {
+  id          String  @id @default(cuid())
+  tenantId    String
+  tenant      Tenant  @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  name        String // "Standard Mortgage", "Flexible Payment", "Cash Purchase"
+  description String? @db.Text
+  isActive    Boolean @default(true)
+
+  // Global method configuration
+  allowEarlyPayoff       Boolean @default(true)
+  earlyPayoffPenaltyRate Float?
+  autoActivatePhases     Boolean @default(true)
+  requiresManualApproval Boolean @default(false)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Many-to-many with properties
+  properties PropertyPaymentMethodLink[]
+  // Phases that make up this method (templates)
+  phases     PropertyPaymentMethodPhase[]
+  // Contracts using this method
+  contracts  Contract[]
+
+  // Payment method change tracking
+  changeRequestsFrom PaymentMethodChangeRequest[] @relation("ChangeFromMethod")
+  changeRequestsTo   PaymentMethodChangeRequest[] @relation("ChangeToMethod")
+
+  // Document requirement rules
+  documentRules   DocumentRequirementRule[] @relation("RulePaymentMethod")
+  changeRulesFrom DocumentRequirementRule[] @relation("RuleFromMethod")
+  changeRulesTo   DocumentRequirementRule[] @relation("RuleToMethod")
+
+  @@unique([tenantId, name]) // Unique per tenant
+  @@index([tenantId])
+  @@map("property_payment_methods")
+}
+
+// Many-to-many link between Property and PaymentMethod
+model PropertyPaymentMethodLink {
+  propertyId      String
+  property        Property              @relation(fields: [propertyId], references: [id], onDelete: Cascade)
+  paymentMethodId String
+  paymentMethod   PropertyPaymentMethod @relation(fields: [paymentMethodId], references: [id], onDelete: Cascade)
+
+  // Method-specific overrides for this property
+  isDefault Boolean  @default(false)
+  isActive  Boolean  @default(true)
+  createdAt DateTime @default(now())
+
+  @@id([propertyId, paymentMethodId])
+  @@map("property_payment_method_links")
+}
+
+// Phase template within a PropertyPaymentMethod (e.g., documentation, downpayment, mortgage)
+// phaseCategory determines the FSM type: DOCUMENTATION or PAYMENT
+model PropertyPaymentMethodPhase {
+  id              String                @id @default(cuid())
+  paymentMethodId String
+  paymentMethod   PropertyPaymentMethod @relation(fields: [paymentMethodId], references: [id], onDelete: Cascade)
+  paymentPlanId   String? // Only for PAYMENT phases
+  paymentPlan     PaymentPlan?          @relation(fields: [paymentPlanId], references: [id])
+
+  name        String
+  description String? @db.Text
+
+  // Phase classification (DB-enforced enums)
+  phaseCategory PhaseCategory
+  phaseType     PhaseType
+  order         Int
+
+  // Financial configuration (for PAYMENT phases)
+  interestRate   Float?
+  percentOfPrice Float? // e.g., 10.0 for 10% downpayment
+
+  // Fund collection behavior (inherited from PaymentPlan if not set)
+  // true = we collect funds via wallet/gateway (e.g., downpayment)
+  // false = external payment, we only track/reconcile (e.g., bank mortgage)
+  collectFunds Boolean? // null = inherit from PaymentPlan
+
+  // Activation rules
+  requiresPreviousPhaseCompletion Boolean              @default(true)
+  minimumCompletionPercentage     Float?
+  completionCriterion             CompletionCriterion?
+
+  // Snapshots for audit (original config at creation time)
+  stepDefinitionsSnapshot  Json?
+  requiredDocumentSnapshot Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Normalized child tables (for DOCUMENTATION phases)
+  steps               PaymentMethodPhaseStep[]
+  requiredDocuments   PaymentMethodPhaseDocument[]
+  // Normalized child tables (for QUESTIONNAIRE phases)
+  questionnaireFields PaymentMethodPhaseField[]
+  // Event attachments - handlers that fire on phase transitions
+  eventAttachments    PhaseEventAttachment[]
+
+  @@index([paymentMethodId])
+  @@index([paymentPlanId])
+  @@index([phaseCategory])
+  @@map("property_payment_method_phases")
+}
+
+/// Phase Event Attachment - Links event handlers to phase template triggers
+/// When a phase transitions (complete, payment received, etc.), attached handlers fire
+model PhaseEventAttachment {
+  id      String                     @id @default(cuid())
+  phaseId String
+  phase   PropertyPaymentMethodPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+
+  /// When this handler should fire
+  trigger PhaseTrigger
+
+  /// The event handler to execute
+  handlerId String
+  handler   EventHandler @relation(fields: [handlerId], references: [id], onDelete: Cascade)
+
+  /// Order of execution (lower = first)
+  priority Int @default(100)
+
+  /// Whether this attachment is active
+  enabled Boolean @default(true)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([phaseId, handlerId, trigger])
+  @@index([phaseId])
+  @@index([handlerId])
+  @@map("phase_event_attachments")
+}
+
+// Step template within a DOCUMENTATION phase
+model PaymentMethodPhaseStep {
+  id      String                     @id @default(cuid())
+  phaseId String
+  phase   PropertyPaymentMethodPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+
+  name     String
+  stepType StepType
+  order    Int
+
+  metadata  Json?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Event attachments - handlers that fire on step transitions
+  eventAttachments StepEventAttachment[]
+
+  @@index([phaseId])
+  @@map("payment_method_phase_steps")
+}
+
+/// Step Event Attachment - Links event handlers to step template triggers
+/// When a step transitions (complete, reject, etc.), attached handlers fire
+model StepEventAttachment {
+  id     String                 @id @default(cuid())
+  stepId String
+  step   PaymentMethodPhaseStep @relation(fields: [stepId], references: [id], onDelete: Cascade)
+
+  /// When this handler should fire
+  trigger StepTrigger
+
+  /// The event handler to execute
+  handlerId String
+  handler   EventHandler @relation(fields: [handlerId], references: [id], onDelete: Cascade)
+
+  /// Order of execution (lower = first)
+  priority Int @default(100)
+
+  /// Whether this attachment is active
+  enabled Boolean @default(true)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([stepId, handlerId, trigger])
+  @@index([stepId])
+  @@index([handlerId])
+  @@map("step_event_attachments")
+}
+
+// Required document within a DOCUMENTATION phase
+model PaymentMethodPhaseDocument {
+  id      String                     @id @default(cuid())
+  phaseId String
+  phase   PropertyPaymentMethodPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+
+  documentType     String
+  isRequired       Boolean @default(true)
+  description      String? @db.Text
+  allowedMimeTypes String? // CSV: application/pdf,image/jpeg
+  maxSizeBytes     Int?
+
+  metadata  Json?
+  createdAt DateTime @default(now())
+
+  @@index([phaseId, documentType])
+  @@map("payment_method_phase_documents")
+}
+
+// =============================================================================
+// QUESTIONNAIRE FIELD TYPES - For QUESTIONNAIRE phases
+// =============================================================================
+
+enum FieldType {
+  TEXT // Short text input
+  TEXTAREA // Long text input
+  NUMBER // Numeric input (with optional min/max)
+  CURRENCY // Currency input (validated as money)
+  EMAIL // Email validation
+  PHONE // Phone number validation
+  DATE // Date picker
+  SELECT // Dropdown/single select
+  MULTI_SELECT // Multiple selection
+  CHECKBOX // Boolean yes/no
+  RADIO // Radio button group
+  FILE // File upload (single)
+}
+
+// Questionnaire field template within a QUESTIONNAIRE phase
+model PaymentMethodPhaseField {
+  id      String                     @id @default(cuid())
+  phaseId String
+  phase   PropertyPaymentMethodPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+
+  // Field identification
+  name        String // Internal field name (e.g., "monthly_income")
+  label       String // Display label (e.g., "Monthly Income")
+  description String? @db.Text // Help text for the field
+  placeholder String? // Placeholder text
+
+  // Field configuration
+  fieldType  FieldType
+  isRequired Boolean   @default(true)
+  order      Int
+
+  // Validation rules (JSON schema-like)
+  // Examples:
+  // NUMBER: { "min": 0, "max": 1000000 }
+  // TEXT: { "minLength": 2, "maxLength": 100, "pattern": "^[A-Za-z]+$" }
+  // SELECT: { "options": [{"value": "employed", "label": "Employed"}, ...] }
+  // DATE: { "minDate": "now", "maxDate": "+30d" }
+  validation Json?
+
+  // For conditional display (e.g., show if another field has a certain value)
+  // { "field": "employment_status", "operator": "equals", "value": "employed" }
+  displayCondition Json?
+
+  // Default value (JSON to support any type)
+  defaultValue Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([phaseId, name])
+  @@index([phaseId])
+  @@map("payment_method_phase_fields")
+}
+
+// =============================================================================
+// CONTRACT DOMAIN - Unified agreement model (replaces Mortgage, PurchasePlan, etc.)
+// =============================================================================
+// Contract is the canonical agreement. "Mortgage" is just a product configuration
+// that creates a Contract with specific phases (documentation, downpayment, long-term payment).
+// Phases can be QUESTIONNAIRE, DOCUMENTATION, or PAYMENT.
+// =============================================================================
+
+model Contract {
+  id              String                 @id @default(cuid())
+  tenantId        String
+  tenant          Tenant                 @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  // Link to specific unit being purchased/rented
+  propertyUnitId  String
+  propertyUnit    PropertyUnit           @relation(fields: [propertyUnitId], references: [id], onDelete: Cascade)
+  buyerId         String
+  buyer           User                   @relation("ContractBuyer", fields: [buyerId], references: [id], onDelete: Cascade)
+  sellerId        String?
+  seller          User?                  @relation("ContractSeller", fields: [sellerId], references: [id])
+  paymentMethodId String? // PropertyPaymentMethod used to create this contract
+  paymentMethod   PropertyPaymentMethod? @relation(fields: [paymentMethodId], references: [id])
+
+  // Contract identification
+  contractNumber String  @unique
+  title          String
+  description    String? @db.Text
+  contractType   String // Admin-defined: MORTGAGE, INSTALLMENT, RENT_TO_OWN, CASH, LEASE, etc.
+
+  // Contract value (negotiated from unit price)
+  totalAmount Float
+
+  // FSM state (DB-enforced enum)
+  status         ContractStatus @default(DRAFT)
+  currentPhaseId String?
+  currentPhase   ContractPhase? @relation("CurrentPhase", fields: [currentPhaseId], references: [id])
+
+  // Timing
+  nextPaymentDueDate DateTime?
+  lastReminderSentAt DateTime?
+  startDate          DateTime?
+  endDate            DateTime?
+  signedAt           DateTime?
+  terminatedAt       DateTime?
+  createdAt          DateTime  @default(now())
+  updatedAt          DateTime  @updatedAt
+
+  // Relations
+  phases       ContractPhase[]
+  documents    ContractDocument[]
+  payments     ContractPayment[]
+  terminations ContractTermination[]
+  offerLetters OfferLetter[]
+
+  // Payment method change requests for this contract
+  paymentMethodChangeRequests PaymentMethodChangeRequest[]
+
+  // Transfer tracking - when a contract is transferred to a different property
+  transferredFromId String?   @unique // Source contract if this was created via transfer
+  transferredFrom   Contract? @relation("ContractTransfer", fields: [transferredFromId], references: [id])
+  transferredTo     Contract? @relation("ContractTransfer")
+
+  // Transfer requests where this contract is the source
+  outgoingTransferRequests PropertyTransferRequest[] @relation("SourceContract")
+  // Transfer requests where this contract is the target (created after approval)
+  incomingTransferRequests PropertyTransferRequest[] @relation("TargetContract")
+
+  // Audit trail
+  events ContractEvent[]
+
+  // Refund requests
+  refunds ContractRefund[]
+
+  @@index([tenantId])
+  @@index([propertyUnitId])
+  @@index([buyerId])
+  @@index([sellerId])
+  @@index([paymentMethodId])
+  @@index([status])
+  @@index([currentPhaseId])
+  @@map("contracts")
+}
+
+// =============================================================================
+// CONTRACT REFUNDS - Track refund requests for overpayments or cancellations
+// =============================================================================
+model ContractRefund {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  contractId String
+  contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+
+  amount Float
+  reason String       @db.Text
+  status RefundStatus @default(PENDING)
+
+  // Who requested the refund
+  requestedById String
+  requestedBy   User   @relation("RefundRequester", fields: [requestedById], references: [id])
+
+  // Who approved/rejected the refund
+  approvedById String?
+  approvedBy   User?   @relation("RefundApprover", fields: [approvedById], references: [id])
+
+  // Who processed the refund (finance team)
+  processedById String?
+  processedBy   User?   @relation("RefundProcessor", fields: [processedById], references: [id])
+
+  // Refund payment details
+  paymentMethod    String? // BANK_TRANSFER, CHEQUE, MOBILE_MONEY, etc.
+  referenceNumber  String? // Bank/payment reference
+  recipientName    String?
+  recipientAccount String?
+  recipientBank    String?
+
+  // Timestamps
+  requestedAt DateTime  @default(now())
+  approvedAt  DateTime?
+  rejectedAt  DateTime?
+  processedAt DateTime?
+
+  // Additional notes
+  approvalNotes   String? @db.Text
+  rejectionNotes  String? @db.Text
+  processingNotes String? @db.Text
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([contractId])
+  @@index([status])
+  @@index([tenantId])
+  @@index([requestedById])
+  @@map("contract_refunds")
+}
+
+// Phase within a contract - can be DOCUMENTATION or PAYMENT type
+// Admin names phases freely (e.g., "KYC Documents", "Downpayment", "Monthly Mortgage")
+// =============================================================================
+// CONTRACT PHASE - Base model with polymorphic extensions
+// =============================================================================
+// ContractPhase is the base table with shared fields only.
+// Each phase has exactly ONE extension table based on phaseCategory:
+// - QUESTIONNAIRE → QuestionnairePhase
+// - DOCUMENTATION → DocumentationPhase
+// - PAYMENT → PaymentPhase
+// This eliminates nullable field pollution and makes the schema self-documenting.
+// =============================================================================
+
+model ContractPhase {
+  id         String   @id @default(cuid())
+  contractId String
+  contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+
+  // Admin-defined naming
+  name        String
+  description String? @db.Text
+
+  // Phase classification (DB-enforced enums)
+  phaseCategory PhaseCategory
+  phaseType     PhaseType
+  order         Int
+
+  // FSM state for this phase (DB-enforced enum)
+  status PhaseStatus @default(PENDING)
+
+  // Timing (shared across all phase types)
+  dueDate     DateTime?
+  startDate   DateTime?
+  endDate     DateTime?
+  activatedAt DateTime?
+  completedAt DateTime?
+
+  // Activation rules (shared)
+  requiresPreviousPhaseCompletion Boolean @default(true)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Polymorphic extensions (exactly one will be populated based on phaseCategory)
+  questionnairePhase QuestionnairePhase?
+  documentationPhase DocumentationPhase?
+  paymentPhase       PaymentPhase?
+
+  // Payments can be linked to any phase type (for tracking)
+  payments ContractPayment[]
+
+  // Back-relation for contracts where this is the current phase
+  currentForContracts Contract[] @relation("CurrentPhase")
+
+  @@index([contractId])
+  @@index([phaseCategory])
+  @@index([status])
+  @@index([order])
+  @@map("contract_phases")
+}
+
+// =============================================================================
+// QUESTIONNAIRE PHASE DATA - Extension for QUESTIONNAIRE phases
+// =============================================================================
+// Collects form data from users (eligibility, pre-approval, underwriting inputs)
+// =============================================================================
+
+model QuestionnairePhase {
+  id      String        @id @default(cuid())
+  phaseId String        @unique
+  phase   ContractPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+
+  // Progress tracking
+  completedFieldsCount Int @default(0)
+  totalFieldsCount     Int @default(0)
+
+  // Computed results (for UNDERWRITING phases)
+  underwritingScore    Float?
+  debtToIncomeRatio    Float?
+  underwritingDecision String? // APPROVED, CONDITIONAL, DECLINED
+  underwritingNotes    String? @db.Text
+
+  // Snapshot of field definitions at creation
+  fieldsSnapshot Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Child records
+  fields QuestionnaireField[]
+
+  @@index([phaseId])
+  @@map("questionnaire_phases")
+}
+
+// =============================================================================
+// DOCUMENTATION PHASE DATA - Extension for DOCUMENTATION phases
+// =============================================================================
+// Manages document upload/approval workflow with FSM steps
+// =============================================================================
+
+model DocumentationPhase {
+  id      String        @id @default(cuid())
+  phaseId String        @unique
+  phase   ContractPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+
+  // Current step pointer for UX and orchestration
+  currentStepId String?
+  currentStep   DocumentationStep? @relation("CurrentStep", fields: [currentStepId], references: [id])
+
+  // Progress counters
+  approvedDocumentsCount Int @default(0)
+  requiredDocumentsCount Int @default(0)
+  completedStepsCount    Int @default(0)
+  totalStepsCount        Int @default(0)
+
+  // Completion criteria
+  minimumCompletionPercentage Float?
+  completionCriterion         CompletionCriterion?
+
+  // Snapshots for audit
+  stepDefinitionsSnapshot  Json?
+  requiredDocumentSnapshot Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Child records
+  steps DocumentationStep[]
+
+  @@index([phaseId])
+  @@index([currentStepId])
+  @@map("documentation_phases")
+}
+
+// =============================================================================
+// PAYMENT PHASE DATA - Extension for PAYMENT phases
+// =============================================================================
+// Manages installment-based payment collection
+// =============================================================================
+
+model PaymentPhase {
+  id      String        @id @default(cuid())
+  phaseId String        @unique
+  phase   ContractPhase @relation(fields: [phaseId], references: [id], onDelete: Cascade)
+
+  // Payment plan reference
+  paymentPlanId String?
+  paymentPlan   PaymentPlan? @relation(fields: [paymentPlanId], references: [id])
+
+  // Financial details
+  totalAmount  Float
+  paidAmount   Float @default(0)
+  interestRate Float @default(0)
+
+  // User-selected term (for flexible-term plans like mortgages)
+  // These are set when user selects their preferred term at application time
+  selectedTermMonths   Int? // User's chosen term (e.g., 240 for 20 years)
+  numberOfInstallments Int? // Calculated from selectedTermMonths and frequency
+
+  // Fund collection behavior
+  // true = we collect funds via wallet/gateway (e.g., downpayment)
+  // false = external payment, we only track/reconcile (e.g., bank mortgage)
+  collectFunds Boolean @default(true)
+
+  // Completion criteria
+  minimumCompletionPercentage Float?
+
+  // Snapshot for audit
+  paymentPlanSnapshot Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Child records
+  installments ContractInstallment[]
+
+  @@index([phaseId])
+  @@index([paymentPlanId])
+  @@map("payment_phases")
+}
+
+// =============================================================================
+// QUESTIONNAIRE FIELDS - Instantiated fields within QUESTIONNAIRE phases
+// =============================================================================
+// When a contract is created from a payment method template, questionnaire field
+// templates are copied to QuestionnaireField records. Users submit answers here.
+// =============================================================================
+
+model QuestionnaireField {
+  id                   String             @id @default(cuid())
+  questionnairePhaseId String
+  questionnairePhase   QuestionnairePhase @relation(fields: [questionnairePhaseId], references: [id], onDelete: Cascade)
+
+  // Field identification (copied from template)
+  name        String // Internal field name (e.g., "monthly_income")
+  label       String // Display label (e.g., "Monthly Income")
+  description String? @db.Text
+  placeholder String?
+
+  // Field configuration (copied from template)
+  fieldType  FieldType
+  isRequired Boolean   @default(true)
+  order      Int
+
+  // Validation rules (copied from template)
+  validation       Json?
+  displayCondition Json?
+  defaultValue     Json?
+
+  // User's submitted answer (JSON to support any type)
+  // TEXT: "John Doe"
+  // NUMBER/CURRENCY: 500000
+  // SELECT: "employed"
+  // MULTI_SELECT: ["option1", "option2"]
+  // CHECKBOX: true
+  // DATE: "2024-01-15"
+  answer Json?
+
+  // Validation status
+  isValid          Boolean @default(false)
+  validationErrors Json? // Array of error messages if invalid
+
+  // Timestamps
+  submittedAt DateTime?
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+
+  @@unique([questionnairePhaseId, name])
+  @@index([questionnairePhaseId])
+  @@map("questionnaire_fields")
+}
+
+// =============================================================================
+// CONTRACT EVENTS - Audit trail for contract lifecycle
+// =============================================================================
+// Tracks all significant events in a contract's lifecycle for audit, compliance,
+// and debugging. Unlike DomainEvent (which is for inter-service communication),
+// ContractEvent is purely for historical tracking and state machine transitions.
+// =============================================================================
+model ContractEvent {
+  id         String   @id @default(cuid())
+  contractId String
+  contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+
+  // Event classification
+  eventType  ContractEventType
+  eventGroup ContractEventGroup?
+
+  // For state transitions (optional - only populated for CONTRACT_STATE_CHANGED events)
+  fromState String?
+  toState   String?
+  trigger   String?
+
+  // Event payload (all event-specific data)
+  data Json?
+
+  // Actor tracking
+  actorId   String?
+  actorType EventActorType?
+
+  // Timing
+  occurredAt DateTime @default(now())
+
+  @@index([contractId])
+  @@index([eventType])
+  @@index([eventGroup])
+  @@index([occurredAt])
+  @@map("contract_events")
+}
+
+// Steps within a DOCUMENTATION phase (FSM for document collection/approval)
+model DocumentationStep {
+  id                   String             @id @default(cuid())
+  documentationPhaseId String
+  documentationPhase   DocumentationPhase @relation(fields: [documentationPhaseId], references: [id], onDelete: Cascade)
+
+  name        String
+  description String?  @db.Text
+  stepType    StepType
+  order       Int
+
+  status StepStatus @default(PENDING)
+
+  // =========================================================================
+  // USER ACTION TRACKING - For rejection/resubmission flows
+  // =========================================================================
+  // When status is NEEDS_RESUBMISSION or ACTION_REQUIRED, this explains why.
+  // Populated from DocumentationStepApproval.comment on rejection.
+  actionReason String? @db.Text
+
+  // Number of times this step has been submitted (for tracking resubmissions)
+  submissionCount Int @default(0)
+
+  // Last submission timestamp (for tracking resubmission timing)
+  lastSubmittedAt DateTime?
+
+  // Configuration metadata (for GENERATE_DOCUMENT steps, etc.)
+  metadata Json?
+
+  // Assignment
+  assigneeId String?
+  assignee   User?   @relation("DocumentationStepAssignee", fields: [assigneeId], references: [id])
+
+  // Required document types for UPLOAD steps (normalized)
+  requiredDocuments DocumentationStepDocument[]
+
+  // Timing
+  dueDate     DateTime?
+  completedAt DateTime?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  approvals       DocumentationStepApproval[]
+  currentForPhase DocumentationPhase[]        @relation("CurrentStep")
+
+  @@index([documentationPhaseId])
+  @@index([status])
+  @@index([order])
+  @@map("documentation_steps")
+}
+
+// Required documents for a step (normalized from CSV)
+model DocumentationStepDocument {
+  id     String            @id @default(cuid())
+  stepId String
+  step   DocumentationStep @relation(fields: [stepId], references: [id], onDelete: Cascade)
+
+  documentType String
+  isRequired   Boolean @default(true)
+
+  createdAt DateTime @default(now())
+
+  @@index([stepId, documentType])
+  @@map("documentation_step_documents")
+}
+
+// Approvals for documentation steps
+model DocumentationStepApproval {
+  id         String            @id @default(cuid())
+  stepId     String
+  step       DocumentationStep @relation(fields: [stepId], references: [id], onDelete: Cascade)
+  approverId String?
+  approver   User?             @relation("DocumentationStepApprover", fields: [approverId], references: [id])
+
+  decision  ApprovalDecision
+  comment   String?          @db.Text
+  decidedAt DateTime         @default(now())
+
+  createdAt DateTime @default(now())
+
+  @@index([stepId])
+  @@map("documentation_step_approvals")
+}
+
+// Installments within a PAYMENT phase
+model ContractInstallment {
+  id             String       @id @default(cuid())
+  paymentPhaseId String
+  paymentPhase   PaymentPhase @relation(fields: [paymentPhaseId], references: [id], onDelete: Cascade)
+
+  installmentNumber Int
+
+  amount          Float
+  principalAmount Float @default(0)
+  interestAmount  Float @default(0)
+
+  dueDate DateTime
+  status  InstallmentStatus @default(PENDING)
+
+  paidAmount Float     @default(0)
+  paidDate   DateTime?
+
+  lateFee            Float     @default(0)
+  lateFeeWaived      Boolean   @default(false)
+  gracePeriodDays    Int       @default(0)
+  gracePeriodEndDate DateTime?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  payments ContractPayment[]
+
+  @@index([paymentPhaseId])
+  @@index([dueDate])
+  @@index([status])
+  @@map("contract_installments")
+}
+
+// Unified payment record for contracts
+model ContractPayment {
+  id            String               @id @default(cuid())
+  contractId    String
+  contract      Contract             @relation(fields: [contractId], references: [id], onDelete: Cascade)
+  phaseId       String?
+  phase         ContractPhase?       @relation(fields: [phaseId], references: [id])
+  installmentId String?
+  installment   ContractInstallment? @relation(fields: [installmentId], references: [id])
+  payerId       String?
+  payer         User?                @relation("ContractPayer", fields: [payerId], references: [id])
+
+  amount          Float
+  principalAmount Float @default(0)
+  interestAmount  Float @default(0)
+  lateFeeAmount   Float @default(0)
+
+  paymentMethod String // BANK_TRANSFER, CREDIT_CARD, WALLET, CASH, CHECK
+  status        PaymentStatus @default(INITIATED)
+
+  reference       String? @unique
+  gatewayResponse String? @db.Text // JSON
+
+  processedAt DateTime?
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+
+  @@index([contractId])
+  @@index([phaseId])
+  @@index([installmentId])
+  @@index([payerId])
+  @@index([status])
+  @@index([reference])
+  @@map("contract_payments")
+}
+
+// Contract documents (owned by contract, linked to phases/steps as needed)
+model ContractDocument {
+  id         String   @id @default(cuid())
+  contractId String
+  contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+  phaseId    String? // Optional link to specific phase
+  stepId     String? // Optional link to specific step
+
+  name         String
+  url          String
+  type         String // ID, BANK_STATEMENT, INCOME_PROOF, TITLE_DEED, SIGNATURE, etc.
+  uploadedById String?
+  uploadedBy   User?   @relation("DocumentUploader", fields: [uploadedById], references: [id])
+
+  status DocumentStatus @default(PENDING)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([contractId])
+  @@index([phaseId])
+  @@index([stepId])
+  @@index([type])
+  @@index([status])
+  @@map("contract_documents")
+}
+
+// =============================================================================
+// OFFER LETTERS - Provisional and Final offer documents
+// =============================================================================
+
+model DocumentTemplate {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  name        String // "Provisional Offer Letter", "Final Offer Letter"
+  code        String // PROVISIONAL_OFFER, FINAL_OFFER
+  description String?
+  version     Int     @default(1)
+
+  // Template content (Handlebars)
+  htmlTemplate String  @db.Text
+  cssStyles    String? @db.Text
+
+  // Merge field definitions for UI
+  mergeFields Json? // [{name, type, required, description}]
+
+  isActive  Boolean @default(true)
+  isDefault Boolean @default(false)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  offerLetters OfferLetter[]
+
+  @@unique([tenantId, code, version])
+  @@index([tenantId])
+  @@index([code])
+  @@map("document_templates")
+}
+
+model OfferLetter {
+  id         String   @id @default(cuid())
+  tenantId   String
+  tenant     Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  contractId String
+  contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+
+  // Template used (optional - documents-service may handle default selection)
+  templateId String?
+  template   DocumentTemplate? @relation(fields: [templateId], references: [id])
+
+  // Letter details
+  letterNumber String            @unique // OL-XXXXXX
+  type         OfferLetterType
+  status       OfferLetterStatus @default(DRAFT)
+
+  // Generated document
+  htmlContent String? @db.Text // Rendered HTML
+  pdfUrl      String? // S3 URL of generated PDF
+  pdfKey      String? // S3 key for deletion/access
+
+  // Merge data used (snapshot for audit)
+  mergeData Json? // All data merged into template
+
+  // Signing workflow
+  sentAt        DateTime?
+  viewedAt      DateTime?
+  signedAt      DateTime?
+  signatureIp   String?
+  signatureData Json? // {method, timestamp, metadata}
+
+  // Validity
+  expiresAt    DateTime?
+  expiredAt    DateTime?
+  cancelledAt  DateTime?
+  cancelReason String?
+
+  // Audit
+  generatedById String?
+  generatedBy   User?   @relation("OfferLetterGenerator", fields: [generatedById], references: [id])
+  sentById      String?
+  sentBy        User?   @relation("OfferLetterSender", fields: [sentById], references: [id])
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([tenantId])
+  @@index([contractId])
+  @@index([type])
+  @@index([status])
+  @@map("offer_letters")
+}
+
+// =============================================================================
+// CONTRACT TERMINATION - Full lifecycle for cancellation/termination
+// =============================================================================
+// Tracks termination requests from initiation through refund completion.
+// Industry-standard flow:
+// 1. Request created (by buyer/seller/admin/system)
+// 2. Admin reviews (if required by policy)
+// 3. Financial settlement calculated (refunds, penalties, forfeitures)
+// 4. Refund processed (if applicable)
+// 5. Contract marked terminated, unit released
+// =============================================================================
+
+model ContractTermination {
+  id         String   @id @default(cuid())
+  contractId String
+  contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+  tenantId   String
+  tenant     Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Request identification
+  requestNumber String @unique // TRM-XXXXXX
+
+  // Who initiated and why
+  initiatedBy    TerminationInitiator
+  initiatorId    String? // userId if BUYER/SELLER/ADMIN
+  initiator      User?                @relation("TerminationInitiator", fields: [initiatorId], references: [id])
+  type           TerminationType
+  reason         String?              @db.Text
+  supportingDocs Json? // [{type, url, uploadedAt}]
+
+  // Workflow status
+  status              TerminationStatus @default(REQUESTED)
+  requiresApproval    Boolean           @default(true)
+  autoApproveEligible Boolean           @default(false) // Pre-signature, no payments
+
+  // Admin review
+  reviewedBy      String?
+  reviewer        User?     @relation("TerminationReviewer", fields: [reviewedBy], references: [id])
+  reviewedAt      DateTime?
+  reviewNotes     String?   @db.Text
+  rejectionReason String?   @db.Text
+
+  // Financial snapshot at time of request
+  contractSnapshot    Json // Full contract state snapshot
+  totalContractAmount Float
+  totalPaidToDate     Float
+  outstandingBalance  Float
+
+  // Settlement calculation
+  refundableAmount Float   @default(0) // Amount eligible for refund
+  penaltyAmount    Float   @default(0) // Penalties/fees to deduct
+  forfeitedAmount  Float   @default(0) // Amount forfeited (non-refundable deposits)
+  adminFeeAmount   Float   @default(0) // Processing fees
+  netRefundAmount  Float   @default(0) // refundableAmount - penaltyAmount - adminFeeAmount
+  settlementNotes  String? @db.Text
+
+  // Refund processing
+  refundStatus         RefundStatus @default(PENDING)
+  refundReference      String? // Payment gateway reference
+  refundMethod         String? // ORIGINAL_METHOD, BANK_TRANSFER, CHECK, WALLET
+  refundAccountDetails Json? // Encrypted bank details if needed
+  refundInitiatedAt    DateTime?
+  refundCompletedAt    DateTime?
+  refundFailureReason  String?      @db.Text
+
+  // Property unit handling
+  unitReleasedAt    DateTime?
+  unitReservedForId String? // If unit being held for another buyer
+
+  // Timing
+  requestedAt DateTime  @default(now())
+  approvedAt  DateTime?
+  executedAt  DateTime?
+  completedAt DateTime?
+  cancelledAt DateTime?
+
+  // Idempotency and audit
+  idempotencyKey String? @unique
+  metadata       Json?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([contractId])
+  @@index([tenantId])
+  @@index([status])
+  @@index([type])
+  @@index([initiatorId])
+  @@index([requestedAt])
+  @@map("contract_terminations")
+}
+
+// =============================================================================
+// PAYMENT METHOD CHANGE REQUEST - Mid-contract payment method changes
+// =============================================================================
+// When a user wants to change their payment method after contract creation,
+// this aggregate tracks the request, required documentation, approvals, and
+// final execution. Different from-to combinations may require different docs.
+// =============================================================================
+
+enum PaymentMethodChangeStatus {
+  PENDING_DOCUMENTS
+  DOCUMENTS_SUBMITTED
+  UNDER_REVIEW
+  APPROVED
+  REJECTED
+  EXECUTED
+  CANCELLED
+}
+
+model PaymentMethodChangeRequest {
+  id         String   @id @default(cuid())
+  tenantId   String
+  tenant     Tenant   @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+  contractId String
+  contract   Contract @relation(fields: [contractId], references: [id], onDelete: Cascade)
+
+  // The change being requested
+  fromPaymentMethodId String
+  fromPaymentMethod   PropertyPaymentMethod @relation("ChangeFromMethod", fields: [fromPaymentMethodId], references: [id])
+  toPaymentMethodId   String
+  toPaymentMethod     PropertyPaymentMethod @relation("ChangeToMethod", fields: [toPaymentMethodId], references: [id])
+
+  // Who requested and why
+  requestorId String
+  requestor   User    @relation("ChangeRequestor", fields: [requestorId], references: [id])
+  reason      String? @db.Text
+
+  // Documentation requirements (determined by DocumentRequirementRule)
+  requiredDocumentTypes String? // CSV: BANK_STATEMENT,INCOME_PROOF,NEW_EMPLOYER_LETTER
+  submittedDocuments    Json? // [{type, s3Key, uploadedAt, status}]
+
+  // Financial impact assessment
+  currentOutstanding   Float? // Outstanding balance at time of request
+  newTermMonths        Int? // New term if applicable
+  newInterestRate      Float? // New rate if applicable
+  newMonthlyPayment    Float? // Projected new payment
+  penaltyAmount        Float? // Early change penalty if applicable
+  financialImpactNotes String? @db.Text
+
+  // Status and workflow
+  status      PaymentMethodChangeStatus @default(PENDING_DOCUMENTS)
+  reviewerId  String?
+  reviewer    User?                     @relation("ChangeReviewer", fields: [reviewerId], references: [id])
+  reviewNotes String?                   @db.Text
+  reviewedAt  DateTime?
+
+  // Execution details
+  executedAt        DateTime?
+  previousPhaseData Json? // Snapshot of phases before change
+  newPhaseData      Json? // New phases created after change
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([tenantId])
+  @@index([contractId])
+  @@index([status])
+  @@index([requestorId])
+  @@map("payment_method_change_requests")
+}
+
+// =============================================================================
+// DOCUMENT REQUIREMENT RULES - Configurable document requirements
+// =============================================================================
+// Admins can configure which documents are required for specific scenarios:
+// - Prequalification for a payment method type
+// - Contract phases
+// - Payment method changes (from-to combinations)
+// This allows tenants to customize documentation workflows per product.
+// =============================================================================
+
+enum DocumentRequirementContext {
+  CONTRACT_PHASE // During a contract phase
+  PAYMENT_METHOD_CHANGE // When changing payment method mid-contract
+}
+
+model DocumentRequirementRule {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Rule context
+  context DocumentRequirementContext
+
+  // Scoping (which situations this rule applies to)
+  // For PREQUALIFICATION: paymentMethodId
+  // For CONTRACT_PHASE: phaseType
+  // For PAYMENT_METHOD_CHANGE: fromMethodId + toMethodId
+  paymentMethodId     String?
+  paymentMethod       PropertyPaymentMethod? @relation("RulePaymentMethod", fields: [paymentMethodId], references: [id])
+  phaseType           String? // KYC, VERIFICATION, DOWNPAYMENT, etc.
+  fromPaymentMethodId String?
+  fromPaymentMethod   PropertyPaymentMethod? @relation("RuleFromMethod", fields: [fromPaymentMethodId], references: [id])
+  toPaymentMethodId   String?
+  toPaymentMethod     PropertyPaymentMethod? @relation("RuleToMethod", fields: [toPaymentMethodId], references: [id])
+
+  // Document requirements
+  documentType     String // ID_CARD, PASSPORT, BANK_STATEMENT, INCOME_PROOF, etc.
+  isRequired       Boolean @default(true)
+  description      String? // Instructions for the user
+  maxSizeBytes     Int? // Max file size allowed
+  allowedMimeTypes String? // CSV: application/pdf,image/jpeg,image/png
+
+  // Validation rules
+  expiryDays           Int? // Document must not be older than X days
+  requiresManualReview Boolean @default(false)
+
+  isActive  Boolean  @default(true)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([tenantId])
+  @@index([context])
+  @@index([paymentMethodId])
+  @@index([phaseType])
+  @@index([fromPaymentMethodId, toPaymentMethodId])
+  @@map("document_requirement_rules")
+}
+
+// =============================================================================
+// EVENT-DRIVEN WORKFLOW CONFIGURATION
+// =============================================================================
+// This system allows admins to configure event channels, types, and handlers
+// for a flexible, configurable event-driven workflow system.
+//
+// Architecture:
+// 1. EventChannel - Logical grouping of events (e.g., "contracts", "payments")
+// 2. EventType - Specific event types (e.g., "DOCUMENT_UPLOADED", "STEP_COMPLETED")
+// 3. EventHandler - What to do when an event fires (webhook, internal call, etc.)
+// 4. WorkflowEvent - Actual event instances (audit log)
+// 5. EventHandlerExecution - Log of handler executions
+// =============================================================================
+
+/// Event Channel - A logical grouping of events
+/// Channels help organize events and route them to appropriate handlers
+model EventChannel {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  /// Unique code for the channel (e.g., "CONTRACTS", "PAYMENTS")
+  code        String
+  /// Human-readable name
+  name        String
+  /// Description of what this channel handles
+  description String? @db.Text
+
+  /// Whether this channel is active
+  enabled Boolean @default(true)
+
+  /// Event types that belong to this channel
+  eventTypes EventType[]
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([tenantId, code])
+  @@index([tenantId])
+  @@map("event_channels")
+}
+
+/// Event Type - Defines a type of event that can occur
+/// Each event type belongs to a channel and can have multiple handlers
+model EventType {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  /// The channel this event type belongs to
+  channelId String
+  channel   EventChannel @relation(fields: [channelId], references: [id], onDelete: Cascade)
+
+  /// Unique code for this event type (e.g., "DOCUMENT_UPLOADED")
+  code        String
+  /// Human-readable name
+  name        String
+  /// Description of when this event fires
+  description String? @db.Text
+
+  /// JSON schema for event payload validation (optional)
+  payloadSchema Json?
+
+  /// Whether this event type is active
+  enabled Boolean @default(true)
+
+  /// Handlers subscribed to this event type
+  handlers EventHandler[]
+
+  /// Actual event instances of this type
+  events WorkflowEvent[]
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([tenantId, code])
+  @@unique([channelId, code])
+  @@index([tenantId])
+  @@index([channelId])
+  @@map("event_types")
+}
+
+/// Event Handler - Defines what should happen when an event fires
+/// Handlers can be internal (call a service), external (webhook), or workflow triggers
+model EventHandler {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  /// The event type this handler responds to
+  eventTypeId String
+  eventType   EventType @relation(fields: [eventTypeId], references: [id], onDelete: Cascade)
+
+  /// Human-readable name
+  name        String
+  /// Description of what this handler does
+  description String? @db.Text
+
+  /// Handler type determines how the event is processed
+  handlerType EventHandlerType
+
+  /// Configuration for the handler (JSON, depends on handlerType)
+  /// INTERNAL: { "service": "contract", "method": "completeStep" }
+  /// WEBHOOK: { "url": "https://...", "method": "POST", "headers": {...} }
+  /// WORKFLOW: { "workflowId": "...", "action": "advance" }
+  /// NOTIFICATION: { "template": "...", "channels": ["email", "sms"] }
+  config Json
+
+  /// Order of execution when multiple handlers exist (lower = first)
+  priority Int @default(100)
+
+  /// Whether this handler is active
+  enabled Boolean @default(true)
+
+  /// Retry configuration
+  maxRetries   Int @default(3)
+  retryDelayMs Int @default(1000)
+
+  /// Filter condition (JSONPath expression) to conditionally run
+  /// e.g., "$.payload.status == 'approved'"
+  filterCondition String? @db.Text
+
+  /// Handler execution logs
+  executions EventHandlerExecution[]
+
+  /// Step attachments - steps that have attached this handler
+  stepAttachments StepEventAttachment[]
+
+  /// Phase attachments - phases that have attached this handler
+  phaseAttachments PhaseEventAttachment[]
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([tenantId])
+  @@index([eventTypeId])
+  @@index([handlerType])
+  @@map("event_handlers")
+}
+
+/// Workflow Event - An actual event instance that occurred
+/// This is the audit log of all events in the system
+model WorkflowEvent {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  /// The type of this event
+  eventTypeId String
+  eventType   EventType @relation(fields: [eventTypeId], references: [id], onDelete: Cascade)
+
+  /// The event payload (actual data)
+  payload Json
+
+  /// Optional correlation ID to link related events
+  correlationId String?
+
+  /// Optional causation ID (which event caused this one)
+  causationId String?
+
+  /// Source of the event (service name, user action, etc.)
+  source String
+
+  /// Actor who triggered the event (user ID, API key ID, "system")
+  actorId   String?
+  actorType ActorType @default(SYSTEM)
+
+  /// Event status
+  status WorkflowEventStatus @default(PENDING)
+
+  /// Error message if processing failed
+  error String? @db.Text
+
+  /// When the event was processed
+  processedAt DateTime?
+
+  /// Handler executions for this event
+  executions EventHandlerExecution[]
+
+  createdAt DateTime @default(now())
+
+  @@index([tenantId])
+  @@index([eventTypeId])
+  @@index([correlationId])
+  @@index([causationId])
+  @@index([status])
+  @@index([createdAt])
+  @@map("workflow_events")
+}
+
+/// Event Handler Execution - Log of a handler processing an event
+model EventHandlerExecution {
+  id String @id @default(cuid())
+
+  /// The event being processed
+  eventId String
+  event   WorkflowEvent @relation(fields: [eventId], references: [id], onDelete: Cascade)
+
+  /// The handler that processed this event
+  handlerId String
+  handler   EventHandler @relation(fields: [handlerId], references: [id], onDelete: Cascade)
+
+  /// Execution status
+  status ExecutionStatus @default(PENDING)
+
+  /// Attempt number (1 for first try, increments on retry)
+  attempt Int @default(1)
+
+  /// Input to the handler (may be transformed payload)
+  input Json?
+
+  /// Output from the handler
+  output Json?
+
+  /// Error details if failed
+  error     String? @db.Text
+  errorCode String?
+
+  /// Timing
+  startedAt   DateTime?
+  completedAt DateTime?
+  durationMs  Int?
+
+  createdAt DateTime @default(now())
+
+  @@index([eventId])
+  @@index([handlerId])
+  @@index([status])
+  @@map("event_handler_executions")
+}
+
+// =============================================================================
+// EVENT OUTBOX - For guaranteed event delivery to SQS queues
+// =============================================================================
+
+model DomainEvent {
+  id String @id @default(cuid())
+
+  // Event identification
+  eventType     String // MORTGAGE.CREATED, PHASE.ACTIVATED, PAYMENT.COMPLETED, etc
+  aggregateType String // Mortgage, MortgagePhase, MortgagePayment, Property, etc
+  aggregateId   String
+
+  // Routing - which queue(s) should receive this
+  queueName String // notifications, payments, mortgage-steps, accounting, etc
+
+  // Event payload (all data needed by consumers)
+  payload String @db.Text // JSON
+
+  // Metadata
+  occurredAt DateTime @default(now())
+  actorId    String? // User who triggered the event
+  actorRole  String? // Role of the actor
+
+  // Processing status
+  status       String    @default("PENDING") // PENDING, PROCESSING, SENT, FAILED
+  processedAt  DateTime?
+  sentAt       DateTime?
+  failureCount Int       @default(0)
+  lastError    String?   @db.Text
+  nextRetryAt  DateTime?
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([status, nextRetryAt])
+  @@index([eventType])
+  @@index([aggregateType, aggregateId])
+  @@index([queueName])
+  @@index([occurredAt])
+  @@map("domain_events")
+}
+
+// =============================================================================
+// Property Transfer Request
+// =============================================================================
+// Allows a buyer to request transferring their contract to a different property.
+// 
+// TRANSFER PAYMENT FLOW:
+// 1. All payments from source contract are refunded to buyer's wallet (single credit transaction)
+// 2. Source contract marked TRANSFERRED, unit released
+// 3. New contract created for target unit with zero payments
+// 4. Buyer can optionally apply wallet balance as equity during new mortgage application
+//
+// This ensures clean accounting: each contract has isolated payment history,
+// wallet serves as intermediary, and buyer retains full credit.
+// =============================================================================
+
+model PropertyTransferRequest {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Source contract being transferred
+  sourceContractId String
+  sourceContract   Contract @relation("SourceContract", fields: [sourceContractId], references: [id], onDelete: Cascade)
+
+  // Target property unit
+  targetPropertyUnitId String
+  targetPropertyUnit   PropertyUnit @relation(fields: [targetPropertyUnitId], references: [id])
+
+  // Requestor (buyer) and reviewer (admin)
+  requestedById String
+  requestedBy   User    @relation("TransferRequestor", fields: [requestedById], references: [id])
+  reviewedById  String?
+  reviewedBy    User?   @relation("TransferReviewer", fields: [reviewedById], references: [id])
+
+  // Status and workflow
+  status TransferRequestStatus @default(PENDING)
+
+  // Request details
+  reason String? @db.Text // Buyer's reason for transfer
+
+  // Review details
+  reviewNotes             String? @db.Text // Admin notes on decision
+  priceAdjustmentHandling String? // How to handle price difference: ADD_TO_MORTGAGE, REQUIRE_PAYMENT, CREDIT_BUYER
+
+  // Computed values
+  sourceTotalAmount Float? // Original contract total
+  targetTotalAmount Float? // New contract total (based on target property)
+  priceAdjustment   Float? // Difference (positive = buyer owes more)
+
+  // Wallet refund tracking (payments refunded to wallet, NOT carried over)
+  refundedAmount      Float? // Total amount refunded to wallet
+  refundTransactionId String? // Reference to wallet Transaction record
+  refundedAt          DateTime?
+
+  // Result - new contract created after approval
+  targetContractId String?
+  targetContract   Contract? @relation("TargetContract", fields: [targetContractId], references: [id])
+
+  // Timestamps
+  createdAt   DateTime  @default(now())
+  reviewedAt  DateTime?
+  completedAt DateTime?
+  updatedAt   DateTime  @updatedAt
+
+  @@index([tenantId])
+  @@index([sourceContractId])
+  @@index([targetPropertyUnitId])
+  @@index([requestedById])
+  @@index([status])
+  @@map("property_transfer_requests")
+}
+
+// =============================================================================
+// UNIFIED APPROVAL REQUESTS
+// =============================================================================
+
+enum ApprovalRequestType {
+  PROPERTY_TRANSFER // Property unit transfer between contracts
+  PROPERTY_UPDATE // Property/unit listing update requiring approval
+  USER_WORKFLOW // User workflow step approval
+  CREDIT_CHECK // Credit check result review
+  CONTRACT_TERMINATION // Contract termination approval
+  REFUND_APPROVAL // Refund request approval
+}
+
+enum ApprovalRequestStatus {
+  PENDING // Awaiting review
+  IN_REVIEW // Assigned to reviewer
+  APPROVED // Approved by reviewer
+  REJECTED // Rejected by reviewer
+  CANCELLED // Cancelled by requestor
+  EXPIRED // Auto-expired (if TTL configured)
+}
+
+enum ApprovalRequestPriority {
+  LOW
+  NORMAL
+  HIGH
+  URGENT
+}
+
+// Polymorphic approval request model for unified admin dashboard
+model ApprovalRequest {
+  id       String @id @default(cuid())
+  tenantId String
+  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Request type and status
+  type     ApprovalRequestType
+  status   ApprovalRequestStatus   @default(PENDING)
+  priority ApprovalRequestPriority @default(NORMAL)
+
+  // Polymorphic reference to the entity requiring approval
+  entityType String // e.g., "PropertyTransferRequest", "PropertyUnit", "User"
+  entityId   String // ID of the referenced entity
+
+  // Request metadata
+  title       String  @db.VarChar(255) // Human-readable title for the request
+  description String? @db.Text // Detailed description
+
+  // Payload for any additional context (JSON)
+  payload Json? // Flexible data storage for type-specific details
+
+  // Requestor - who created the request
+  requestedById String
+  requestedBy   User   @relation("ApprovalRequestor", fields: [requestedById], references: [id])
+
+  // Assignee - admin/reviewer assigned to handle this request
+  assigneeId String?
+  assignee   User?   @relation("ApprovalAssignee", fields: [assigneeId], references: [id])
+
+  // Reviewer - who made the final decision (may differ from assignee)
+  reviewedById String?
+  reviewedBy   User?   @relation("ApprovalReviewer", fields: [reviewedById], references: [id])
+
+  // Review details
+  reviewNotes String?           @db.Text // Reviewer's notes/comments
+  decision    ApprovalDecision? // APPROVED, REJECTED, REQUEST_CHANGES
+
+  // Expiration
+  expiresAt DateTime? // Optional TTL for auto-expiration
+
+  // Timestamps
+  createdAt   DateTime  @default(now())
+  assignedAt  DateTime? // When assigned to reviewer
+  reviewedAt  DateTime? // When decision was made
+  completedAt DateTime? // When fully processed
+  updatedAt   DateTime  @updatedAt
+
+  @@index([tenantId])
+  @@index([type])
+  @@index([status])
+  @@index([priority])
+  @@index([entityType, entityId])
+  @@index([requestedById])
+  @@index([assigneeId])
+  @@index([createdAt])
+  @@index([type, status]) // Efficient queries for approval dashboard
+  @@map("approval_requests")
+}