DMX Specification Language

// This is a line comment

/* This is a
   block comment */

service UserService {
  version = "1.0.0"
  port = 8000
  api_prefix = "/api/v1"
  database = "postgresql"

  // ... entities, api, flows, etc.
}

service AuthService {
  version    = "1.0.0"
  port       = 8000
  api_prefix = "/api"

  identity {
    service_name      = "Auth Service"
    service_version   = "2.4.1"
    service_slug      = "auth-svc"
    internal_hostname = "auth-svc.svc.cluster.local"
    internal_port     = 8081
    description       = "identity overrides"

    gateway {
      enabled          = true
      public_port      = 8443
      public_base_path = "/v2"
      mode             = auth_precheck
    }

    architecture {
      mode        = microservices
      mode_source = explicit
    }
  }
}

service AuthService {
  version    = "1.0.0"
  port       = 8000
  api_prefix = "/api"

  identity {
    service_version = "2.4.1"
  }
}

entity Order @audit @soft_delete {
  id          UUID      @pk @default($computed.uuid)
  customer_id UUID      @fk(Customer.id) @not_null
  total       Decimal   @not_null @check("total >= 0")
  status      Enum(DRAFT, PENDING, PAID, SHIPPED, CANCELLED) @default(DRAFT)
  notes       Text      @nullable
}

api REST @entity(Order) @paginated {
  // Standard CRUD endpoints are generated automatically
  // Custom endpoints:
  POST   "/orders/{id}/cancel"  @status(200) @triggers(order_cancelled)
  GET    "/orders/summary"      @roles(ADMIN)
}

flow RegisterUser {
  step validate_input {
    action = validate
    target = User
    mapping {
      email = $input.email
      password = $input.password
    }
  }

  step create_user {
    action = create
    target = User
    mapping {
      id = $computed.uuid
      email = $input.email
      password = $computed.hash_password($input.password)
      created_at = $computed.now
    }
  }

  step generate_token {
    action = calculate
    expression = $computed.sign_jwt($result.id, $result.role)
    result_capture = "token"
  }
}

state_machine OrderStatus {
  initial = DRAFT

  DRAFT -> PENDING @roles(MEMBER, ADMIN)
  PENDING -> PAID @guard("payment_confirmed == true")
  PAID -> SHIPPED @roles(ADMIN)
  SHIPPED -> DELIVERED
  PENDING -> CANCELLED @roles(MEMBER, ADMIN)
  DRAFT -> CANCELLED
}

validations {
  email {
    format = "email"
    uniqueness = true
  }
  age {
    range = "0..150"
    presence = true
  }
  username {
    format = "^[a-zA-Z0-9_]{3,30}$"
    uniqueness = true
  }
}

security {
  auth_scheme = "jwt"
  jwt_algorithm = "HS256"
  token_expiry_minutes = 60
  refresh_token_enabled = true
  password_hashing = "bcrypt"

  rate_limit {
    policy = "sliding_window"
    allow = 100
    for = "1m"
  }

  roles = [ADMIN, MEMBER, GUEST]
}

security {
  auth_scheme = "jwt"
  user_entity = "User"
  active_field = "is_active"

  credential_type_field = "credential_type"
  password_credential_kind = "password"
}

errors {
  USER_NOT_FOUND {
    status = 404
    category = "not_found"
    message = "User not found"
  }
  INVALID_CREDENTIALS {
    status = 401
    category = "auth"
    message = "Invalid email or password"
  }
}

jobs {
  cleanup_expired_tokens {
    schedule = "0 */6 * * *"
    timeout = "5m"
    retry {
      max_attempts = 3
      backoff = "exponential"
    }
  }
  send_daily_digest {
    schedule = "0 8 * * *"
    queue = "low_priority"
  }
}

notifications {
  providers {
    email { adapter = "smtp" }
    sms   { adapter = "twilio" }
    push  { adapter = "firebase" }
  }
  order_confirmed {
    channels = [email, push]
    recipient = $instance.customer.email
    template = "order_confirmed"
    locale = $context.locale
  }
}

