id: "implementation-profile"
version: "1.0.0"
name: "Implementation Design"
description: "Design and model the technical implementation details of your system, including classes, methods, services, integration patterns, and persistence structures"
icon: "Code"

# Metadata
metadata:
  tags:
    - "implementation"
    - "code-design"
    - "classes"
    - "services"
    - "rest-api"
    - "messaging"
    - "persistence"
    - "database"

# Status Enumerations
statusEnumerations: []

# Element Types
elementTypes:
  # Implementation Design
  - id: "implementation.service"
    name: "Service"
    description: "A service that implements business logic or technical functionality"
    descriptionDetailed: "A Service represents a service class or component that implements business logic or technical functionality. Services are typically stateless and provide operations that can be called by other components. They encapsulate business logic that doesn't naturally fit within domain entities."
    baseType: "default-model-element"
    layer: "application"
    trackable: true
    style:
      icon: "Function"
      accentColor: "#0f62fe"
      defaultCanvasStyle: "card"

  - id: "implementation.class"
    name: "Class"
    description: "A class that represents a data structure or component"
    descriptionDetailed: "A Class represents a class in object-oriented design. Classes can have attributes (properties) and methods. They can contain nested classes and methods to model complex class hierarchies and compositions."
    baseType: "default-model-element"
    layer: "application"
    trackable: true
    propertiesSchema:
      - "implementation-class-properties"
    style:
      icon: "Object"
      accentColor: "#007d79"
      defaultCanvasStyle: "card"

  - id: "implementation.method"
    name: "Method"
    description: "A method or operation that performs a specific function"
    descriptionDetailed: "A Method represents a method or operation within a class or service. Methods define the behavior and operations that can be performed. They can have parameters, return values, and implement specific functionality."
    baseType: "default-model-element"
    layer: "application"
    trackable: true
    style:
      icon: "Parameter"
      accentColor: "#0072c3"
      defaultCanvasStyle: "card"

  # Integration
  - id: "implementation.rest-api"
    name: "REST API"
    description: "A REST API that provides or consumes web services"
    descriptionDetailed: "A REST API represents a RESTful web service that provides or consumes HTTP-based services. REST APIs expose operations that can be called over HTTP. They can contain REST API operations that define the specific endpoints and methods."
    baseType: "default-model-element"
    layer: "application"
    trackable: true
    propertiesSchema:
      - "implementation-rest-api-properties"
    style:
      icon: "ConvertToCloud"
      accentColor: "#8a3ffc"
      defaultCanvasStyle: "card"

  - id: "implementation.rest-api-operation"
    name: "REST operation"
    description: "A REST API operation that defines an HTTP endpoint"
    descriptionDetailed: "A REST API Operation represents a specific HTTP endpoint and method (GET, POST, PUT, DELETE, etc.) within a REST API. Operations define the contract for how clients interact with the API, including the endpoint path, HTTP method, request/response formats, and whether the operation is provided or consumed."
    baseType: "default-model-element"
    layer: "application"
    trackable: true
    propertiesSchema:
      - "implementation-rest-api-operation-properties"
    style:
      icon: "CallsIncoming"
      accentColor: "#8a3ffc"
      defaultCanvasStyle: "card"

  - id: "implementation.soap-api"
    name: "SOAP API"
    description: "A SOAP API that provides or consumes web services"
    descriptionDetailed: "A SOAP API represents a SOAP-based web service that provides or consumes XML-based services over HTTP or other transport protocols. SOAP APIs use WSDL (Web Services Description Language) to define the service contract, including operations, messages, and data types. They can be used for enterprise integration and service-oriented architectures."
    baseType: "default-model-element"
    layer: "application"
    trackable: true
    propertiesSchema:
      - "implementation-soap-api-properties"
    style:
      icon: "ConvertToCloud"
      accentColor: "#8a3ffc"
      defaultCanvasStyle: "card"

  - id: "implementation.message-publisher"
    name: "Message publisher"
    description: "A component that publishes messages to a message broker"
    descriptionDetailed: "A Message Publisher represents a component that publishes messages to a message broker or message queue. Message publishers are used in event-driven architectures to send messages asynchronously. They publish messages to topics or queues that other components can subscribe to."
    baseType: "default-model-element"
    layer: "application"
    trackable: true
    style:
      icon: "ConnectionSend"
      accentColor: "#ba4e00"
      defaultCanvasStyle: "card"

  - id: "implementation.message-listener"
    name: "Message listener"
    description: "A component that listens for and consumes messages from a message broker"
    descriptionDetailed: "A Message Listener represents a component that listens for and consumes messages from a message broker or message queue. Message listeners subscribe to topics or queues and process incoming messages asynchronously. They are used in event-driven architectures to receive and handle messages."
    baseType: "default-model-element"
    layer: "application"
    trackable: true
    style:
      icon: "ConnectionReceive"
      accentColor: "#ba4e00"
      defaultCanvasStyle: "card"

  - id: "implementation.message-topic"
    name: "Message topic"
    description: "A message topic or queue that routes messages between publishers and listeners"
    descriptionDetailed: "A Message Topic represents a message topic or queue in a message broker that routes messages between publishers and listeners. Topics act as intermediaries that allow message publishers to send messages without knowing the specific listeners, and listeners to receive messages without knowing the specific publishers."
    baseType: "default-model-element"
    layer: "application"
    trackable: true
    style:
      icon: "MessageQueue"
      accentColor: "#8e6a00"
      defaultCanvasStyle: "card"

  - id: "implementation.message"
    name: "Message"
    description: "A message that is sent between components via message brokers"
    descriptionDetailed: "A Message represents a message that is sent between components via message brokers or message queues. Messages contain data and metadata that are exchanged asynchronously in event-driven architectures. They represent the contract and format of data exchanged between publishers and listeners."
    baseType: "default-model-element"
    layer: "application"
    trackable: true
    style:
      icon: "Email"
      accentColor: "#8e6a00"
      defaultCanvasStyle: "card"

  # Persistence
  - id: "implementation.db-collection"
    name: "DB collection"
    description: "A database collection (NoSQL) that stores documents or records"
    descriptionDetailed: "A DB Collection represents a collection in a NoSQL database (such as MongoDB) that stores documents or records. Collections are the equivalent of tables in relational databases but are schema-less and can store flexible document structures. They represent the data storage structure in document-oriented databases."
    baseType: "default-model-element"
    layer: "data"
    trackable: true
    style:
      icon: "DataCollection"
      accentColor: "#697077"
      defaultCanvasStyle: "card"

  - id: "implementation.db-table"
    name: "DB table"
    description: "A database table (relational) that stores records"
    descriptionDetailed: "A DB Table represents a table in a relational database that stores records with a fixed schema. Tables consist of columns (attributes) and rows (records). They represent the data storage structure in relational databases and define the schema for persistent data."
    baseType: "default-model-element"
    layer: "data"
    trackable: true
    style:
      icon: "Table"
      accentColor: "#697077"
      defaultCanvasStyle: "card"

