🧠 Event-Driven Architect Agent Specification¶

🎯 Purpose¶

The Event-Driven Architect Agent is responsible for designing the asynchronous backbone of the ConnectSoft platform.
Its mission is to define, govern, and evolve the event-driven interactions that allow services, systems, and agents to:

Communicate through decoupled event flows
React to state changes and triggers autonomously
Scale horizontally via pub-sub topologies
Maintain observability, replayability, and traceability
Respect bounded context contracts and delivery guarantees

It converts domain and application-level events into governed, schema-based integration events that become the foundation of event choreography across the entire platform.

🧠 Strategic Role in the ConnectSoft AI Factory¶

flowchart TD
    DomainModeler --> EventDrivenArchitect
    ApplicationArchitect --> EventDrivenArchitect
    EventDrivenArchitect --> AdapterGenerator
    EventDrivenArchitect --> MicroserviceGenerator
    EventDrivenArchitect --> ObservabilityAgent

Hold "Alt" / "Option" to enable pan & zoom

Consumes semantic events emitted by aggregates or applications
Produces contracts, schema files, topic/queue topologies, and observability hooks
Enables autonomous orchestration, saga patterns, and integration with external systems

🧠 Core Objectives¶

Objective	Description
📢 Promote Semantic Events to Integration Events	Identify which domain events require propagation across services or systems
📜 Define Durable, Schema-Governed Event Contracts	Output JSON Schema, Avro, or protocol-neutral formats with versioning and validation
🔁 Design Pub/Sub Topologies	Map publisher → event → subscriber pipelines using transport-agnostic patterns
📊 Enable Observability	Ensure emitted events are traceable (e.g., `trace_id`, `event_source`, `correlation_id`)
🧩 Support Choreography and Saga Coordination	Tag long-running flows, distributed transitions, compensation actions

🔍 Without This Agent...¶

Services would emit inconsistent, unstructured, and non-traceable messages
Event subscribers could break when contracts evolve
Integration points would become fragile and manually governed
Event duplications, loss, or drift between contexts would increase
Testing and observability across event boundaries would be error-prone

✅ With This Agent...¶

Events are first-class architectural artifacts
Contracts are schema-valid, versioned, and observable
Topologies are modeled, validated, and published
Event flows support retries, deduplication, and QoS
Agents can subscribe and react reliably to service behaviors
Human teams can understand and debug inter-service flows

🗂️ Example Output¶

For a BillingService domain event InvoiceCreated:

Promote it to InvoiceCreatedIntegrationEvent
Generate invoice.created.v1.schema.json
Define publishing via billing-events/invoice.created
Document subscribers (e.g., CRMService, AccountingService)
Emit EventContractPublished event for downstream agents

🧭 Event-Driven Principles Embedded¶

🧱 Choreographed, not orchestrated
📜 Contracts over assumptions
🔁 Replayable and versioned
📈 Observable and testable
⛓️ Coupling via schemas, not code

🏛️ Scope of Influence¶

The Event-Driven Architect Agent governs the event layer across services — defining how events are:

Promoted from domain signals
Published across bounded contexts
Routed to subscribers (internal and external)
Traced, versioned, and observed
Governed for backward/forward compatibility

Its influence spans both design-time modeling and runtime topology orchestration.

📋 Primary Modeling Domains¶

Domain	Scope
📢 1. Event Classification	Defines different types of events that are crucial for the architecture, including their ownership and usage in the system.
🔄 2. Topology & Transport Design	Describes the design of the event-driven topology, including message routing, event transport layers, and quality of service.
📦 3. Event Contract Governance	Ensures that event contracts are well-defined, versioned, and compliant with standards, guaranteeing interoperability.
🚫 Not in Scope	Lists items that are outside the scope of this model, specifying their ownership and responsibility.

📢 1. Event Classification¶

Type	Description
Domain Events	Raised internally by aggregates (e.g., `InvoiceCreated`) — owned by Domain Modeler
Application Events	Emitted by use case handlers or services (e.g., `ReminderSent`) — owned by Application Architect
Integration Events	Promoted external-facing events with stable contracts (e.g., `InvoiceCreatedIntegrationEvent`) — owned by this agent
Command Events	Downstream-trigged actions, usually from workflows or sagas
Saga/Internal Orchestration Events	Used to coordinate long-running workflows within the platform (e.g., `PaymentValidated → InvoiceReleased`)

🔄 2. Topology & Transport Design¶

Layer	Description
Event Topics/Queues	Maps events to logical channels, e.g., `billing.invoice.created`
Event Subscribers	Maps services/agents to subscribed events
Message Routing Rules	Filters, transforms, correlation ID injection
Quality of Service (QoS)	Delivery guarantees (at-least-once, exactly-once, FIFO), retry/dlq policies
Broadcast vs Point-to-Point	Models fanout, targeted commands, saga chaining

📦 3. Event Contract Governance¶

Component	Description
Schema Definition	JSON Schema, Avro, or IDL for each promoted event
Versioning Policy	Semantic versioning of event contracts with compatibility annotations
Metadata Enforcement	Every event includes `event_id`, `timestamp`, `source`, `trace_id`, `correlation_id`, and `event_version`
Audit & Observability Hooks	Span IDs, emitter identity, payload hash

🚫 Not in Scope¶

Not Owned	Responsibility Of
Domain Event Emission Logic	Domain Modeler Agent
Application Service Triggers	Application Architect Agent
Infrastructure Bus Implementation	Adapter Generator Agent
Retry Pipelines & DLQ Consumers	Microservice Runtime Config
Event Replay Engine (if CQRS/EventSourcing)	Specialized Event Sourcing Agent (if active)

🔁 Influence Map¶

flowchart TD
    subgraph Domain Layer
        A1[DomainModeler Agent]
    end

    subgraph Application Layer
        A2[ApplicationArchitect Agent]
    end

    A1 --> B[EventDrivenArchitect Agent]
    A2 --> B

    B --> C[Adapter Generator]
    B --> D[Microservice Generator]
    B --> E[Platform Event Registry]
    B --> F[Observability Agent]

Hold "Alt" / "Option" to enable pan & zoom

📐 Inter-Bounded Context Flow¶

For cross-context communication, this agent defines:

Event producers
Subscribers
Contract schemas
Routing rules
Replay compatibility strategy
Observability points
Lifecycle governance

✅ Scope Summary¶

Area	Owned By Event-Driven Architect Agent
Promote domain/app events to integration events	✅
Define schemas, versions, metadata	✅
Configure pub/sub topology	✅
Emit traceable, observable messages	✅
Govern compatibility and evolution	✅
Model distributed coordination flows	✅
Implement retry/DLQ mechanics	❌ (delegated to runtime infra)

📋 Core Responsibilities¶

The Event-Driven Architect Agent defines, governs, and publishes semantic, decoupled, observable event flows
that connect bounded contexts, services, and external integrations across the ConnectSoft platform.

It transforms raw domain/application events into governed integration events and defines the entire event-driven interaction model.

📢 1. Event Discovery & Promotion¶

Task	Description
Discover Domain Events	Parse outputs from Domain Modeler Agent (`domain-events.json`)
Discover Application Events	Parse use cases with `emits_event:` markers in `use-cases.yaml`
Promote to Integration Events	Elevate semantically meaningful internal events to published messages
Tag Event Types	Classify as `domain`, `integration`, `command`, `workflow`, `external`

📜 2. Event Contract Design¶

Task	Description
Define Schema	Emit contract in JSON Schema or Avro (versioned)
Specify Metadata Fields	Enforce: `event_id`, `event_type`, `timestamp`, `source`, `trace_id`, `correlation_id`, `event_version`
Apply Validation Rules	Run schema validators + compatibility checkers
Track Breaking Changes	Emit warnings when contract evolution breaks subscribers

🔁 3. Topic and Topology Modeling¶

Task	Description
Define Topics	Assign logical topics to events (e.g., `billing.invoice.created`)
Configure Subscribers	Declare which services/agents react to each event
Configure Routing Policies	Include filter conditions, headers, message transforms
QoS Mapping	Annotate events with delivery class: `at-least-once`, `exactly-once`, `at-most-once`

📦 4. Event Flow Diagrams & Maps¶

Task	Description
Emit Event Flow Diagrams	Render Mermaid-style or PlantUML interaction maps
Map Cross-Service Dependencies	Track which contexts depend on each event
Mark Ownership	Who owns the contract vs who subscribes

📡 5. Observability and Replay Enablement¶

Task	Description
Inject Observability Fields	Require `trace_id`, `span_id`, `correlation_id`, `service_name`, etc.
Emit Span Mapping Templates	Suggest span start/end for emit/consume
Define Replay Capability	Annotate replay-safe vs transient events
Emit Message Hash for Audit	Optional payload hashing for signed audit chains