file_storage {
  provider = "s3"
  bucket = "my-app-uploads"
  max_size = "10MB"
  allowed_types = ["image/png", "image/jpeg", "application/pdf"]
  virus_scan = true
  cdn_enabled = true
}

infrastructure {
  docker {
    compose_version = "3.8"
    base_image = "python:3.12-slim"
  }
  redis {
    broker = true
    cache = true
    pool_size = 10
  }
  celery {
    concurrency = 4
    queue = "default"
  }
  cors {
    allow = ["https://app.example.com"]
  }
}

infrastructure {
  rabbitmq {
    vhost = "/tenant_a"
    user_env = "RABBITMQ_USER"
    password_env = "RABBITMQ_PASSWORD"
    use_tls = true
    tls_ca_path_env = "RABBITMQ_CA_PATH"
    pool_size = 10
    max_overflow = 5
    heartbeat_seconds = 60
    prefetch_count = 50
    quorum_replication_factor = 3
    publisher_confirms = true
    mandatory_routing = true
    management {
      port = 15672
      user_env = "RABBITMQ_MGMT_USER"
      password_env = "RABBITMQ_MGMT_PASSWORD"
    }
    cluster {
      discovery_mode = "dns"
      static_peers = ["rmq-0", "rmq-1", "rmq-2"]
    }
    exchange "events" {
      type = "topic"
      durable = true
    }
    queue "events.q" {
      durable = true
      dead_letter_exchange = "events.dlx"
      dead_letter_routing_key = "events.dlq"
      max_length = 100000
      quorum = true
    }
  }
}

infrastructure {
  kafka {
    bootstrap_servers_env = "KAFKA_BOOTSTRAP_SERVERS"
    security_protocol = "SASL_SSL"
    sasl_mechanism = "SCRAM-SHA-512"
    sasl_user_env = "KAFKA_SASL_USER"
    sasl_password_env = "KAFKA_SASL_PASSWORD"
    tls_truststore_path_env = "KAFKA_TLS_TRUSTSTORE_PATH"
    tls_truststore_password_env = "KAFKA_TLS_TRUSTSTORE_PASSWORD"
    consumer_group_id = "svc_a.consumer"
    auto_offset_reset = "earliest"
    producer_acks = "all"
    producer_idempotence = true
    compression_type = "zstd"
    schema_registry {
      url_env = "KAFKA_SCHEMA_REGISTRY_URL"
      auth_user_env = "SR_USER"
      auth_password_env = "SR_PASSWORD"
    }
    topic "events" {
      partitions = 6
      replication_factor = 3
      min_insync_replicas = 2
      retention_ms = 604800000
      cleanup_policy = "compact"
      acl_read_principals = ["User:svc_a"]
      acl_write_principals = ["User:svc_publisher"]
    }
  }
}

infrastructure {
  elasticsearch {
    hosts_env = "ELASTICSEARCH_HOSTS"
    use_https = true
    verify_certs = true
    ca_bundle_path_env = "ELASTICSEARCH_CA_BUNDLE"
    rbac_roles = ["search_user", "index_admin"]
    bulk_batch_size = 1000
    bulk_timeout_seconds = 60
    watcher_enabled = false
    auth {
      method = "api_key"
      api_key_env = "ELASTICSEARCH_API_KEY"
    }
    index "logs" {
      tenant_prefix = "tenant_a"
      number_of_shards = 3
      number_of_replicas = 2
      min_insync_replicas = 2
      refresh_interval = "30s"
      lifecycle_policy = "logs-policy"
      ingest_pipeline = "enrich-logs"
    }
    ilm_policy "logs-policy" {
      phase "hot" { min_age = "0ms" }
      phase "warm" { min_age = "7d" }
      phase "delete" { min_age = "90d" }
    }
    snapshot_repository "primary" { type = "s3" }
    ingest_pipeline "enrich-logs" { description = "Add tenant tag" }
  }
}

platform "MyPlatform" {
  version = "1.0.0"

  modules {
    UserService         { spec = "user.dmx";         dependencies = [] }
    OrderService        { spec = "order.dmx";        dependencies = [UserService] }
    NotificationService { spec = "notification.dmx"; dependencies = [OrderService] }
  }

  shared_kernel { modules = [tenant_context, jwt_utils, event_bus, audit_decorator, observability] }

  interactions {
    "order-confirmed-notifies" {
      tier     = 1
      producer = OrderService
      consumer = NotificationService
      trigger  = event("order.confirmed")
      task     = "send_confirmation"
      queue    = "notifications"
    }
  }
}

