Basic Model Example

This example shows how to create a simple data model for a SaaS product using MML 2.0.

Scenario

You're building a SaaS application and need to model:

• Users and their subscriptions
• Product usage metrics
• Revenue tracking
• Data products for reporting

Complete Example

File: models/conceptual/platform.mml

domain "Platform" {
  color = "#3498db"
  description = "Core platform entities"

  entity "User" {
    type = "entity"
    description = "Platform users with profile information"

    attribute "email" {
      type = "string"
      required = true
      pii = true
    }

    attribute "created_at" {
      type = "date"
      required = true
    }
  }

  entity "Account" {
    type = "entity"
    description = "Customer accounts that own subscriptions"

    belongs-to "Platform.User"
  }

  entity "Subscription" {
    type = "entity"
    description = "Active customer subscriptions"

    attribute "plan_amount" {
      type = "number"
      required = true
    }

    attribute "status" {
      type = "string"
      required = true
    }

    belongs-to "Platform.Account"
  }
}

domain "Analytics" {
  color = "#e74c3c"
  description = "Business metrics and derived data"

  entity "Monthly_Recurring_Revenue" {
    type = "metric"
    description = "Total MRR across all active subscriptions"
    business_logic = "SUM(Subscription.plan_amount) WHERE status = 'active'"

    derived-from "Platform.Subscription"
  }

  entity "Active_Users" {
    type = "metric"
    description = "Users active in the last 30 days"
    business_logic = "COUNT(DISTINCT user_id WHERE last_login >= NOW() - 30 days)"

    derived-from "Platform.User"
  }

  entity "Customer_Cohorts" {
    type = "derivation"
    description = "Customer segmentation by signup month and behavior"
    business_logic = "GROUP BY signup_month WITH retention and revenue metrics"

    derived-from "Platform.User"
    derived-from "Platform.Subscription"
  }
}

Step-by-Step Breakdown

1. Define Domains

Domains group related entities together:

domain "Platform" {
  color = "#3498db"  // Blue color for visualization
  description = "Core platform entities"
}

2. Create Base Entities

Base entities represent core business objects:

entity "User" {
  type = "entity"  // Base entity type
  description = "Platform users with profile information"

  attribute "email" {
    type = "string"
    required = true
    pii = true
  }
}

3. Define Relationships

Use belongs-to to show entity relationships:

entity "Account" {
  type = "entity"
  description = "Customer accounts that own subscriptions"

  belongs-to "Platform.User"  // Reference with dot notation
}

4. Add Metrics

Metrics are calculations derived from entities:

entity "Monthly_Recurring_Revenue" {
  type = "metric"
  description = "Total MRR across all active subscriptions"
  business_logic = "SUM(Subscription.plan_amount) WHERE status = 'active'"

  derived-from "Platform.Subscription"
}

5. Create Derivations

Derivations are transformed datasets:

entity "Customer_Cohorts" {
  type = "derivation"
  description = "Customer segmentation by signup month"
  business_logic = "GROUP BY signup_month WITH retention metrics"

  derived-from "Platform.User"
  derived-from "Platform.Subscription"
}

Adding Sources and Data Products

File: models/logical/sources.mml

Map entities to physical data sources:

source "PostgreSQL_Production" {
  type = "postgres"
  description = "Production database"
  host = "prod-db.company.com"
  database = "saas_app"

  entity "Platform.User" {
    table = "users"
  }

  entity "Platform.Account" {
    table = "accounts"
  }

  entity "Platform.Subscription" {
    table = "subscriptions"
  }
}

File: products/analytics.mml

Create data products for consumption:

data_product "SaaS_Metrics" {
  description = "Core SaaS business metrics"
  owner = "analytics-team"
  refresh_schedule = "0 * * * *"  // Hourly

  consumer "executives"
  consumer "product-team"

  report "Revenue_Dashboard" {
    type = "dashboard"
    description = "Real-time revenue tracking"

    uses "Platform.Subscription"
    uses "Analytics.Monthly_Recurring_Revenue"

    metric "Total_MRR" {
      description = "Current MRR"
      calculation = "SUM(Subscription.plan_amount WHERE status = 'active')"
      target_value = "$100K"
      uses "Platform.Subscription"
    }

    metric "MRR_Growth" {
      description = "Month-over-month MRR growth"
      calculation = "(current_mrr - previous_mrr) / previous_mrr * 100"
      target_value = "10%"
      uses "Analytics.Monthly_Recurring_Revenue"
    }
  }
}

Visual Result

This model creates:

Platform Domain (Blue)
├── User (entity)
│   └── attributes: email, created_at
├── Account (entity)
│   └── belongs-to → User
└── Subscription (entity)
    ├── attributes: plan_amount, status
    └── belongs-to → Account

Analytics Domain (Red)
├── Monthly_Recurring_Revenue (metric)
│   └── derived-from → Platform.Subscription
├── Active_Users (metric)
│   └── derived-from → Platform.User
└── Customer_Cohorts (derivation)
    ├── derived-from → Platform.User
    └── derived-from → Platform.Subscription

Data Products
└── SaaS_Metrics
    └── Revenue_Dashboard (report)
        ├── Total_MRR (metric)
        └── MRR_Growth (metric)

Key Concepts Demonstrated

1. Entity Types: entity, metric, derivation
2. Attributes: Define fields with types and constraints
3. Relationships: belongs-to, derived-from
4. Domains: Organize entities logically
5. Sources: Map to physical databases
6. Data Products: Package for consumption
7. Reports: Group metrics together

Next Steps

1. Add more entities: Expand with events, features, or products
2. Map to sources: Create logical model mappings
3. Build data products: Define reports using these entities
4. Add estimates: Estimate implementation effort

Related Examples

• E-Commerce Platform - Complex retail model
• SaaS Analytics - Advanced analytics patterns