🛡️ 6. Governance & Lifecycle¶

Task	Description
Track Contract Versions	Emit changelogs and `EventContractUpdated`
Detect Schema Drift	Run diffs between promoted versions
Promote Retired Events	Mark deprecated events and subscribers
Enforce Naming Standards	e.g., kebab-case topics, PascalCase payload fields, suffix-based classification (`Event`, `Command`, `Notification`)

📤 7. Output Artifact Generation¶

Artifact	Purpose
`event-catalog.yaml`	Event → contract map, version, publisher, subscribers
`event-schema-*.json`	Schema file per integration event
`event-topology.yaml`	Topics, QoS, routing rules
`event-flow.mmd`	Sequence or pub-sub diagrams
`EventContractPublished`	Triggers downstream actions by Adapter Generator, Observability Agent, and CI/CD pipelines

✅ Summary Table of Responsibilities¶

Area	Owns
Integration event design	✅
Event contract schema + versioning	✅
Topic / subscriber / routing modeling	✅
Pub-sub flow rendering + traceability	✅
Emission observability and replay rules	✅
Runtime implementation or message queue infra	❌ (delegated to runtime / Adapter Generator)

📥 Core Inputs¶

The Event-Driven Architect Agent consumes structured upstream artifacts that describe:

Events raised by the domain model or application logic
Use case triggers and emissions
API operations indicating asynchronous behavior
Non-functional requirements influencing delivery modes (e.g., durability, QoS, observability)
Bounded context contracts that guide event ownership and segregation

These inputs allow it to build a complete, validated, and traceable event interaction layer.

📋 Required Inputs¶

Artifact	Source Agent	Description
`domain-events.json`	Domain Modeler Agent	Declared internal events (with name, emitter, payload)
`use-cases.yaml`	Application Architect Agent	Use case emission mappings (e.g., `emits_event: InvoiceCreated`)
`application-architecture.md`	Application Architect Agent	Overview of services, ports, and internal behavior flow
`event-catalog.yaml` (optional pre-existing)	Event Registry	Registry of prior published events for compatibility checks
`nfr.yaml`	Solution Architect Agent	Requirements that affect delivery (e.g., must be auditable, idempotent)
`trace_id`, `project_id`, `bounded_context`, `service_name`	System Metadata	Required for traceability tagging

🧩 Key Input Fields and Mapping¶

🔷 From `domain-events.json`¶

Field	Used For
`event_name`	Integration event promotion candidate
`emitted_by`	Used to track ownership and service
`payload_fields`	Contract base for schema
`correlation_id`	Ensures flow-level observability
`is_externalizable`	If true, promote to integration event

🔷 From `use-cases.yaml`¶

Field	Used For
`emits_event`	Event-to-use-case mapping
`cross_cutting: tracing`	Tracing span injection template
`output_ports`	Subscriber or event consumer mapping

🔷 From `nfr.yaml`¶

Field	Use
`requires_exactly_once_delivery: true`	Annotate QoS in topology
`audit_required: true`	Emit hash + compliance hint
`pii_sensitive: true`	Mask payload fields in schema or mark accordingly

🔷 From `application-architecture.md`¶

Section	Use
`Application Services`	Event ownership mapping
`Cross-Cutting Concerns`	Observability + retry pattern injection
`Ports & Adapters`	Subscribe/publish contract interface mapping

📄 Example Aggregated Input View (Simplified YAML)¶

bounded_context: Billing
service_name: BillingService
trace_id: trace-billing-evt-9332
domain_events:
  - name: InvoiceCreated
    emitted_by: InvoiceAggregate
    payload_fields: [InvoiceId, Amount, DueDate]
    is_externalizable: true
use_cases:
  - name: CreateInvoice
    emits_event: InvoiceCreated
    output_ports: [IEventBus]
nfr:
  requires_exactly_once_delivery: true
  audit_required: true

🧪 Input Validation Rules¶

Rule	Enforced
Must receive at least one event from domain or application	✅
Each event must define `name`, `payload`, and emitter	✅
If promoting, `is_externalizable: true` is required	✅
Traceability metadata (`trace_id`, `project_id`) required	✅
Payload fields must not contain raw DTOs	✅

🧠 Semantic Memory Use (Optional)¶

Match existing events: "InvoiceCreated" → reuse known schema
Find topic patterns for bounded context: "Billing" → topic prefix billing.*
Suggest standard metadata structure: trace_id, service, timestamp, payload_version

📤 Core Outputs¶

The Event-Driven Architect Agent generates a structured set of event-driven artifacts that define:

What events are published and subscribed to
Which services own or consume them
How the events are structured (schemas)
What topics or channels they use
How observability, versioning, and QoS are enforced

These outputs form the canonical source of truth for event-driven flows in the ConnectSoft platform.

📘 1. `event-catalog.yaml`¶

Format	YAML
Purpose	An index of all modeled integration events, their publishers, subscribers, and versions. This file organizes the event structure and provides traceability for each event within the system.

Example¶

events:
  - name: InvoiceCreated
    version: 1.0.0
    type: integration
    owned_by: BillingService
    published_on: billing.invoice.created
    schema_ref: ./schemas/invoice-created.v1.json
    subscribers:
      - CRMService
      - AccountingService

Explanation:

name: The name of the event (e.g., InvoiceCreated).
version: The version of the event contract (e.g., 1.0.0), ensuring backward compatibility and allowing version tracking.
type: Specifies the event type (e.g., integration), indicating whether the event is used internally or externally.
owned_by: The service that owns and publishes the event (e.g., BillingService).
published_on: The topic or channel on which the event is published (e.g., billing.invoice.created).
schema_ref: A reference to the event schema file that defines the event structure (e.g., ./schemas/invoice-created.v1.json).
subscribers: A list of services that subscribe to the event and react accordingly (e.g., CRMService, AccountingService).

✅ Used by: Adapter Generator, Microservice Generator, and Event Registry to wire up the event-driven architecture and ensure consistent event handling.

📜 2. `event-schema-*.json`¶

Format	JSON Schema or Avro
Purpose	Defines structured, versioned event payload contracts with metadata and validation rules. These schemas ensure data integrity and provide a standard for event consumption and validation.

Example¶

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "title": "InvoiceCreated",
  "type": "object",
  "properties": {
    "invoiceId": { "type": "string" },
    "amount": { "type": "number" },
    "dueDate": { "type": "string", "format": "date" },
    "traceId": { "type": "string" },
    "eventVersion": { "type": "string" }
  },
  "required": ["invoiceId", "amount", "dueDate", "traceId", "eventVersion"]
}

Explanation:

$schema: The schema version being used (e.g., JSON Schema Draft 07).
title: The name of the event (e.g., InvoiceCreated).
type: Specifies that the event payload is of type object.
properties: The fields in the event payload, including their data types and any special formats (e.g., date for dueDate).
- invoiceId: A string representing the unique invoice identifier.
- amount: A number representing the invoice amount.
- dueDate: A date indicating the due date of the invoice.
- traceId: A string representing the trace identifier for tracking the event.
- eventVersion: A string representing the version of the event schema.
required: Lists the mandatory fields that must be included in the event payload to ensure proper validation.

✅ Output schema must be validatable and versioned (e.g., v1, v1.1) to ensure backward compatibility and proper event contract evolution.

🧭 3. `event-topology.yaml`¶

topics:
  - name: billing.invoice.created
    qos: exactly_once
    publisher: BillingService
    subscribers:
      - name: CRMService
        retry_policy: exponential_backoff
        max_attempts: 5
        filters:
          - field: "amount"
            condition: "> 1000"

✅ Used by infrastructure layer (e.g., Adapter Generator) to set up queues, topics, subscriptions

🗺️ 4. `event-flow.mmd` (Mermaid Diagram)¶

flowchart LR
    BillingService -->|InvoiceCreated| CRMService
    BillingService -->|InvoiceCreated| AccountingService

Hold "Alt" / "Option" to enable pan & zoom

✅ Supports rendering in ConnectSoft documentation UI or exported in PNG/SVG

📦 5. `event-contract-metadata.yaml`¶

trace_id: "trace-evt-bill-8442"
project_id: "connectsoft-saas"
bounded_context: "Billing"
agent_version: "1.1.0"
generated_events: 3
promoted_from: [domain-events.json, use-cases.yaml]
compliance_flags:
  - audit_required
  - pii_fields_masked
  - qos: exactly_once

📨 6. Emitted Event: `EventContractPublished`¶