interactions {
  "i-11-order-confirmed-notifies" {
    tier         = 1
    producer     = OrderService
    consumer     = NotificationService
    trigger      = event("order.confirmed")
    task         = "send_confirmation"
    event_schema = "order.confirmed@v2"
    ordering_key = "tenant_id"

    payload_map {
      order_id    = $instance.id
      customer_id = $instance.customer_id
      tenant_id   = $context.tenant_id
    }

    delivery {
      transport    = redis_streams
      outbox       = true
      ordering_key = "tenant_id"
      retry {
        max_attempts     = 5
        backoff          = "exponential"
        initial_delay_ms = 100
      }
      dlq {
        stream_name             = "order-confirmed.dlq"
        max_attempts_before_dlq = 5
      }
    }
  }
}

modules {
  control_plane { spec = "control_plane.dmx"; dependencies = [] }
  identity      { spec = "identity.dmx";      dependencies = [control_plane] }
  registry      { spec = "registry.dmx";      dependencies = [identity] }
  catalog       { spec = "catalog.dmx";       dependencies = [identity] }
  connectivity  { spec = "connectivity.dmx";  dependencies = [registry] }
  preanalytic   { spec = "preanalytic.dmx";   dependencies = [connectivity] }
  lab           { spec = "lab.dmx";           dependencies = [connectivity, preanalytic] }
}

celery {
  broker_url      = "redis://redis:6379/0"
  result_backend  = "redis://redis:6379/1"
  task_serializer = "json"
  concurrency     = 2

  worker worker_fast {
    queues = ["fast", "ocr", "notifications"]
  }
  worker worker_standard {
    queues = ["default", "pdf", "billing"]
  }
  worker worker_beat {
    role = scheduler    // Celery Beat scheduler
  }
}

interactions {
  "order-created" {
    tier     = 1
    producer = billing
    consumer = fulfillment
    trigger  = event("billing.order.created")
    task     = "process_order"
    queue    = "fulfillment-queue"
    payload {
      order_id UUID @required
      status   String
    }
  }
}

infrastructure {
  api_gateway {
    enabled = true
    type    = kong
    rate_limiting { enabled = true; requests_per_minute = 100 }
  }
  service_ports {
    control_plane = 8010
    identity      = 8001
  }
  jwt {
    algorithm              = "HS256"
    token_lifetime_minutes = 30
    issuer                 = "platform-name"
  }
  redis { host = "redis"; port = 6379 }
  databases {
    control_plane = "postgresql"
    datalake      = "clickhouse"
  }
  pagination {
    default_limit = 100
    max_limit     = 1000
  }
}

infrastructure {
  pagination {
    default_limit = 50    // default page size when client omits ?limit
    max_limit     = 500   // hard cap enforced via Query(le=...)
  }
}

compliance {
  profile "covered-entity" {
    scope                     = "protected_health_information"
    data_classes              = ["PHI", "PII"]
    retention_days            = 2190
    encryption_at_rest        = true
    encryption_in_transit     = true
    audit_required            = true
    access_review_days        = 90
    subject_rights            = ["access", "rectification", "erasure"]
    breach_notification_hours = 72
    residency                 = "US"
    validation_controls       = ["technical_safeguards", "administrative"]
    legal_basis               = "HIPAA-45-CFR-164"
    full_name                 = "Health Insurance Portability and Accountability Act"
    mode_alias                = "covered-entity"
    phi_keywords              = ["diagnosis", "patient_id", "mrn"]
    pii_keywords              = ["ssn", "passport"]
    min_retention_days        = 2190
    requires_read_audit       = true
    requires_pii_masking      = true
    requires_extended_retention = true
    requires_immutable_audit  = true
    requires_encrypted_audit  = true
    requires_actor_info       = true
    requires_digital_signature = false
    requires_request_metadata = true
    test_frameworks           = ["hipaa-test-suite"]
  }
}