Skip to content
EventCatalog Compass

Tutorial

In this tutorial, we will build a small architecture model from scratch and see it visually.

You have two options to follow this tutorial:

  1. Open the EventCatalog Compass Playground
    • This will give you a blank canvas to work on.
  2. Use the EventCatalog VSCode Extension
    • You will need to install the plugin and create your first main.ec file.
    • You can run the EventCatalog: Open Preview command to see your model visually.

Creating your first model

In this example we will create a simple model of an order processing system.

  1. Create a visualizer

    The visualizer block is your canvas. Everything you want to see in the diagram goes inside it.

    • Start by creating a visualizer block.
    visualizer main {
      name "Order Processing"
    }

  2. Add a service

    A service is a runtime capability in your system, for example a microservice or application.

    • Add a service inside the visualizer block.
    visualizer main {
      name "Order Processing"
    

      service OrdersService {
        version 1.0.0
        name "Orders Service"
        summary "Handles order lifecycle"
      }
    }

  3. Publish an event from the service

    Services can send (publish) messages. These can be events, commands, or queries. These messages can be sent to a channel (e.g. Kafka, MQTT, HTTP, SQS, etc.).

    • Add a sends statement to the service to publish an event.
    • Add a channel to send the event to (this is optional).
    visualizer main {
      name "Order Processing"
    

      service OrdersService {
        version 1.0.0
        name "Orders Service"
        summary "Handles order lifecycle"
        sends event OrderCreated@1.0.0 to KafkaOrdersTopic
      }
    

      event OrderCreated {
        version 1.0.0
        name "Order Created"
        summary "Raised when an order is created"
      }
    

      channel KafkaOrdersTopic {
        version 1.0.0
        name "Kafka Orders Topic"
        summary "Primary channel for order events"
        address "orders.events"
        protocol "kafka"
      }
    }

  4. Consume messages

    Services can also receive (consume) messages. These can be events, commands, or queries. These messages can be received from a channel (e.g. Kafka, MQTT, HTTP, SQS, etc.).

    • Add a receives statement to consume a command.
    • This time we don’t specify a version and latest version is used.
    visualizer main {
      name "Order Processing"
    

      service OrdersService {
        version 1.0.0
        name "Orders Service"
        summary "Handles order lifecycle"
        sends event OrderCreated@1.0.0 to KafkaOrdersTopic
        receives command ProcessOrder
      }
    

      event OrderCreated {
        version 1.0.0
        name "Order Created"
        summary "Raised when an order is created"
      }
    

      channel KafkaOrdersTopic {
        version 1.0.0
        name "Kafka Orders Topic"
        summary "Primary channel for order events"
        address "orders.events"
        protocol "kafka"
      }
    

      command ProcessOrder {
        version 1.0.0
        name "Process Order"
        summary "Processes an order"
      }
    }

  5. Add more services

    Add as many services as you need. When multiple services produce or consume the same event through the same channel, the diagram connects them automatically.

    visualizer main {
      name "Order Processing"
    

      service OrdersService {
        version 1.0.0
        name "Orders Service"
        summary "Handles order lifecycle"
        sends event OrderCreated@1.0.0 to KafkaOrdersTopic
        receives command ProcessOrder
      }
    

      service PaymentService {
        version 1.0.0
        summary "Processes payments for orders"
        receives event OrderCreated from KafkaOrdersTopic
        sends event PaymentProcessed to KafkaOrdersTopic {
          version 1.0.0
          summary "Payment completed successfully"
        }
      }
    

      service InventoryService {
        version 1.0.0
        summary "Manages product stock levels"
        receives event OrderCreated from KafkaOrdersTopic
        sends event InventoryReserved {
          version 1.0.0
          summary "Stock reserved for an order"
        }
      }
    

      service NotificationService {
        version 1.0.0
        summary "Sends notifications to users"
        receives event OrderCreated from KafkaOrdersTopic
        receives event PaymentProcessed from KafkaOrdersTopic
      }
    

      event OrderCreated {
        version 1.0.0
        name "Order Created"
        summary "Raised when an order is created"
      }
    

      channel KafkaOrdersTopic {
        version 1.0.0
        name "Kafka Orders Topic"
        summary "Primary channel for order events"
        address "orders.events"
        protocol "kafka"
      }
    

      command ProcessOrder {
        version 1.0.0
        name "Process Order"
        summary "Processes an order"
      }
    }

  6. Wrap it in a domain

    Domains group related services together. Wrap your services inside a domain block to show ownership and boundaries.

    visualizer main {
      name "Order Processing"
    

      domain Orders {
        version 1.0.0
        summary "Everything related to order processing"
    

        service OrdersService {
          version 1.0.0
          name "Orders Service"
          summary "Handles order lifecycle"
          sends event OrderCreated@1.0.0 to KafkaOrdersTopic
          receives command ProcessOrder
        }
    

        service PaymentService {
          version 1.0.0
          summary "Processes payments for orders"
          receives event OrderCreated from KafkaOrdersTopic
          sends event PaymentProcessed to KafkaOrdersTopic {
            version 1.0.0
            summary "Payment completed successfully"
          }
        }
    

        service InventoryService {
          version 1.0.0
          summary "Manages product stock levels"
          receives event OrderCreated from KafkaOrdersTopic
          sends event InventoryReserved {
            version 1.0.0
            summary "Stock reserved for an order"
          }
        }
      }
    

      service NotificationService {
        version 1.0.0
        summary "Sends notifications to users"
        receives event OrderCreated from KafkaOrdersTopic
        receives event PaymentProcessed from KafkaOrdersTopic
      }
    

      event OrderCreated {
        version 1.0.0
        name "Order Created"
        summary "Raised when an order is created"
      }
    

      channel KafkaOrdersTopic {
        version 1.0.0
        name "Kafka Orders Topic"
        summary "Primary channel for order events"
        address "orders.events"
        protocol "kafka"
      }
    

      command ProcessOrder {
        version 1.0.0
        name "Process Order"
        summary "Processes an order"
      }
    }

  7. Next steps