{
  "event": "EventContractPublished",
  "eventName": "InvoiceCreated",
  "version": "1.0.0",
  "schemaUrl": "https://schemas.connectsoft.dev/events/invoice-created.v1.json",
  "catalogUrl": "https://.../event-catalog.yaml",
  "traceId": "trace-evt-bill-8442",
  "timestamp": "2025-05-01T21:00:00Z"
}

📑 Optional Outputs¶

Artifact	Use
`event-changelog.md`	Markdown spec of contract versions and change diffs
`event-contract-compatibility-report.json`	Flags breaking changes between v1 and v2 for validation pipelines
`event-field-audit-map.yaml`	Identifies PII fields or masking requirements per schema

✅ Output Validation Criteria¶

Output	Rule
Catalog includes all published events	✅
Every promoted event has a versioned schema	✅
Topology includes QoS and retry policies	✅
Event diagram includes producers/subscribers	✅
Event contract metadata includes traceability and compliance hints	✅

📚 Knowledge Base Overview¶

The Event-Driven Architect Agent leverages a structured, curated, and versioned knowledge base to:

Reuse proven event patterns (integration, workflow, command)
Enforce standards and naming conventions
Prevent known event-driven anti-patterns
Suggest best practices for schema evolution, QoS, and observability
Promote governed reuse across bounded contexts

It integrates both static templates and semantic memory for similarity-based event design and pattern injection.

📘 1. Event Design Pattern Repository¶

Pattern Type	Examples
Integration Event	`InvoiceCreated`, `UserDeactivated`, `ShipmentDelivered`
→ Reusable schemas, routing strategies, common subscriber patterns
Workflow Event	`StepCompleted`, `ApprovalRequested`, `SagaTimeout`
→ Used in multi-step processes or compensation flows
Command Event	`SendNotificationCommand`, `RecalculateScoreCommand`
→ Often one-to-one and require idempotent processing
Domain Forwarding	`DomainEvent → IntegrationEvent` mapping policies
Event Correlation	Pattern for using `correlation_id`, `trace_id`, `cause_event_id` across flows

🔁 2. Schema Snippet Library¶

Type	Details
Reusable Metadata Fragments	`event_id`, `timestamp`, `event_version`, `producer_service`, `trace_id`, etc.
Payload Reuse	Common object fragments (e.g., `Money`, `Address`, `ContactInfo`) for embedding
Enforced Field Constraints	Required fields, naming rules, PII masking annotations (`sensitive: true`)

These are included automatically during schema generation based on reuse confidence.

🧠 3. Semantic Memory Retrieval¶

🔍 Examples¶

Query	Result
`"InvoiceCreated"`	Matching v1 event schema, topic `billing.invoice.created`, subscribers list
`"SubscriptionCancelled"`	Returns schema + Avro version + changelog note about `reasonCode` deprecation
`"OrderCreated"` → `"ShipmentStarted"`	Suggests event correlation structure: `orderId`, `shipmentId`, `parent_trace_id`

Metadata Included:¶

pattern_confidence_score
source_trace_id
governance_verified: true
schema_version, retired: false

⚠️ 4. Anti-Pattern Guard Rules¶

Anti-Pattern	Rejection Logic
❌ Event with DTO structure as payload	Blocks and replaces with explicit contract mapping
❌ Events without version field	Appends `event_version` and emits warning
❌ Flat events with too many fields (>15)	Suggests payload segmentation or compression
❌ Hard-coded retry logic in subscribers	Flags and redirects to subscriber QoS policies in topology
❌ Reused field names without disambiguation	Emits validation errors with prefix suggestions

Violations are logged via EventPatternValidatorSkill.

📜 5. Naming and Topic Structure Rules¶

Rule	Example
Topics must be kebab-case	✅ `billing.invoice.created`
Events must be PascalCase	✅ `InvoiceCreatedEvent`
Topics = `boundedContext.entity.action`	Pattern: `crm.user.deactivated`, `billing.invoice.created`
Event filename = `event-name.vX.Y.schema.json`	✅ `invoice-created.v1.0.json`
Field naming = camelCase	✅ `dueDate`, `invoiceId`, `paymentMethod`

These conventions are injected by skills like SchemaNameNormalizerSkill, TopicConventionEnforcerSkill.

🔄 Governance Features¶

Feature	Enforcement
Version history for every event	✅ `event-changelog.md` generated per contract
Reuse logged with origin trace	✅ memory-enhanced reuse journal
Compatibility scores between event versions	✅ emitted via `event-contract-compatibility-report.json`
PII detection in payloads	✅ triggers redaction tag or masking instruction

🧠 Knowledge Injection Diagram¶

flowchart TD
    A[Receive Domain + App Events] --> B[Query Semantic Memory]
    B --> C[Inject Event Pattern]
    B --> D[Inject Schema Fragment]
    C --> E[Run Pattern Validator]
    D --> F[Assemble Schema + Contract]

Hold "Alt" / "Option" to enable pan & zoom

✅ Benefits of Knowledge-Driven Design¶

Outcome	Benefit
🎯 Consistent and governed event contracts	✅
🔁 Reuse of proven flows and schemas	✅
🔐 Security and observability fields standardized	✅
📊 Easier platform-wide analytics of event lifecycles	✅
🔎 Human and agent visibility via changelogs and diagrams	✅

🔄 Execution Process Overview¶

The Event-Driven Architect Agent follows a structured, observable, and retryable process to:

Discover semantic events
Promote them to integration-level contracts
Define schemas, topologies, and routing rules
Output traceable artifacts used by other agents

This pipeline ensures that ConnectSoft’s event-driven flows are standardized, schema-governed, and compatible with platform-wide observability.

📋 Step-by-Step Process Flow¶

Phase	Description
1️⃣ Input Validation & Semantic Retrieval	- Confirm presence of key parameters: `trace_id`, `service_name`, `bounded_context`, and inputs such as events, use cases, and NFRs. - Pull related schema fragments, topic conventions, and historical events from semantic memory for context. - Normalize naming and field casing for consistency across the system.
2️⃣ Event Classification	- Classify events into categories: - `domain`, `integration`, `command`, `workflow`, `external` events. - Determine which events are promotable based on: - `is_externalizable: true` flag - Use case emission - Cross-context dependency mapping to understand how events will be used and propagated.
3️⃣ Schema Generation	- For each integration-level event, define: - JSON Schema or Avro schema structure for the event payload. - Inject metadata such as `event_id`, `timestamp`, `trace_id`, etc., to ensure traceability. - Link `emitted_by`, `service_name`, and `payload_version` for event versioning and ownership tracking.
4️⃣ Topic & Topology Design	- Map each event to a topic (e.g., `billing.invoice.created`) for easier identification and handling. - Assign QoS (Quality of Service) policies (e.g., `exactly_once`, `at_least_once`) to ensure reliable delivery. - Configure subscribers, including: - Retry policies - Filtering rules - Optional dead-letter handling for unprocessed messages - Correlation or causation linkage for workflows that need to trace event dependencies.
5️⃣ Contract Validation & Compatibility	- Run schema validators and perform backward/forward compatibility checks to ensure consistent event contracts across versions. - Emit `event-contract-compatibility-report.json` for tracking compatibility. - Detect breaking changes and flag them via governance warnings, ensuring compliance with the event versioning strategy.
6️⃣ Artifact Generation	- Emit artifacts including: - `event-catalog.yaml` - `event-schema-*.json` - `event-topology.yaml` - `event-flow.mmd` - `event-contract-metadata.yaml` to document the event structure and governance metadata.
7️⃣ Event Publication	- Emit the `EventContractPublished` event in JSON format to announce that event contracts are finalized and published. - Notify downstream agents: - Adapter Generator Agent for event bus wiring - Observability Agent for monitoring - Contract governance dashboards for tracking. - Optionally sync with external registry (e.g., AsyncAPI registry, schema registry) for external documentation and usage.

1️⃣ Input Validation & Semantic Retrieval¶

Confirm trace_id, service_name, bounded_context, and inputs (events, use cases, NFRs)
Pull related schema fragments, topic conventions, and historical events from semantic memory
Normalize naming and field casing

2️⃣ Event Classification¶

Classify events as:
- domain, integration, command, workflow, external
Determine which events are promotable based on:
- is_externalizable: true flag
- Use case emission
- Cross-context dependency mapping

3️⃣ Schema Generation¶

For each integration-level event:
- Define JSON Schema or Avro schema structure
- Inject metadata (event_id, timestamp, trace_id, etc.)
- Link emitted_by, service_name, and payload_version

4️⃣ Topic & Topology Design¶

Map each event to a topic (e.g., billing.invoice.created)
Assign QoS policies (e.g., exactly_once, at_least_once)
Configure subscribers, including:
- Retry policies
- Filtering rules
- Optional dead-letter handling
- Correlation or causation linkage for workflows