# Relationship Types
relationshipTypes:
  - id: "implementation.extends"
    name: "extends"
    description: "Indicates that a class extends another class"
    descriptionDetailed: "An Extends relationship indicates that one class extends another class. This relationship is used to model inheritance hierarchies, where a subclass inherits properties and methods from a superclass."
    typeMappings:
      - sourceElementTypes: ["implementation.class"]
        targetElementTypes: ["implementation.class"]
    bidirectional: false
    relationshipType: "default"
    prefillLabel: false
    reverse:
      name: "extended by"
      description: "Classes extended by this class"
      descriptionDetailed: "The reverse of the 'Extends' relationship. When a class extends another class, the extended class is 'extended by' the superclass. This represents the perspective from the extended class's point of view."
    style:
      style: "line"
      startArrow: "none"
      endArrow: "arrow"
      defaultColor: "#000000"
      thickness: 1
  - id: "implementation.triggers"
    name: "triggers"
    description: "Indicates that one element triggers an implementation logic element (service, method, etc.)"
    descriptionDetailed: "A Triggers relationship indicates that one element triggers an implementation logic element (service, method, etc.)."
    typeMappings:
      - sourceElementTypes: ["ddd.*", "implementation.*"]
        targetElementTypes: ["implementation.service", "implementation.method"]
    bidirectional: false
    relationshipType: "default"
    prefillLabel: false
    reverse:
      name: "triggered by"
      description: "Implementation logic elements triggered by this element"
      descriptionDetailed: "The reverse of the 'Triggers' relationship. When an element triggers an implementation logic element, the triggered element is 'triggered by' the triggering element. This represents the perspective from the triggered element's point of view."
    style:
      style: "line"
      startArrow: "none"
      endArrow: "simple_arrow"
      defaultColor: "#000000"
      thickness: 1
  - id: "implementation.contains"
    name: "contains"
    description: "Indicates that an element contains another element"
    descriptionDetailed: "A Contains relationship represents that one element contains another element. This relationship is used to model composition structures, such as classes containing methods, classes containing nested classes, and REST APIs containing REST API operations."
    typeMappings:
      - sourceElementTypes: ["implementation.class"]
        targetElementTypes: ["implementation.method", "implementation.class"]
      - sourceElementTypes: ["implementation.rest-api"]
        targetElementTypes: ["implementation.rest-api-operation"]
    bidirectional: false
    relationshipType: "aggregation"
    prefillLabel: false
    reverse:
      name: "contained in"
      description: "Elements contained in this element"
      descriptionDetailed: "The reverse of the 'Contains' relationship. When an element contains another element, the contained element is 'contained in' the containing element. This represents the perspective from the contained element's point of view."
    style:
      style: "dashed"
      startArrow: "none"
      endArrow: "arrow"
      defaultColor: "#000000"
      thickness: 1

