Skip to main content

Application Projector

Description​

A type of Event Handler specifically responsible for updating read models (Projections) based on Domain Events.

Definition Schema​

The definition for a application_projector component expects the following structure:

{
  "$defs": {
    "EventToHandleDTO": {
      "properties": {
        "event_name": {
          "title": "Event Name",
          "type": "string"
        },
        "event_module": {
          "title": "Event Module",
          "type": "string"
        },
        "handler_method_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Handler Method Name"
        }
      },
      "required": [
        "event_name",
        "event_module"
      ],
      "title": "EventToHandleDTO",
      "type": "object"
    }
  },
  "example": {
    "description": "Updates the order summary read model.",
    "events_to_handle": [
      {
        "event_module": "app_root_name.domain.ordering.events.order_created_event",
        "event_name": "OrderCreatedEvent",
        "handler_method_name": "_handle_order_created"
      },
      {
        "event_module": "app_root_name.domain.ordering.events.order_item_added_event",
        "event_name": "OrderItemAddedEvent"
      }
    ],
    "projection_id_value": "order_summary_v1",
    "projection_store_module_str": "castlecraft_engineer.abstractions.projection_store",
    "projection_store_type_str": "ProjectionStore[uuid.UUID]",
    "projector_name": "OrderSummaryProjector"
  },
  "properties": {
    "projector_name": {
      "description": "Name of the Projector class (e.g., 'OrderSummaryProjector')",
      "title": "Projector Name",
      "type": "string"
    },
    "projection_id_value": {
      "description": "The unique string ID for this projector (e.g., 'order_summary_projector_v1')",
      "title": "Projection Id Value",
      "type": "string"
    },
    "projection_store_type_str": {
      "description": "Type hint for the ProjectionStore (e.g., 'ProjectionStore[uuid.UUID]', 'OrderProjectionStore')",
      "title": "Projection Store Type Str",
      "type": "string"
    },
    "projection_store_module_str": {
      "description": "Module where the ProjectionStore interface/concrete class is defined (e.g., 'castlecraft_engineer.abstractions.projection_store', 'app_root_name.infrastructure.projection_stores')",
      "title": "Projection Store Module Str",
      "type": "string"
    },
    "events_to_handle": {
      "description": "List of events this projector should handle.",
      "items": {
        "$ref": "#/$defs/EventToHandleDTO"
      },
      "title": "Events To Handle",
      "type": "array"
    },
    "base_projector_module": {
      "default": "castlecraft_engineer.abstractions.projector",
      "description": "Module for the base Projector class.",
      "title": "Base Projector Module",
      "type": "string"
    },
    "base_projector_name": {
      "default": "Projector",
      "description": "Name of the base Projector class.",
      "title": "Base Projector Name",
      "type": "string"
    },
    "projection_abstractions_module": {
      "default": "castlecraft_engineer.abstractions.projection",
      "description": "Module for ProjectionId, ProjectionState.",
      "title": "Projection Abstractions Module",
      "type": "string"
    },
    "event_base_module": {
      "default": "castlecraft_engineer.abstractions.event",
      "description": "Module for the base Event class.",
      "title": "Event Base Module",
      "type": "string"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional description for the projector.",
      "title": "Description"
    }
  },
  "required": [
    "projector_name",
    "projection_id_value",
    "projection_store_type_str",
    "projection_store_module_str"
  ],
  "title": "ProjectorEngineInputDTO",
  "type": "object"
}

Naming and Location Conventions​

Class: PascalCase, typically ends with 'Projector'. File: ${application_projector_name}.py (based on ${application_projector_name}). Location: app/application/${bounded_ctx}/projectors. (Requires context: ['bounded_ctx'])

Example Definition​

{
  "projector_name": "OrderSummaryProjector",
  "projection_id_value": "order_summary_v1",
  "projection_store_type_str": "ProjectionStore[uuid.UUID]",
  "projection_store_module_str": "castlecraft_engineer.abstractions.projection_store",
  "events_to_handle": [
    {
      "event_name": "OrderCreatedEvent",
      "event_module": "app_root_name.domain.ordering.events.order_created_event",
      "handler_method_name": "_handle_order_created"
    },
    {
      "event_name": "OrderItemAddedEvent",
      "event_module": "app_root_name.domain.ordering.events.order_item_added_event"
    }
  ],
  "description": "Updates the order summary read model."
}