5️⃣ Contract Validation & Compatibility¶

Run schema validators and backward/forward compatibility checks
Emit event-contract-compatibility-report.json
Detect breaking changes and flag via governance warnings

6️⃣ Artifact Generation¶

Emit:
- event-catalog.yaml
- event-schema-*.json
- event-topology.yaml
- event-flow.mmd
- event-contract-metadata.yaml

7️⃣ Event Publication¶

Emit EventContractPublished (JSON)
Notify:
- Adapter Generator Agent
- Observability Agent
- Contract governance dashboards
Optionally sync with external registry (e.g., AsyncAPI registry, schema registry)

🔁 Retry and Recovery¶

Phase	Retry Trigger	Action
Schema fails validation	Missing required field	Auto-patch via `SchemaFixerSkill` to add or correct missing fields in the schema.
Topic conflict	Topic name already exists in registry	Retry with a suffix or scope prefix to ensure unique topic names.
Version collision	Same event promoted with incompatible structure	Trigger changelog and suggest a version bump to resolve conflicts in event schema changes.

📈 OpenTelemetry Spans¶

Span	Description
`event.discovery.duration`	Time taken to parse and classify events during the discovery phase.
`schema.generation.duration`	Time required to construct the event schema for each event.
`topology.build.duration`	Time taken to map topics and subscribers, and establish event routing rules.
`event.publish.status`	Success or failure status of event output emission, tracking if the event was successfully published.

All spans include: trace_id, event_name, agent_version, and reuse_score for traceability and monitoring.

🧠 Process Flow Diagram (High-Level)¶

flowchart TD
    A[Start Session] --> B[Validate Inputs]
    B --> C[Discover Events]
    C --> D[Classify + Promote]
    D --> E[Generate Schema + Metadata]
    E --> F[Map Topics + Subscribers]
    F --> G[Run Validators]
    G --> H[Assemble Artifacts]
    H --> I[Emit EventContractPublished]

Hold "Alt" / "Option" to enable pan & zoom

🛠️ Semantic Kernel Skills Overview¶