# Property Groups
propertyGroups:
  - id: "implementation-class-properties"
    name: "Class Properties"
    description: "Properties for classes including attributes"
    descriptionDetailed: "This property group contains properties specific to Class elements, including references to Property elements that define the data structure of the class."
    properties:
      - fieldName: "attributesDescription"
        displayName: "Attributes"
        description: "The attributes (properties) of the class"
        descriptionDetailed: "A list of attributes that define the data structure of the class. Each attribute represents an attribute with a name, type, and optional metadata such as whether it is required, whether it is an array, and a description."
        type: "formattedText"
        required: false

  - id: "implementation-property-properties"
    name: "Property Properties"
    description: "Properties for Property elements"
    descriptionDetailed: "This property group contains properties specific to Property elements, including the property name, data type, and metadata."
    properties:
      - fieldName: "property-name"
        displayName: "Name"
        description: "The name of the property"
        descriptionDetailed: "The name of the property, which must be a valid identifier."
        type: "text"
        required: true
      - fieldName: "property-type"
        displayName: "Type"
        description: "The data type of the property"
        descriptionDetailed: "The data type of the property (e.g., String, Integer, Boolean, Date, or a custom type)."
        type: "text"
        required: true
      - fieldName: "is-required"
        displayName: "Required"
        description: "Indicates if the property is required"
        descriptionDetailed: "Specifies whether the property is mandatory and must have a value."
        type: "boolean"
        required: false
        defaultValue: false
      - fieldName: "is-list"
        displayName: "Array"
        description: "Indicates if the property is an array or list"
        descriptionDetailed: "Specifies whether the property is an array or list that can contain multiple values."
        type: "boolean"
        required: false
        defaultValue: false

  - id: "implementation-rest-api-properties"
    name: "REST API Properties"
    description: "Properties for REST APIs"
    descriptionDetailed: "This property group contains properties specific to REST API elements, including the interaction type (providing or consuming) and OpenAPI specification."
    properties:
      - fieldName: "interaction-type"
        displayName: "Interaction Type"
        description: "Indicates if the REST API is getting provided or consumed in the current context"
        descriptionDetailed: "Specifies whether the REST API is provided (exposed by the system) or consumed (used by the system from an external source). This helps distinguish between APIs that the system exposes versus APIs that the system uses."
        type: "selection"
        required: false
        options:
          - key: "providing"
            displayName: "Providing"
            description: "The REST API is provided by the system"
          - key: "consuming"
            displayName: "Consuming"
            description: "The REST API is consumed by the system"
      - fieldName: "openapi-specification"
        displayName: "OpenAPI specification"
        description: "The OpenAPI specification of the REST API"
        descriptionDetailed: "The OpenAPI specification document that defines the REST API contract, including endpoints, request/response schemas, authentication, and other API details. This specification can be used for code generation, documentation, and API testing."
        type: "attachment-text"
        required: false
        textAttachmentFormat: "yaml"
        allowedAttachmentFileExtensions: ["yaml", "yml", "json"]

  - id: "implementation-rest-api-operation-properties"
    name: "REST API Operation Properties"
    description: "Properties for REST API operations"
    descriptionDetailed: "This property group contains properties specific to REST API Operation elements, including the interaction type (providing or consuming)."
    properties:
      - fieldName: "interaction-type"
        displayName: "Interaction Type"
        description: "Indicates if the REST API operation is getting provided or consumed in the current context"
        descriptionDetailed: "Specifies whether the REST API operation is provided (exposed by the system) or consumed (used by the system from an external source). This helps distinguish between operations that the system exposes versus operations that the system uses."
        type: "selection"
        required: false
        options:
          - key: "providing"
            displayName: "Providing"
            description: "The REST API operation is provided by the system"
          - key: "consuming"
            displayName: "Consuming"
            description: "The REST API operation is consumed by the system"

  - id: "implementation-soap-api-properties"
    name: "SOAP API Properties"
    description: "Properties for SOAP APIs"
    descriptionDetailed: "This property group contains properties specific to SOAP API elements, including the interaction type (providing or consuming) and WSDL specification."
    properties:
      - fieldName: "interaction-type"
        displayName: "Interaction Type"
        description: "Indicates if the SOAP API is getting provided or consumed in the current context"
        descriptionDetailed: "Specifies whether the SOAP API is provided (exposed by the system) or consumed (used by the system from an external source). This helps distinguish between APIs that the system exposes versus APIs that the system uses."
        type: "selection"
        required: false
        options:
          - key: "providing"
            displayName: "Providing"
            description: "The SOAP API is provided by the system"
          - key: "consuming"
            displayName: "Consuming"
            description: "The SOAP API is consumed by the system"
      - fieldName: "wsdl"
        displayName: "WSDL specification"
        description: "The WSDL specification of the SOAP API"
        descriptionDetailed: "The WSDL (Web Services Description Language) specification document that defines the SOAP API contract, including service operations, message formats, data types, and binding information. This specification can be used for code generation, service discovery, and API documentation."
        type: "attachment-text"
        required: false
        textAttachmentFormat: "xml"
        allowedAttachmentFileExtensions: ["wsdl", "xml"]