The Event-Driven Architect Agent uses a modular, skill-driven architecture powered by Semantic Kernel (C#).
Each skill encapsulates a single responsibility and can be composed, retried, or validated independently.

All skills are observable, schema-aware, and trace-linked, ensuring they can integrate cleanly into the ConnectSoft AI Factory pipeline.

📋 Key Skills Used¶

📥 1. Input & Discovery Skills¶

Skill	Description
`InputValidatorSkill`	Ensures trace_id, project_id, domain-events, and use-cases are present and valid
`EventDiscoverySkill`	Aggregates candidate events from domain + application layers
`PromotableEventClassifierSkill`	Determines which events should be elevated to integration status

📜 2. Schema & Contract Modeling¶

Skill	Description
`SchemaBuilderSkill`	Generates JSON Schema / Avro contracts with metadata and payload definitions
`SchemaNormalizerSkill`	Injects standard metadata fields (`event_id`, `timestamp`, `trace_id`, `event_version`)
`SchemaCompatibilityCheckerSkill`	Compares new schema versions with prior versions and flags breaking changes

📡 3. Topology & Routing Design¶

Skill	Description
`TopicMapperSkill`	Assigns event → topic using naming convention and bounded context prefix
`SubscriberConfiguratorSkill`	Maps known or implied consumers of the event
`QoSPolicyAssignerSkill`	Annotates delivery type (`at-least-once`, `exactly-once`), retry and DLQ policies
`FilterRoutingPlannerSkill`	Adds conditional filters for event routing (e.g., `amount > 1000`)

📈 4. Observability & Metadata¶

Skill	Description
`TelemetryInjectorSkill`	Adds span, trace, and correlation ID fields to schema and catalog
`EventAuditHasherSkill`	Computes payload hash for audit trail and compliance tagging
`SpanTemplateEmitterSkill`	Suggests span boundaries for emit/consume pairs per event

🧩 5. Output Assembly & Publishing¶

Skill	Description
`EventCatalogAssemblerSkill`	Generates `event-catalog.yaml` with schema refs and subscribers
`SchemaFileWriterSkill`	Emits `.json` schema files and changelogs
`TopologyMapBuilderSkill`	Constructs `event-topology.yaml` including all channel and subscriber info
`DiagramGeneratorSkill`	Outputs `event-flow.mmd` diagrams
`EventPublisherSkill`	Emits `EventContractPublished` with URLs, trace, and version info

🔁 6. Retry/Validation Skills¶

Skill	Description
`ContractSchemaValidatorSkill`	Validates final JSON schema structure
`AntiPatternCheckerSkill`	Detects malformed payloads, DTO references, or missing metadata
`ConflictResolutionSkill`	Resolves topic or schema name conflicts via versioning or prefixing
`SchemaFixerSkill`	Auto-corrects minor schema issues (e.g., missing required fields or type mismatches)

🧠 Skill Chain Overview¶

flowchart TD
    A[EventDiscoverySkill] --> B[PromotableEventClassifierSkill]
    B --> C[SchemaBuilderSkill]
    C --> D[SchemaCompatibilityCheckerSkill]
    D --> E[TopicMapperSkill]
    E --> F[SubscriberConfiguratorSkill]
    F --> G[QoSPolicyAssignerSkill]
    G --> H[EventCatalogAssemblerSkill]
    H --> I[EventPublisherSkill]

Hold "Alt" / "Option" to enable pan & zoom

🔁 Retry-Oriented Skills¶

Skill	Common Retry Trigger
`SchemaBuilderSkill`	Missing metadata fields → fix + retry
`TopicMapperSkill`	Name conflict in registry → suffix or namespace retry
`CompatibilityCheckerSkill`	Breaking change → suggest `vNext` upgrade
`SubscriberConfiguratorSkill`	Unknown service reference → retry with external service catalog enrichment

📈 Observability in Each Skill¶

Each skill emits: span_name, duration_ms, status, trace_id, retry_count
Skills are wrapped in ExecutionTracerSkill for OpenTelemetry compatibility

✅ Benefits of Skill-Oriented Modeling¶

Feature	Benefit
Modular execution	Partial modeling and pipeline reuse
Retry-safe	Fine-grained error handling and recovery
Observable	Per-skill metrics and span injection
Traceable	Each artifact is linked to skill origin + trace_id
Governance-aware	Anti-pattern rejection and version enforcement per skill

🛠️ Core Technologies and Tools¶

The Event-Driven Architect Agent is built to be transport-agnostic, schema-driven, and fully integrated with the ConnectSoft AI Software Factory ecosystem.

It leverages cloud-native, agent-compatible, and scalable tooling to model, validate, emit, and register events that can be consumed by services, agents, and external systems.

📋 Key Technologies and Roles¶

🧠 1. Semantic Kernel & Agent Framework¶

Component	Role
Semantic Kernel (.NET)	Orchestrates skill execution, prompt flow, retry logic
Azure OpenAI (GPT-4)	Powers event classification, naming, compatibility matching
ConnectSoft SkillPack: EventArchitecture	Prebuilt skill library for schema generation, topic mapping, and contract publishing

📜 2. Schema Definition and Contract Modeling¶

Tool	Role
JSON Schema (Draft 07+)	Primary contract format for integration events
Avro / AsyncAPI (optional)	Supported for specific use cases or external system compatibility
ConnectSoft Schema Validator	Ensures generated schemas conform to structural and semantic rules
*`event-schema-.json`**	Versioned file output for each integration event

📡 3. Transport-Agnostic Topology Modeling¶

System	Role
Azure Service Bus	Topic/subscription topology (ConnectSoft standard)
Apache Kafka (pluggable)	Alternative for batch/stream-heavy workloads
MassTransit (for .NET)	Internal pub/sub abstraction for message handling in services
EventGrid / SNS	Optional external pub/sub bridge for cross-platform integration

All are modeled abstractly using event-topology.yaml and resolved by the Adapter Generator Agent.

📈 4. Observability & Traceability¶

Tool	Role
OpenTelemetry SDK (.NET)	Span emission, event mapping, delivery tracing
Application Insights / Prometheus	Storage of span data and telemetry metrics
ConnectSoft Observability Agent	Subscribes to `EventContractPublished` and wires telemetry automatically
Span Template Output	Provided to downstream services and agents to implement emit/consume tracing

📦 5. Artifact and Contract Publishing¶

Component	Role
Artifact Storage API	Stores schemas, catalogs, metadata, diagrams, changelogs
ConnectSoft Event Registry	Registers new contracts, versions, and compatibility metadata
Event Bus (Azure Event Grid)	Publishes `EventContractPublished` and `ContractUpdated` notifications
AsyncAPI UI (optional)	Human-browsable documentation of async APIs and contracts

📑 6. Versioning and Governance¶

Component	Role
Schema Changelog Engine	Diffs new vs old contract versions and emits changelogs
Compatibility Checker	Tags breaking changes and emits alerts if existing subscribers are affected
Governance Dashboard	Displays compliance status, PII warnings, QoS tags, and topic routing graphs

✅ Supported Output Formats¶

Artifact	Format
Event Catalog	`event-catalog.yaml`
Schema Files	`.json` (JSON Schema Draft 7)
Topology Map	`event-topology.yaml`
Flow Diagrams	`event-flow.mmd` (Mermaid)
Metadata	`event-contract-metadata.yaml`
Changelog (optional)	`event-changelog.md`
Compatibility Report	`event-contract-compatibility-report.json`

⚡ Agent Infrastructure Compatibility¶

Environment	Ready
Azure DevOps Pipelines	✅ Build + publish artifacts + sync with Event Registry
Azure Service Bus	✅ Topic/subscription topology export supported
CI/CD Event Contracts Integration	✅ GitOps-ready
Cross-Bounded Context Messaging	✅ Topology + schema supports it
Adapter Generator Agent	✅ Consumes topology, contracts, QoS rules
External Systems (Kafka, RabbitMQ, etc.)	⚠️ Supported with adapter pattern; requires external plugin agents

📜 System Prompt (Bootstrapping Instruction)¶

The System Prompt defines the core mission, constraints, and generation policies that the Event-Driven Architect Agent follows when instantiated.

This prompt ensures that every modeling session adheres to ConnectSoft’s event-driven architecture principles, produces standardized artifacts, and interoperates reliably with all downstream agents and runtime services.

✅ Full System Prompt Definition (Plain Text)¶

You are the **Event-Driven Architect Agent** in the ConnectSoft AI Software Factory.

Your responsibility is to convert all relevant domain and application-level events  
into formally defined, versioned, and traceable **integration events**.

You must ensure that all events are schema-governed, semantically named,  
transport-agnostic, and observability-ready.

---

## You must:

1. Parse inputs from the Domain Modeler and Application Architect agents:
   - domain-events.json
   - use-cases.yaml
   - application-architecture.md
   - nfr.yaml

2. Promote only appropriate events to **integration-level status** using these rules:
   - If `is_externalizable = true` → promote
   - If the event crosses a bounded context → promote
   - If the event has subscribers in other services → promote

3. For each promoted event:
   - Define a schema in **JSON Schema (Draft 07)** or **Avro**
   - Include metadata: `event_id`, `timestamp`, `trace_id`, `event_version`, `producer_service`
   - Ensure the schema passes the ConnectSoft EventContract schema validator

4. Assign a logical **topic** for the event using:
   - `boundedContext.entity.action` format
   - kebab-case topic naming
   - e.g., `billing.invoice.created`

5. Define **topology and routing**:
   - Assign QoS: `at-least-once`, `exactly-once`, or `best-effort`
   - Configure subscribers, retry policies, and DLQ routing rules
   - Include optional filters or payload selectors

6. Emit the following outputs:
   - `event-catalog.yaml`
   - `event-schema-*.json`
   - `event-topology.yaml`
   - `event-flow.mmd`
   - `event-contract-metadata.yaml`
   - Optional: `event-changelog.md`, `event-compatibility-report.json`

7. Emit an `EventContractPublished` JSON event to notify downstream agents:
   - Adapter Generator Agent
   - Observability Agent
   - Governance Agent
   - CI/CD pipeline orchestrators

---

## Rules & Constraints

- All promoted events must be versioned (`event_version: "1.0.0"`)
- All schemas must include core metadata fields
- No raw DTOs are allowed in event payloads
- Events must be observable (emit `trace_id`, `correlation_id`, `producer_service`)
- All topic names must be unique within the project

---

## Traceability

Every output file and emitted event must include:
- `trace_id`
- `project_id`
- `bounded_context`
- `service_name`
- `agent_version`
- `pattern_reuse` (if applicable)

---

## Governance

You must validate:
- Event schema compatibility with prior versions
- Duplicate event names or topic collisions
- PII fields in payloads, and annotate them
- Breaking changes in required fields

If violations are found, emit warnings and retry with corrections or escalate to governance dashboard.

🔐 Purpose of the Prompt¶

This system prompt ensures that the Event-Driven Architect Agent:

Produces fully governed, cross-context-safe, and CI-compatible event contracts
Aligns event naming, formatting, and delivery with platform-wide policies
Enables plug-and-play messaging between ConnectSoft microservices and external consumers
Supports observability-first delivery for tracing and SLA enforcement

📥 Input Prompt Template¶

The Event-Driven Architect Agent receives a structured YAML prompt to initiate the design and promotion of integration event contracts, topologies, and schemas.

This prompt aligns with upstream architecture workflows and provides all required artifacts, trace metadata, and configuration flags.

✅ Full Input Prompt (YAML Format)¶

assignment: "design-event-architecture"

project:
  project_id: "connectsoft-saas"
  trace_id: "evt-trace-29341"
  bounded_context: "Billing"
  service_name: "BillingService"
  agent_version: "1.1.0"

inputs:
  domain_events_url: "https://artifacts.connectsoft.dev/events/domain-events.json"
  use_cases_url: "https://artifacts.connectsoft.dev/billing/use-cases.yaml"
  application_architecture_url: "https://artifacts.connectsoft.dev/billing/application-architecture.md"
  nfr_url: "https://artifacts.connectsoft.dev/billing/nfr.yaml"
  glossary_url: "https://artifacts.connectsoft.dev/glossary/billing.yaml"  # optional

settings:
  output_format: [yaml, json, mermaid]
  schema_format: "json-schema"
  promote_events: true
  check_version_compatibility: true
  include_diagrams: true
  topology_modeling: true
  observability_fields_required: true

🧩 Field Breakdown¶

📁 `project`¶

Field	Description
`trace_id`	Enables full traceability for spans, schemas, and contracts
`project_id`	The solution namespace
`bounded_context`	Context owner of the emitted events
`service_name`	Source of the events
`agent_version`	Used for audit and reproducibility tagging

📂 `inputs`¶

Field	Description
`domain_events_url`	JSON file containing domain-layer events with names, payloads, emitters
`use_cases_url`	YAML structure that includes `emits_event:` annotations
`application_architecture_url`	Application services, ports, observability hints
`nfr_url`	Non-functional requirements (e.g., audit, delivery guarantees, compliance)
`glossary_url`	Optional — maps terms to known event families or context-wide naming hints

⚙️ `settings`¶

Field	Description
`schema_format`	Typically `"json-schema"` or `"avro"`
`promote_events`	If false, agent only validates and documents existing ones
`check_version_compatibility`	Enables changelog and compatibility diffing
`include_diagrams`	Whether to emit `event-flow.mmd` for documentation
`topology_modeling`	Enables subscriber, retry, and routing policy mapping
`observability_fields_required`	Forces injection of `trace_id`, `event_id`, etc.

🧪 Input Validation Checklist¶

Rule	Enforced
`project_id`, `trace_id`, `bounded_context`, `service_name` must be present	✅
At least one of `domain_events_url` or `use_cases_url` must be valid	✅
URLs must return schema-compliant documents	✅
If `promote_events: true`, must receive `is_externalizable: true` flags or inferred context boundaries	✅

🔍 Minimal Example¶

assignment: design-event-architecture
project:
  trace_id: evt-trace-1248
  bounded_context: Payments
  service_name: PaymentService

inputs:
  domain_events_url: https://.../domain-events.json
  use_cases_url: https://.../use-cases.yaml

settings:
  promote_events: true

🔁 Interoperability Notes¶

This prompt is compatible with MKDocs trace metadata, allowing contract documentation embedding
Consumed and referenced by:
- 🧱 Application Architect Agent
- 🧪 Test Generator Agent
- ⚙️ Adapter Generator Agent
- 📈 Observability Agent
- 🚀 CI/CD Pipelines

📤 Output Expectations¶

The Event-Driven Architect Agent emits a complete, validated, and traceable set of artifacts describing the event-driven topology of a ConnectSoft microservice or bounded context.

These outputs are used by:

💡 Adapter Generator Agent to create publishers/subscribers
📊 Observability Agent to wire spans and telemetry
🧪 Test Generator Agent to simulate event flows
📜 Governance Dashboards to manage versioning and compliance

📘 1. `event-catalog.yaml`¶

events:
  - name: InvoiceCreated
    version: "1.0.0"
    owned_by: BillingService
    type: integration
    topic: billing.invoice.created
    schema_ref: ./schemas/invoice-created.v1.json
    subscribers:
      - name: CRMService
        delivery: at-least-once
        filter: amount > 1000

✅ Downstream agents use this as their primary input map

📜 2. `event-schema-*.json`¶

Format	JSON Schema Draft 07
Purpose	Defines the contract structure for each event in a machine-readable and CI-validatable format. Ensures consistency and validity for automated systems.
Fields Required	The following fields are required in the event schema: - `event_id`: A unique identifier for the event. - `timestamp`: The time at which the event was emitted, formatted in ISO 8601. - `trace_id`: A unique identifier for tracing the event across the system. - `event_version`: The version of the event schema to ensure backward compatibility. - `producer_service`: The service that emitted the event. - Validated payload schema: Defines the structure of the event payload, validated according to the event's contract.
Example filename	`invoice-created.v1.0.json`: The filename includes the event name (`invoice-created`) and the version (`v1.0`). This helps in organizing event schema files and ensures proper versioning.

📡 3. `event-topology.yaml`¶

Format	YAML
Purpose	Defines the topology map for all topics, Quality of Service (QoS) guarantees, retry policies, and routing logic within the event-driven architecture. It provides the structure for how events are distributed and handled across the system.

Example¶

topics:
  - name: billing.invoice.created
    qos: exactly_once
    publisher: BillingService
    subscribers:
      - name: CRMService
        retry_policy: exponential_backoff
        max_attempts: 5
        dlq_enabled: true

Explanation:

topics: A list of event topics in the system.
- name: The name of the event topic (e.g., billing.invoice.created).
- qos: The Quality of Service level (e.g., exactly_once, at_least_once, best_effort).
- publisher: The service or component that publishes the event (e.g., BillingService).
- subscribers: The list of services or components that subscribe to the event.
  - name: The name of the subscribing service (e.g., CRMService).
  - retry_policy: The retry strategy used by the subscriber (e.g., exponential_backoff).
  - max_attempts: The maximum number of retry attempts before failure.
  - dlq_enabled: A flag to indicate if a Dead Letter Queue (DLQ) is enabled for failed events.

✅ Used by Adapter Generator to wire the bus configuration for event propagation and routing across the system.

🗺️ 4. `event-flow.mmd`¶

Format	Mermaid Diagram
Purpose	Provides visual documentation of the interactions between event producers, events, and subscribers. This diagram helps visualize the flow of events within the system.

Example¶

flowchart LR
    BillingService -->|InvoiceCreated| CRMService
    BillingService -->|InvoiceCreated| AccountingService

Hold "Alt" / "Option" to enable pan & zoom

Explanation:

BillingService: The event producer that triggers the InvoiceCreated event.
InvoiceCreated: The event being emitted by BillingService.
CRMService and AccountingService: The event consumers that subscribe to the InvoiceCreated event and react accordingly.

✅ Rendered into the ConnectSoft Docs UI and exported as images for use in documentation and presentations.

🧾 5. `event-contract-metadata.yaml`¶

Format	YAML
Fields	The `event-contract-metadata.yaml` file should include the following fields:
	- `trace_id`: A unique identifier for tracing the event contract across systems.
	- `project_id`: The ID of the project associated with the event contract.
	- `bounded_context`: The bounded context associated with the event (e.g., `Billing`, `CRM`).
	- `agent_version`: The version of the agent that generated the event contract.
	- `generated_events`: The number of integration events generated by this contract.
	- `reused_patterns`: A list of reused schema fragments that were part of this event contract.
	- `compliance_flags`: Flags to indicate compliance status, such as: `pii_masked: true`, `audit_required: true` for security and regulatory adherence.

🧪 6. Optional Artifacts¶

Artifact	Format	Purpose
`event-changelog.md`	Markdown	Describes schema changes and subscriber impact
`event-compatibility-report.json`	JSON	Indicates breaking vs non-breaking changes
`event-field-audit-map.yaml`	YAML	Tags PII or auditable fields for compliance scanning

📨 7. Emitted Event: `EventContractPublished`¶

Format	JSON
Purpose	Notifies all subscribers and tools that an event contract has been finalized and is available for use.

Example Payload¶

{
  "event": "EventContractPublished",
  "eventName": "InvoiceCreated",
  "version": "1.0.0",
  "schemaUrl": "https://schemas.connectsoft.dev/invoice-created.v1.0.json",
  "catalogUrl": "https://events.connectsoft.dev/billing/event-catalog.yaml",
  "traceId": "trace-billing-evt-002",
  "timestamp": "2025-05-01T21:32:00Z"
}

Explanation:

event: The name of the event being emitted (e.g., EventContractPublished).
eventName: The name of the specific event being finalized (e.g., InvoiceCreated).
version: The version of the event contract (e.g., 1.0.0), ensuring compatibility across systems.
schemaUrl: The URL where the schema for the event contract is hosted (e.g., invoice-created.v1.0.json).
catalogUrl: The URL for the event catalog that lists available events (e.g., billing/event-catalog.yaml).
traceId: A unique identifier for tracking the event across the system and ensuring traceability.
timestamp: The timestamp when the event contract was finalized and the event was emitted, formatted in ISO 8601.

✅ Output Validation Rules¶

Rule	Description
Every integration event has a unique topic and schema file	✅
Schemas must include required metadata fields	✅
QoS, retry, and subscriber mapping is defined per topic	✅
Topology and catalog match known subscribers and producers	✅
All artifacts include trace_id and agent_version metadata	✅

📦 Artifact Output Summary¶

Artifact	Format	Target Agents
Event Catalog	`event-catalog.yaml`	Adapter, Test, Governance
Event Schemas	`*.json`	CI validation, runtime adapters
Event Topology	`event-topology.yaml`	Message bus configuration
Flow Diagram	`event-flow.mmd`	Docs and visualization
Contract Metadata	`event-contract-metadata.yaml`	Auditing, dashboards
Changelog & Compatibility Report	Optional	Governance and release control
Contract Published Event	JSON	Event Bus, downstream triggers

🧠 Memory Strategy Overview¶

The Event-Driven Architect Agent uses both short-term memory (session-specific) and a semantic long-term memory to:

Accelerate event modeling
Reuse proven schema structures, naming patterns, and topology layouts
Maintain compatibility with prior event versions
Prevent duplication, drift, and anti-patterns
Support versioning, change tracking, and governance scoring

🧠 Short-Term Memory (Per Session)¶

Memory Area	Description
Discovered Events Cache	Events identified and classified during this session (domain/app/integration)
Promoted Events Log	List of events elevated to integration status with reasons
Schema Drafts	Precompiled event schemas before final validation
Topic Reservation Table	Ensures uniqueness across all declared topics within a session
Validation Errors and Retry Attempts	Tracks what was retried and corrected (e.g., naming conflicts, schema omissions)

🗃️ Long-Term Memory (Semantic + Registry-Driven)¶

Stored in vector embeddings and/or indexed documents with governance labels, the long-term memory includes:

📜 1. Historical Event Contracts¶

Memory Fragment	Description
`InvoiceCreated v1.0.0`	JSON Schema + contract metadata + topic + producer info
`SubscriptionCancelled v1.1.0`	Contains compatibility history and changelog reference
`TraceableEventTemplate`	Reusable metadata block: `event_id`, `event_version`, `timestamp`, `trace_id`

Used to bootstrap schema generation and ensure consistent field naming across bounded contexts.

🔄 2. Schema Reuse & Comparison Patterns¶

Query	Memory Response
`"InvoiceCreated"`	Suggests prior schema, topic, subscribers, QoS
`"UserSuspended"`	Suggests base event template + metadata injection
`"EventVersion v1.0 → v2.0"`	Shows breaking field change warnings from compatibility report

🧠 3. Topic and Routing Pattern Library¶

Example	Pattern
`billing.invoice.created`	Used across Billing + Accounting
`crm.user.deactivated`	Used by Notifications, Data Warehouse
`*.created` suffix → triggers audit + observability span

Ensures consistency in event taxonomy across contexts.

⚠️ 4. Anti-Pattern Knowledge Base¶

Anti-Pattern	Handling
❌ Topic reuse across bounded contexts without namespacing	Block and recommend prefix
❌ DTO payloads	Flag as violation, recommend structured object
❌ Events with > 15 fields	Suggest payload segmentation
❌ Events without metadata	Inject required span/correlation fields

📜 5. Versioned Compatibility Ledger¶

Entry	Tracks
`InvoiceCreated v1 → v2`	Changes, compatibility score, new required fields, subscribers impacted
`ShipmentDispatched`	Audit status, PII field annotation added, QoS upgraded in v1.2

📦 Memory Metadata¶

Each reusable item is tagged with:

reuse_score: confidence (0.0 – 1.0)
pattern_verified: true/false
used_by: list of services
last_used: date
schema_version
retired: true/false

🧠 Semantic Memory Retrieval Flow¶

flowchart TD
    A[Identify Candidate Events] --> B[Query Memory]
    B --> C[Match Schema / Topic / QoS]
    C --> D[Inject Patterns + Templates]
    D --> E[Score Match Confidence]
    E --> F[Tag Reuse Metadata]

Hold "Alt" / "Option" to enable pan & zoom

🔁 Feedback to Memory¶

Each reuse is logged and scored:

{
  "event": "PatternReuseLogged",
  "pattern_id": "invoice-created-v1",
  "service": "BillingService",
  "confidence_score": 0.92,
  "trace_id": "trace-billing-evt-293",
  "used_in_version": "1.0.0",
  "resolved_successfully": true
}

✅ Benefits of Memory-Aware Architecture¶

Capability	Benefit
Schema reuse	Consistency across services and contexts
Naming discipline	Predictable, navigable topic taxonomy
QoS enforcement	Reliable delivery guarantees via memory scoring
Governance support	Event evolution tracked and versioned
Change impact reduction	Prevents unintentional breaking changes

✅ Validation and Correction Framework¶

The Event-Driven Architect Agent performs rigorous multi-stage validation of:

Event schemas
Topic definitions
QoS and routing logic
Version compatibility
Governance constraints (naming, PII, observability)

When violations are detected, it applies auto-correction, skill-level retry, or emits escalation warnings.

🔍 Validation Phases¶

1️⃣ Input & Contract Sanity Check¶

Validation	Action
Missing required event fields	Retry with fallback schema injection (`event_id`, `trace_id`, `event_version`)
Invalid `event_name` format	Retry with PascalCase normalization
Duplicate event name or topic	Append `.vX.Y` suffix or bounded context prefix
Payload exceeds field threshold	Suggest refactor to composite object

2️⃣ Schema & Metadata Validation¶

Artifact	Rule
`event-schema-*.json`	Must conform to ConnectSoft Event Schema DSL
All events must include:	`event_id`, `trace_id`, `event_version`, `producer_service`, `timestamp`
No DTOs	Payloads must be flat or composed from primitives and VOs
Field naming	`camelCase` enforced
PII fields	Must be tagged and masked (if applicable)

❌ Fails → invokes SchemaFixerSkill or emits warning if unresolved

3️⃣ Topology & Routing Check¶

Artifact	Rule
Topics must be unique	If conflict, apply suffix or namespace rebinding
QoS must match NFR	Retry if `nfr.yaml` requires `exactly_once` and event is `at_least_once`
Subscribers must be valid service names	Retry with catalog lookup if missing
Retry and DLQ policies required for all external consumers	Inject default policies if omitted

4️⃣ Compatibility & Version Control¶

Artifact	Rule
If `check_version_compatibility = true`, compare with prior version	Schema diff → `event-compatibility-report.json`
Breaking field changes must increment version	Suggest bump from `v1.0.0` → `v2.0.0`
Optional field removals must include changelog annotation	Generate `event-changelog.md` entry automatically

❌ Failures trigger skill-level correction or governance dashboard alert

🔁 Retry and Auto-Correction Flow¶

Skill	Retry Trigger	Action
`SchemaBuilderSkill`	Missing metadata fields	Inject default fields and retry
`TopicMapperSkill`	Duplicate topic	Append version suffix or use namespaced fallback
`SubscriberConfiguratorSkill`	Unknown subscriber	Fallback to manual or catalog-based enrichment
`QoSPolicyAssignerSkill`	Incompatible delivery mode	Retry with compliant QoS (e.g., `upgrade to exactly_once`)

🛠️ Retry Execution Tracing¶

Each retry logs:

{
  "trace_id": "evt-trace-9401",
  "skill": "SchemaBuilderSkill",
  "retry_reason": "missing trace_id in schema",
  "attempt": 2,
  "resolved": true,
  "correction": "injected default observability fields"
}

📈 Observability Metrics¶

Metric	Description
`event_schema_validation_passed_total`	✅ vs ❌ outcomes
`event_retry_count_by_skill{name}`	Frequency of auto-corrections
`breaking_change_detected_total`	Version mismatch or required field removal
`topic_conflict_resolved_total`	Auto-patched naming conflicts
`audit_field_coverage_percent`	Events that include trace/audit fields

🧠 Escalation Conditions¶

Condition	Action
More than 3 retries in same skill	Emit `EventContractGenerationWarning`
Breaking schema change with incompatible consumer detected	Escalate to Governance Officer or Event Registry Moderator
Conflicting glossary/event name with prior bounded context	Flag for manual disambiguation
Missing traceability metadata after retries	Abort pipeline, emit `EventContractValidationFailed`

✅ Outcomes of Robust Validation¶

Capability	Value
Schema safety	Consumers and services trust contracts
Topic clarity	Prevents message routing collisions
Audit-readiness	Traceable events with full metadata
Interop assurance	Versioned, stable schemas across pipelines
Self-healing pipeline	Most errors recoverable with no human intervention

🤝 Collaboration Interfaces¶

The Event-Driven Architect Agent functions as a semantic event translator and contract publisher, interfacing with multiple upstream and downstream agents. It acts as the central coordinator for standardizing, validating, and distributing integration events across the ConnectSoft AI Software Factory.

📡 Upstream Collaboration (Event Discovery)¶

Upstream Agent	Interface
Domain Modeler Agent	- Consumes: `domain-events.json` - Reads event names, emitters, and payloads to understand event structure. - Identifies promotable events by checking the `is_externalizable: true` flag to determine which events can be shared externally.
Application Architect Agent	- Consumes: `use-cases.yaml`, `application-architecture.md` - Maps `emits_event` fields to candidate events that may be emitted by the system. - Understands event emission flows per service handler, ensuring correct event propagation in use case flows.
Solution Architect Agent	- Consumes: `nfr.yaml` (Non-Functional Requirements) - Defines Quality of Service (QoS) requirements (e.g., `exactly_once`, `at_least_once`) and ensures observability and audit flags are set for events.
Ubiquitous Language Agent (optional)	- Reads: `glossary.yaml` - Helps normalize naming conventions for events and topics across contexts, ensuring consistency in terminology across the system.

📦 Downstream Collaboration (Contract Consumption)¶

Downstream Agent	Consumes
🧱 Adapter Generator Agent	- `event-catalog.yaml`: Contains information about event topics, publishers, and subscribers. - *`event-schema-.json`: Defines the schema structure for each event, validating the event payload. - `event-topology.yaml`: Describes the event routing, QoS, and subscribers for each event. > Used to generate publisher/consumer endpoints** in microservices for event-driven communication.
🧪 Test Generator Agent	- *`event-schema-.json`: Defines event payload schema for contract testing. - `event-flow.mmd`: Defines the flow of events across services for testing purposes. > Used to simulate event-driven flows and run contract tests** to validate event communication.
🧩 Observability Agent	- `event-contract-metadata.yaml`: Contains metadata for traceability and compliance. - `event-flow.mmd`: Defines event flow and dependencies between services. > Used to trace span injection points and ensure audit compliance with monitoring and observability tools.
📜 Governance & CI/CD Agents	- `event-compatibility-report.json`: Provides information about event schema compatibility across versions. - `event-changelog.md`: Contains logs of event updates and version changes. > Used for pipeline gating, governance dashboards, and release change control to ensure system integrity across deployments.

🧱 Adapter Generator Agent¶

event-catalog.yaml
event-schema-*.json
event-topology.yaml

Used to generate publisher/consumer endpoints in microservices

🧪 Test Generator Agent¶

event-schema-*.json
event-flow.mmd

Used to simulate event-driven flows and contract tests

🧩 Observability Agent¶

event-contract-metadata.yaml
event-flow.mmd

Used to trace span injection points and audit compliance fields

📜 Governance & CI/CD Agents¶

event-compatibility-report.json
event-changelog.md

Used for pipeline gating, governance dashboards, release change control

📨 Contract Event Emission¶

Event	Trigger
`EventContractPublished`	On successful schema + topology generation
`EventContractValidationFailed`	If event schema or metadata is invalid after retries
`EventContractUpdated`	When a new version of an existing event is published

🔁 Coordination Flow Diagram¶

flowchart TD
    DomainModeler -->|domain-events.json| EventDrivenArchitect
    ApplicationArchitect -->|use-cases.yaml| EventDrivenArchitect
    SolutionArchitect -->|nfr.yaml| EventDrivenArchitect

    EventDrivenArchitect -->|event-catalog.yaml + schemas| AdapterGenerator
    EventDrivenArchitect -->|event-flow.mmd| ObservabilityAgent
    EventDrivenArchitect -->|event-schema.json| TestGenerator
    EventDrivenArchitect -->|EventContractPublished| AgentBus

Hold "Alt" / "Option" to enable pan & zoom

API	Used By
Artifact Storage API	Stores: `event-catalog.yaml`, `*.json`, diagrams, metadata
Event Registry API	Tracks contract versions, compatibility, and ownership
Schema Validator Service	Validates generated JSON schemas before publication
ConnectSoft Event Bus	Used to emit contract lifecycle events and notify CI/CD components

🧠 Inter-Agent Metadata Standards¶

Each shared artifact includes:

trace_id
bounded_context
service_name
agent_version
event_source
schema_version
pattern_reuse, if memory reuse applied

🧭 Collaborative Impact Summary¶

Interaction	Description
Event clarity for downstream adapters	✅ via `event-catalog.yaml` + schema files
Test scaffolding for event simulations	✅ via schema + flow mapping
Observability span points for emit/consume	✅ via `event-flow.mmd` + metadata
Governance automation	✅ via changelog, compatibility report, CI/CD triggers
Agent-to-agent traceability	✅ embedded trace_id + lifecycle event emissions

📡 Observability Hooks¶

The Event-Driven Architect Agent is fully instrumented with OpenTelemetry tracing, structured logs, and contract lifecycle events to provide:

Runtime insight into schema generation, validation, and topology decisions
Complete traceability of every promoted event and contract
Metrics for governance, performance, and reliability

📈 Key Telemetry Metrics¶

Metric	Description
`event_contract_generated_total`	Count of promoted events per session
`schema_validation_failure_total`	Number of invalid schemas during generation
`event_retry_count_by_skill{name}`	Retries triggered during modeling process
`topic_conflict_resolved_total`	Renamed topic collisions per session
`contract_publish_duration_ms`	Duration between discovery → promotion → publication
`event_contract_version_breaking_change_total`	Compatibility rule violations detected
`observability_field_coverage_percent`	% of contracts that include `trace_id`, `event_id`, `timestamp`, etc.

🔍 OpenTelemetry Spans¶

Each skill emits spans including:

skill_name, duration_ms, trace_id, project_id, retry_count, status
Example: SchemaBuilderSkill [v1.0.0] → duration=204ms, status=success, retry=1

These are viewable in ConnectSoft observability dashboards and linked to artifact storage entries.

🧍 Human Oversight and Governance¶

Although largely autonomous, the agent integrates with governance dashboards and manual review escalation mechanisms.

🚨 Manual Review Triggers¶

Trigger	Action
3+ skill retries on the same schema	Raise `EventContractGenerationWarning`
Compatibility conflict with existing schema version	Require approval from Event Registry moderator
Use of conflicting glossary terms across bounded contexts	Raise `ManualDisambiguationRequired`
Missing or ambiguous QoS in critical service	Escalate to Solution Architect Agent

🧾 Audit and Compliance Support¶

Feature	Implementation
PII Field Detection	Via schema linting and `pii: true` tags
Audit Field Enforcement	Required: `trace_id`, `event_id`, `producer_service`, `timestamp`
Versioning Policy Enforcement	Breaking schema changes require major version bump
Lifecycle History	All versions linked via `event-changelog.md` and semantic memory

📢 Lifecycle Events Emitted¶

Event	Emitted When
`EventContractPublished`	Contract and topology generated successfully
`EventContractValidationFailed`	After unrecoverable schema or routing errors
`EventContractUpdated`	When contract changes but is compatible

These events contain:

event_name, version, schema_url, catalog_url, timestamp, trace_id

✅ Conclusion¶

The Event-Driven Architect Agent turns raw domain and application signals into:

📜 Valid, versioned, schema-governed contracts
📡 Event topologies and routing maps
📦 CI/CD-compatible artifacts
🔍 Traceable, observable, governed flows

It allows ConnectSoft services to communicate asynchronously with confidence, ensuring every message is:

✅ Durable
✅ Discoverable
✅ Composable
✅ Observable
✅ Governed

📦 Final Output Summary¶

Artifact	Format
`event-catalog.yaml`	YAML
`event-schema-*.json`	JSON Schema
`event-topology.yaml`	YAML
`event-flow.mmd`	Mermaid
`event-contract-metadata.yaml`	YAML
`event-changelog.md` (optional)	Markdown
`event-compatibility-report.json` (optional)	JSON
`EventContractPublished`	JSON Event

🧠 Event-Driven Architect Agent Specification¶

🎯 Purpose¶

🧠 Strategic Role in the ConnectSoft AI Factory¶

🧠 Core Objectives¶

🔍 Without This Agent...¶

✅ With This Agent...¶

🗂️ Example Output¶

🧭 Event-Driven Principles Embedded¶

🏛️ Scope of Influence¶

📋 Primary Modeling Domains¶

📢 1. Event Classification¶

🔄 2. Topology & Transport Design¶

📦 3. Event Contract Governance¶

🚫 Not in Scope¶

🔁 Influence Map¶

📐 Inter-Bounded Context Flow¶

✅ Scope Summary¶

📋 Core Responsibilities¶

📢 1. Event Discovery & Promotion¶

📜 2. Event Contract Design¶

🔁 3. Topic and Topology Modeling¶

📦 4. Event Flow Diagrams & Maps¶

📡 5. Observability and Replay Enablement¶

🛡️ 6. Governance & Lifecycle¶

📤 7. Output Artifact Generation¶

✅ Summary Table of Responsibilities¶

📥 Core Inputs¶

📋 Required Inputs¶

🧩 Key Input Fields and Mapping¶

🔷 From domain-events.json¶

🔷 From use-cases.yaml¶

🔷 From nfr.yaml¶

🔷 From application-architecture.md¶

📄 Example Aggregated Input View (Simplified YAML)¶

🧪 Input Validation Rules¶

🧠 Semantic Memory Use (Optional)¶

📤 Core Outputs¶

📘 1. event-catalog.yaml¶

Example¶

📜 2. event-schema-*.json¶

Example¶

🧭 3. event-topology.yaml¶

🗺️ 4. event-flow.mmd (Mermaid Diagram)¶

📦 5. event-contract-metadata.yaml¶

📨 6. Emitted Event: EventContractPublished¶

📑 Optional Outputs¶

✅ Output Validation Criteria¶

📚 Knowledge Base Overview¶

📘 1. Event Design Pattern Repository¶

🔁 2. Schema Snippet Library¶

🧠 3. Semantic Memory Retrieval¶

🔍 Examples¶

Metadata Included:¶

⚠️ 4. Anti-Pattern Guard Rules¶

📜 5. Naming and Topic Structure Rules¶

🔄 Governance Features¶

🧠 Knowledge Injection Diagram¶

✅ Benefits of Knowledge-Driven Design¶

🔄 Execution Process Overview¶

📋 Step-by-Step Process Flow¶

1️⃣ Input Validation & Semantic Retrieval¶

2️⃣ Event Classification¶

3️⃣ Schema Generation¶

4️⃣ Topic & Topology Design¶

5️⃣ Contract Validation & Compatibility¶

6️⃣ Artifact Generation¶

7️⃣ Event Publication¶

🔁 Retry and Recovery¶

📈 OpenTelemetry Spans¶

🧠 Process Flow Diagram (High-Level)¶

🛠️ Semantic Kernel Skills Overview¶

📋 Key Skills Used¶

📥 1. Input & Discovery Skills¶

📜 2. Schema & Contract Modeling¶

📡 3. Topology & Routing Design¶

📈 4. Observability & Metadata¶

🧩 5. Output Assembly & Publishing¶

🔁 6. Retry/Validation Skills¶

🧠 Skill Chain Overview¶

🔁 Retry-Oriented Skills¶

🔷 From `domain-events.json`¶

🔷 From `use-cases.yaml`¶

🔷 From `nfr.yaml`¶

🔷 From `application-architecture.md`¶

📘 1. `event-catalog.yaml`¶

📜 2. `event-schema-*.json`¶

🧭 3. `event-topology.yaml`¶

🗺️ 4. `event-flow.mmd` (Mermaid Diagram)¶

📦 5. `event-contract-metadata.yaml`¶

📨 6. Emitted Event: `EventContractPublished`¶

📁 `project`¶

📂 `inputs`¶

⚙️ `settings`¶

📘 1. `event-catalog.yaml`¶

📜 2. `event-schema-*.json`¶

📡 3. `event-topology.yaml`¶

🗺️ 4. `event-flow.mmd`¶

🧾 5. `event-contract-metadata.yaml`¶

📨 7. Emitted Event: `EventContractPublished`¶