# Text Templates
textTemplates: []

# Validations
validations: []

# Guidelines
guidelines:
  - id: "domain-events-outbox-pattern"
    scope:
      elementTypes: ["implementation.message-publisher"]
    policy: "When implementing domain events that need to be published to external systems or message brokers, always use the outbox pattern to ensure transactional consistency. Domain events should be stored in the same database transaction as the aggregate state changes, then published asynchronously by a separate process. This prevents situations where the aggregate is updated but the event publication fails, or vice versa, which would lead to inconsistent state. The outbox pattern requires: (1) storing the event in an outbox table within the same transaction as the aggregate update, (2) a separate publisher process that reads from the outbox and publishes events to the message broker, (3) marking events as published after successful delivery. Never publish domain events directly from the aggregate transaction, as this creates a distributed transaction that can fail and cause data inconsistency."

  - id: "rest-api-naming-convention"
    scope:
      elementTypes: ["implementation.rest-api", "implementation.rest-api-operation"]
    policy: "When creating REST APIs and REST API operations, use clear, resource-oriented naming conventions. REST APIs should be named after the primary resource they manage (e.g., 'Customer API', 'Order API', 'Payment API'). REST API operations should follow RESTful conventions: use nouns for resources, use HTTP methods appropriately (GET for retrieval, POST for creation, PUT for full updates, PATCH for partial updates, DELETE for removal), and use plural nouns for collections. Endpoint paths should be hierarchical and reflect resource relationships (e.g., '/customers/{id}/orders' for orders belonging to a customer). Avoid verbs in URLs and use query parameters for filtering, sorting, and pagination."

  - id: "class-single-responsibility"
    scope:
      elementTypes: ["implementation.class"]
    policy: "When designing classes, follow the Single Responsibility Principle. Each class should have one reason to change - it should encapsulate a single concept or responsibility. If a class has multiple responsibilities, consider splitting it into multiple classes. Classes should be cohesive, meaning all their methods and properties should work together toward a single purpose. Avoid god classes that do too much. Use composition over inheritance when possible, and prefer small, focused classes over large, monolithic ones."

  - id: "message-idempotency"
    scope:
      elementTypes: ["implementation.message-listener"]
    policy: "When implementing message listeners that process messages from message brokers, always design handlers to be idempotent. Message brokers may deliver the same message multiple times due to network issues, retries, or broker behavior. Message handlers must be able to safely process the same message multiple times without causing side effects or data corruption. Use idempotency keys, check message processing status before processing, or design operations to be naturally idempotent. Log duplicate message attempts for monitoring and debugging purposes."

  - id: "database-transaction-boundaries"
    scope:
      elementTypes: ["implementation.db-table", "implementation.db-collection"]
    policy: "When designing database tables and collections, consider transaction boundaries and consistency requirements. Related data that must be updated atomically should be stored in the same database or use distributed transaction patterns. Avoid splitting data that requires consistency across multiple databases unless you have a clear strategy for handling eventual consistency. Use database transactions for operations that must be atomic, and design your data model to minimize the need for distributed transactions, which are complex and can fail."

