Diagram Generate Collaboration

Outputs

Files Generated:

• projects/[project-name]/artifacts/Analysis/collaboration-diagrams.md - Markdown with embedded Mermaid diagrams
• projects/[project-name]/artifacts/Analysis/collaboration-diagrams.json - Structured diagram metadata
• orgModel/**/domain-model.md - Updated organizational domain models with embedded class diagrams (when domain-model integration is requested)

Markdown Structure (collaboration-diagrams.md)

# Collaboration Diagrams

**Project**: [project_id]  
**Generated**: [timestamp]  
**Source**: domain-concepts.json, requirements.json

## Domain Class Model

### Entity Relationship Overview *(Diagram D-001)*
**Source Requirements**: [R-001], [R-003]  
**Domain Source**: orgModel/01-skill-dev/domain-model.md

```mermaid
classDiagram
    class User:::core {
        +user_id: String
        +name: String
        +email: String
        +role: UserRole
        +authenticate()
        +updateProfile()
    }
    
    class UserRole:::core {
        +role_id: String
        +name: String
        +permissions: String[]
        +grantAccess()
    }
    
    class Session:::entity {
        +session_id: String
        +start_time: DateTime
        +expiry_time: DateTime
        +is_active: Boolean
        +extend()
        +terminate()
    }
    
    User "1" --> "1" UserRole : has
    User "1" *-- "*" Session : creates
    
    %% Styling Definitions
    classDef core fill:#e1f5fe
    classDef entity fill:#f3e5f5
    classDef enum fill:#fff3e0
    classDef ai fill:#e8f5e8

User-System Interactions

Authentication Flow (Diagram D-002)

Source Requirements: [R-001], [R-003]
Entities Involved: User, AuthenticationService, Database

sequenceDiagram
    participant U as User
    participant AS as AuthenticationService  
    participant DB as Database
    
    U->>AS: Login request (username, password)
    AS->>DB: Validate credentials
    DB-->>AS: User record
    AS->>AS: Generate JWT token
    AS-->>U: Authentication response (token)
    
    Note over AS: Token valid for 24 hours
    Note over U,DB: Secure HTTPS communication

[Additional User-System Diagrams...]

System-System Interactions

API Integration Flow (Diagram D-002)

Source Requirements: [R-005], [R-007]
Entities Involved: APIGateway, ExternalService, Cache

sequenceDiagram
    participant AG as API Gateway
    participant ES as External Service
    participant C as Cache
    
    AG->>C: Check cache for data
    alt Cache Hit
        C-->>AG: Return cached data
    else Cache Miss
        AG->>ES: Request external data
        ES-->>AG: Return fresh data
        AG->>C: Store in cache (TTL: 5min)
    end
    AG-->>Client: Return data response

[Additional System-System Diagrams...]

Hierarchical Collaboration Diagrams

System Boundary View (Diagram D-005)

Source Requirements: [R-010] Decomposition: 01-ECommerce-Platform/collaboration.md

sequenceDiagram
    %% Stereotypes: User=actor | ECommerce=control | Payment=control | Shipping=control
    participant User as "User"
    
    box "E-commerce Platform"
        participant ECommerce as "E-commerce Platform"
    end
    
    box "Payment System"
        participant Payment as "Payment System"
    end
    
    box "Shipping System"
        participant Shipping as "Shipping System"
    end
    
    User->>ECommerce: Place Order
    ECommerce->>Payment: Process Payment
    ECommerce->>Shipping: Schedule Delivery

Process Workflows

[Business Process Diagrams...]

### JSON Structure (`collaboration-diagrams.json`)
```json
{
  "project_id": "string",
  "generation_metadata": {
    "generated_at": "ISO8601",
    "source_files": ["domain-concepts.json", "requirements.json"],
    "total_diagrams": "number",
    "diagram_types": ["class", "sequence", "flowchart", "stateDiagram"]
  },
  "diagrams": [
    {
      "id": "D-001",
      "title": "Entity Relationship Overview", 
      "type": "class",
      "category": "domain-model",
      "description": "Core domain entities and their relationships",
      "entities": ["User", "UserRole", "Session"],
      "source_requirements": ["R-001", "R-003"],
      "mermaid_code": "classDiagram...",
      "complexity": "medium",
      "maintenance_priority": "high"
    },
    {
      "id": "D-002",
      "title": "Authentication Flow", 
      "type": "sequence",
      "category": "user-system",
      "description": "User authentication and JWT token generation",
      "entities": ["User", "AuthenticationService", "Database"],
      "source_requirements": ["R-001", "R-003"],
      "mermaid_code": "sequenceDiagram...",
      "complexity": "medium",
      "maintenance_priority": "high"
    }
  ]
}

Processing Workflow

1. Input Analysis

From domain-concepts.json:

• Extract entities with their relationships
• Identify domain areas and key processes
• Map entity interactions and dependencies

From requirements.json:

• Find interaction patterns in requirement text
• Identify user journeys and system flows
• Extract temporal sequences and decision points

For Hierarchical Diagrams (Optional):

• Identify participant stereotypes (<<Actor>>, <<System>>, <<UI>>, <<Entity>>) from domain concepts
• Classify participants using stereotype inference rules (see Participant Stereotype Classification)
• Detect boundary definitions from configuration or automatic analysis
• Map decomposition links between parent and child diagrams
• Validate decomposition eligibility — only control-type participants may become sub-processes
• Validate boundary-first reception — boundary-type participants must receive actor messages first

2. Diagram Type Selection

Domain Class Models:

• Use class diagrams to visualize entity relationships and domain structure
• Include core entities with attributes and operations
• Show inheritance, composition, and association relationships
• Add styling to distinguish entity types (actors, core entities, enums)

User-System Interactions:

• Use sequence diagrams for user workflows
• Include system responses and error paths
• Show authentication, authorization flows

System-System Interactions:

• Use sequence diagrams for API communications
• Include timeouts, retries, and failure scenarios
• Show data flow between services

Business Process Workflows:

• Use flowcharts for decision trees and branching logic
• Include parallel processes and synchronization points
• Show approval workflows and state transitions

Hierarchical Diagrams:

• Use box syntax to represent system boundaries
• Generate Level 0 diagrams showing high-level system interactions
• Decompose <<System>> participants into Level 1+ diagrams
• Follow EDPS decomposition rules for participant stereotypes
• Apply stereotype classification to all participants before generating diagrams
• Enforce decomposition rules — block decomposition of non-control participants

3. Mermaid Generation Rules

Class Diagrams:

classDiagram
    class [EntityName]:::[styleCategory] {
        +attribute_name: Type
        -private_attribute: Type
        +operation_name()
        -private_operation()
    }
    
    %% UML Relationship Notation (MANDATORY — do NOT use ER notation like ||--o{ )
    %% Association:   ClassA "1" --> "*" ClassB : label
    %% Composition:   Parent "1" *-- "*" Child : label
    %% Aggregation:   Whole "1" o-- "*" Part : label
    %% Inheritance:   Parent <|-- Child
    %% Dependency:    Client ..> Service : uses
    %% Realization:   Interface <|.. Implementation
    %%
    %% Multiplicity: "1", "*", "0..1", "1..*", "0..*"
    %% FORBIDDEN: ||--o{  }o--||  }o--o{  ||--||  (these are ER notation, not UML)
    
    [SourceEntity] "1" --> "*" [TargetEntity] : relationship_label
    [ParentEntity] <|-- [ChildEntity]
    [CompositeEntity] "1" *-- "*" [ComponentEntity] : contains
    [AggregateEntity] "1" o-- "*" [PartEntity] : has
    [Client] ..> [Service] : uses
    
    %% Apply :::style directly on class body declarations
    %% RIGHT:  class User:::core { +name: String }
    %% WRONG:  class User { +name: String }  then  User:::core
    
    %% Styling Definitions
    classDef [styleCategory] fill:#[color]
    classDef actor fill:#e1f5fe
    classDef entity fill:#f3e5f5
    classDef enum fill:#fff3e0
    classDef ai fill:#e8f5e8

Naming Conventions for Class Diagrams:

• Entity names: PascalCase (User, UserProfile, PaymentGateway)
• Attributes: snake_case (user_id, created_at, is_active)
• Methods: camelCase (authenticate(), updateProfile(), calculateTotal())
• Relationships: Use UML notation only — --> (association), *-- (composition), o-- (aggregation), <|-- (inheritance), ..> (dependency)
• Multiplicity: Always annotate with "1", "*", "0..1", etc. on both sides of the relationship
• NEVER use ER notation (||--o{, }o--||, }o--o{, ||--||) in class diagrams — those belong in erDiagram blocks only
• Styling: Apply :::styleCategory directly on class body declarations: class Name:::style { } — this is the preferred format
• Style categories: actor, entity, enum, ai (or custom categories as needed)
• Standard colors: actor (#e1f5fe), entity (#f3e5f5), enum (#fff3e0), ai (#e8f5e8)

Sequence Diagrams:

participant [ShortName] as [Full Entity Name]
[Actor]->>+[Target]: [Action description]
[Target]-->>-[Actor]: [Response description]
Note over [Entity]: [Important information]
alt [Condition]
    [Alternative flow]
else [Other condition]
    [Alternative flow]
end

Naming Conventions:

• Entity names: PascalCase (UserService, PaymentGateway)
• Messages: Action-oriented (Validate credentials, Process payment)
• Notes: Clarify business rules, timeouts, constraints
• Alt blocks: Show error handling and edge cases

Hierarchical Sequence Diagrams (with Boundaries):

sequenceDiagram
    %% Stereotypes: [ActorAlias]=actor | [BoundaryAlias]=boundary, [ControlAlias]=control, [EntityAlias]=entity
    participant [ActorName] as "[Full Actor Name]"
    
    box "[BoundaryName]"
        participant [BoundaryAlias] as "[Full Participant Name]"
        participant [ControlAlias] as "[Full Participant Name]"
        participant [EntityAlias] as "[Full Participant Name]"
    end
    
    [ActorName]->>[BoundaryAlias]: [Interaction]

Naming and Stereotype Conventions:

• Use participant [Alias] as "[Label]" syntax for all participants
• Track stereotypes in a %% Stereotypes: comment at the top of the diagram, using the format: Alias=type separated by commas within a boundary and | between boundaries
• Valid stereotype types: actor, boundary, control, entity
• actor: External participants, cannot be decomposed
• boundary: Entry point to a boundary (e.g., UI, API Gateway)
• control: Decomposable system/service component
• entity: Stable data store or resource
• Quote box labels: box "Boundary Name" for maximum renderer compatibility
• Boundary names should reflect the encapsulated capability
• See Participant Stereotype Classification section for inference and enforcement rules

4. Traceability Integration

Requirement References:

• Link each diagram to source requirements using [R-XXX] format
• Include entity references using ENT-XXX identifiers from domain concepts
• Maintain bidirectional traceability for change impact analysis
• Reference domain models using orgModel/**/*domain-model.md paths for class diagrams

Diagram Metadata:

• Assign unique diagram IDs (D-001, D-002, etc.)
• Track complexity level (simple/medium/complex)
• Set maintenance priority based on business criticality
• Category classification: domain-model, user-system, system-system, process-workflow

For Hierarchical Diagrams:

• Add decomposition field in diagram metadata to link to child diagrams
• Ensure participant names are consistent across hierarchy levels
• Propagate requirement traceability down the decomposition chain

Participant Stereotype Classification

Every participant in a hierarchical collaboration diagram must be classified into exactly one of four stereotypes. Classification drives annotation generation, decomposition eligibility, and message routing validation.

Stereotype Definitions

Automatic Type Inference Rules

When a participant does not have an explicit stereotype, the skill infers its type using the following ordered heuristic rules:

1. Actor inference — A participant is classified as actor when:

   • It appears outside all box boundaries
   • It only initiates interactions (sends first messages) and never receives unsolicited internal messages
   • Its name matches common actor patterns: User, Customer, Client, Admin, External, Partner
   • It has a <<Actor>> stereotype tag in domain concepts

2. Boundary inference — A participant is classified as boundary when:

   • It is the first participant inside a box to receive a message from an external actor
   • Its name matches interface patterns: UI, API, Gateway, Portal, Interface, Handler, Endpoint, Facade
   • It primarily mediates between external actors and internal components
   • It has a <<UI>> stereotype tag in domain concepts

3. Entity inference — A participant is classified as entity when:

   • It primarily receives data operation messages (CRUD: store, retrieve, query, update, delete)
   • Its name matches data patterns: DB, Database, Repository, Store, Cache, Registry, Storage, Table, Queue
   • It does not initiate complex orchestration sequences
   • It has a <<Entity>> stereotype tag in domain concepts

4. Control inference (default) — A participant is classified as control when:

   • It does not match actor, boundary, or entity patterns
   • It performs business logic, orchestration, or coordination
   • Its name matches service patterns: Service, Manager, Processor, Engine, Handler, Coordinator, Orchestrator, Validator
   • It has a <<System>> stereotype tag in domain concepts
   • Fallback: any participant that cannot be classified by the above rules defaults to control

Manual Type Override

Explicit type specification always takes precedence over inference. Types can be set via:

Input JSON:

{
  "participants": [
    { "name": "OrderService", "stereotype": "control" },
    { "name": "AuditLog", "stereotype": "entity" },
    { "name": "AdminPortal", "stereotype": "boundary" }
  ]
}

Inline annotation (already in diagram):

%% Stereotypes: OrderService=control
participant OrderService as "Order Service"

When a manual override conflicts with inferred type, the override wins and a note is added to the diagram metadata:

{
  "type_overrides": [
    { "participant": "AuditLog", "inferred": "control", "override": "entity", "reason": "manual" }
  ]
}

Mermaid Annotation Generation

After classification, every participant definition in the Mermaid output must use the standard participant [Alias] as "[Label]" syntax, with stereotypes tracked in a %% Stereotypes: comment:

sequenceDiagram
    %% Stereotypes: Customer=actor | API=boundary, OrderSvc=control, OrderDB=entity
    participant Customer as "Customer"
    
    box "Order Processing"
        participant API as "Order API"
        participant OrderSvc as "Order Service"
        participant OrderDB as "Order Database"
    end
    
    Customer->>API: Place Order
    API->>OrderSvc: Process Order
    OrderSvc->>OrderDB: Store Order

Generation rules:

• Use participant [Alias] as "[Label]" for every participant
• Include a %% Stereotypes: comment listing all participants with their types
• Format: Alias=type pairs, separated by commas within a box and | between boxes
• Actors are declared before any box block
• Boundary participants are declared first inside their box block
• NEVER use @{ "type": "...", "label": "..." } syntax — it is not supported by most Mermaid renderers (GitHub, Mermaid Live, VS Code preview)
• Always quote box labels: box "Name" not box Name

Decomposition Rule Enforcement

Before generating a decomposition (sub-process diagram) for any participant, the skill must validate decomposition eligibility:

Rule 1: Control-Only Decomposition

• Only participants with "type": "control" may be decomposed into sub-process diagrams
• Attempting to decompose an actor, boundary, or entity participant must produce a validation error

Validation output on violation:

{
  "validation_errors": [
    {
      "rule": "control-only-decomposition",
      "participant": "CustomerDB",
      "type": "entity",
      "message": "Cannot decompose participant 'CustomerDB' (type: entity). Only control-type participants can be decomposed into sub-processes.",
      "suggestion": "If this participant requires internal detail, consider reclassifying it as 'control' or modeling its internals as a separate entity-focused diagram."
    }
  ]
}

Rule 2: Boundary-First Reception

• Within any box boundary, the first message from an external actor must be received by a boundary-type participant
• If no boundary-type participant exists in a box, a validation warning is generated
• If an actor sends a message directly to a control or entity participant inside a box, a validation error is generated

Valid pattern:

Customer (actor) ->> API (boundary) ->> Service (control) ->> DB (entity)

Invalid pattern (produces error):

Customer (actor) ->> Service (control)   ❌ skips boundary

Validation output on violation:

{
  "validation_errors": [
    {
      "rule": "boundary-first-reception",
      "boundary": "Order Processing",
      "actor": "Customer",
      "received_by": "OrderService",
      "received_by_type": "control",
      "message": "Actor 'Customer' sends directly to 'OrderService' (type: control) inside boundary 'Order Processing'. Messages from actors must be received by a boundary-type participant first.",
      "suggestion": "Add or designate a boundary-type participant (e.g., API Gateway) as the entry point for this boundary."
    }
  ]
}

Rule 3: Actor Externality

• actor-type participants must never appear inside a box boundary
• Actors must be declared at the top level, before any box block

Rule 4: Entity Stability

• entity-type participants should not be decomposed
• Entities represent stable data/resource concerns; if internal detail is needed, model it as a separate entity-relationship diagram rather than a process decomposition

Type Consistency Across Hierarchy Levels

When a participant is decomposed from Level N to Level N+1:

• The parent participant at Level N retains its original type annotation
• The decomposed diagram at Level N+1 introduces new participants with their own type classifications
• The entry point in the Level N+1 diagram should be a boundary-type participant matching the parent's external interface
• Type classifications must be consistent — a participant classified as control at Level N cannot appear as entity at Level N+1

Participant Type Summary

After classification, the skill generates a type summary in the diagram metadata:

{
  "participant_type_summary": {
    "total_participants": 8,
    "by_type": {
      "actor": { "count": 2, "participants": ["Customer", "Admin"] },
      "boundary": { "count": 2, "participants": ["WebUI", "AdminPortal"] },
      "control": { "count": 3, "participants": ["OrderService", "PaymentService", "NotificationService"] },
      "entity": { "count": 1, "participants": ["OrderDB"] }
    },
    "decomposable": ["OrderService", "PaymentService", "NotificationService"],
    "type_overrides": [],
    "inference_confidence": {
      "high": ["Customer", "WebUI", "OrderDB"],
      "medium": ["OrderService", "PaymentService"],
      "low": ["NotificationService"]
    }
  }
}

Classification Input Parameters

{
  "stereotype_classification": true,
  "auto_inference": true,
  "manual_overrides": [
    { "participant": "AuditLog", "type": "entity" }
  ],
  "enforce_decomposition_rules": true,
  "enforce_boundary_first_reception": true,
  "generate_type_summary": true
}

Box Syntax Generation

This section defines how the skill generates Mermaid box ... end syntax blocks for boundary grouping in hierarchical sequence diagrams. All rules in this section apply whenever hierarchical_decomposition: true or explicit boundaries are configured.

Core Box Syntax Template

Every boundary is rendered as a box block. External actors are declared before all box blocks; participants inside a boundary appear inside the corresponding box ... end block:

sequenceDiagram

    %% Stereotypes: [ActorName]=actor | [BoundaryParticipant]=boundary, [ControlParticipant1]=control, [ControlParticipant2]=control, [EntityParticipant1]=entity

    %% External participants (actors) — outside all boundaries
    participant [ActorName] as "[Human-readable Actor Label]"

    %% Boundary: [BoundaryName]
    box "[BoundaryName]"
        participant [BoundaryParticipant] as "[Label]"
        participant [ControlParticipant1] as "[Label]"
        participant [ControlParticipant2] as "[Label]"
        participant [EntityParticipant1] as "[Label]"
    end

    %% Interactions
    [ActorName]->>[BoundaryParticipant]: [Action]
    ...

Generation rules:

• All actor-type participants are emitted before any box block
• Each boundary produces exactly one box "[BoundaryName]" ... end block — always quote the label
• Box blocks are separated by a blank line plus a %% Boundary: comment for readability
• MANDATORY: Include a %% Stereotypes: comment listing every participant's type
• MANDATORY: Use participant [Alias] as "[Label]" syntax — NEVER use @{ ... } JSON metadata
• MANDATORY: Participants inside each box must follow strict ordering: boundary first, then control, then entity (see Participant Ordering Within a Box)
• MANDATORY: Box blocks are ordered by first interaction received from the actor — boundaries that receive the actor's first message come first
• Mermaid does not support nested box blocks; decomposition to sub-boundaries is expressed through separate diagrams linked by decomposition references

Participant Ordering Within a Box

Participants inside each box block must follow a strict ordering to satisfy EDPS boundary rules and produce readable diagrams:

Example of correct ordering:

box "Payment Service Boundary"
    participant Gateway as "Payment Gateway"
    participant Processor as "Transaction Processor"
    participant Validator as "Payment Validator"
    participant Ledger as "Transaction Ledger"
end

If a boundary contains no boundary-type participant, emit a validation warning and list all control participants first, followed by entity participants.

Multi-Boundary Generation

Multiple non-overlapping boundaries are supported in a single sequence diagram. Each gets its own box block, declared in order of first interaction:

sequenceDiagram

    %% Stereotypes: Customer=actor | Web=boundary, Order=control, Inventory=control, CustomerDB=entity | PayAPI=boundary, TxProcessor=control, Ledger=entity | FulfillAPI=boundary, Warehouse=control, Shipment=entity
    participant Customer as "Customer"

    %% Boundary: E-commerce Platform
    box "E-commerce Platform Boundary"
        participant Web as "Web Frontend"
        participant Order as "Order Service"
        participant Inventory as "Inventory Service"
        participant CustomerDB as "Customer Database"
    end

    %% Boundary: Payment System
    box "Payment System Boundary"
        participant PayAPI as "Payment API"
        participant TxProcessor as "Transaction Processor"
        participant Ledger as "Transaction Ledger"
    end

    %% Boundary: Fulfillment Center
    box "Fulfillment Center Boundary"
        participant FulfillAPI as "Fulfillment API"
        participant Warehouse as "Warehouse Manager"
        participant Shipment as "Shipment Record"
    end

    Customer->>Web: Place Order
    Web->>Order: Create Order
    Order->>PayAPI: Process Payment
    Order->>FulfillAPI: Schedule Delivery

Multi-boundary constraints:

• Participants cannot belong to more than one boundary block
• Boundaries must be non-overlapping; if a conflict is detected during generation, report a validation error
• Recommended maximum of 5 boundaries per diagram for readability; beyond 5, consider splitting into multiple diagrams
• Order of box blocks follows the sequence of first message receipt by each boundary

Boundary Naming Conventions

Boundary names are derived automatically from context using the following priority order:

Naming formatting rules:

• Use Title Case for all boundary names
• Append " Boundary" suffix to system/component names; omit suffix for naturally scoped phrases that are already descriptive (e.g., E-commerce Platform)
• Avoid acronyms unless they are widely understood in the project domain
• Maximum name length: 50 characters; truncate with ... if exceeded

Boundary Color and Styling

Boundaries support optional color customization. Colors are applied via Mermaid's box color parameter:

box rgb(235, 245, 255) "E-commerce Platform Boundary"
    participant Web as "Web Frontend"
    ...
end

Default color palette (applied round-robin when auto_color: true):

Styling configuration:

{
  "boundary_styling": {
    "auto_color": true,
    "manual_colors": {
      "Payment System Boundary": "rgb(255, 243, 224)",
      "Security Boundary": "rgb(255, 235, 235)"
    }
  }
}

When auto_color: false (default) and no manual_colors are provided, the box keyword is used without a color parameter.

Boundary Summary Comments

When generate_boundary_comments: true is set (recommended), the skill inserts structured comments into the Mermaid output to improve readability and navigation:

sequenceDiagram
    %% ─────────────────────────────────────────────────────
    %% BOUNDARY SUMMARY
    %% ─────────────────────────────────────────────────────    
    %% [B-1] E-commerce Platform Boundary
    %%         Participants: Web Frontend (boundary), Order Service (control),
    %%                       Inventory Service (control), Customer Database (entity)
    %%         Decomposable: Order Service, Inventory Service
    %%         External actor: Customer
    %%
    %% [B-2] Payment System Boundary
    %%         Participants: Payment API (boundary), Transaction Processor (control),
    %%                       Transaction Ledger (entity)
    %%         Decomposable: Transaction Processor
    %%         External actor: none (called from E-commerce Platform)
    %% ─────────────────────────────────────────────────────

    participant Customer as "Customer"

    %% [B-1] E-commerce Platform Boundary
    box "E-commerce Platform Boundary"
        ...
    end

    %% [B-2] Payment System Boundary
    box "Payment System Boundary"
        ...
    end

Edge Case Handling

Box Syntax Configuration Parameters

{
  "box_syntax": {
    "enabled": true,
    "participant_ordering": "boundary-control-entity",
    "generate_boundary_comments": true,
    "boundary_naming": {
      "strategy": "domain-concept-first",
      "suffix": "Boundary",
      "title_case": true
    },
    "boundary_styling": {
      "auto_color": false,
      "manual_colors": {}
    },
    "validation": {
      "enforce_participant_ordering": true,
      "warn_single_participant_boundary": true,
      "error_on_empty_boundary": true,
      "warn_no_boundary_type_entry_point": true,
      "error_on_duplicate_participant": true,
      "warn_exceeds_boundary_count": 5
    }
  }
}

Box Syntax Metadata Output

After box syntax generation the skill emits a box_syntax_metadata block in collaboration-diagrams.json:

{
  "box_syntax_metadata": {
    "total_boundaries": 3,
    "boundaries": [
      {
        "id": "B-1",
        "name": "E-commerce Platform Boundary",
        "color": null,
        "participants": {
          "boundary": ["Web"],
          "control": ["Order", "Inventory"],
          "entity": ["CustomerDB"]
        },
        "decomposable_participants": ["Order", "Inventory"],
        "external_actors": ["Customer"],
        "warnings": []
      },
      {
        "id": "B-2",
        "name": "Payment System Boundary",
        "color": null,
        "participants": {
          "boundary": ["PayAPI"],
          "control": ["TxProcessor"],
          "entity": ["Ledger"]
        },
        "decomposable_participants": ["TxProcessor"],
        "external_actors": [],
        "warnings": []
      }
    ],
    "external_participants": [],
    "validation_errors": [],
    "validation_warnings": []
  }
}

Boundary Validation

This section defines the complete set of boundary validation rules, the two execution modes (strict vs advisory), and the machine-readable validation report format emitted by the skill. Boundary validation runs as a pre-render check after participant classification and box syntax generation, and before final Mermaid output is written.

Overview

All hierarchical collaboration diagrams produced by this skill are validated against four EDPS boundary rules. Each rule can independently raise an error (hard violation) or a warning (advisory issue) depending on the active mode.

Rule VR-1: Single External Interface

Requirement: Each boundary must have exactly one external actor sending messages directly into it. Multiple external actors communicating directly with internal boundary participants violates EDPS encapsulation principles.

Valid:

Customer (actor) ->> API (boundary) [inside Order Boundary]

Invalid:

Customer (actor)  ->> API     [inside Order Boundary]  ✅
Admin (actor)     ->> Service [inside Order Boundary]  ❌  second actor enters boundary directly

Detection logic:

• Collect all message senders that are actor-type and outside the boundary
• If count(distinct external actors sending into boundary) > 1 → violation

Validation output on violation:

{
  "rule": "VR-1",
  "rule_name": "single-external-interface",
  "severity": "error",
  "boundary": "Order Processing Boundary",
  "actors_found": ["Customer", "Admin"],
  "message": "Boundary 'Order Processing Boundary' is accessed by 2 external actors (Customer, Admin). Only one external actor may interact directly with a boundary.",
  "suggestion": "Split into two separate boundaries — one per external actor — or introduce a shared entry-point gateway that aggregates actor messages before forwarding into a single boundary."
}

Rule VR-2: Boundary-First Reception

Requirement: Within any box boundary, the first message sent from an external actor must be received by a boundary-type participant. Actors must not bypass the boundary-type entry point and send directly to control or entity participants.

Valid:

Customer (actor) ->> Gateway (boundary) ->> OrderService (control)

Invalid:

Customer (actor) ->> OrderService (control)   ❌  skips boundary-type entry point

Detection logic:

• For each boundary, identify the first inbound message from an external actor
• Check the receiver's type; if it is not boundary → violation

Validation output on violation:

{
  "rule": "VR-2",
  "rule_name": "boundary-first-reception",
  "severity": "error",
  "boundary": "Order Processing Boundary",
  "actor": "Customer",
  "received_by": "OrderService",
  "received_by_type": "control",
  "message": "Actor 'Customer' sends directly to 'OrderService' (type: control) inside boundary 'Order Processing Boundary'. The first recipient inside a boundary must be a boundary-type participant.",
  "suggestion": "Add or designate a boundary-type participant (e.g., 'Order API' or 'Order Portal') as the single entry point. Route the actor message through that participant first."
}

Rule VR-3: Control-Only Decomposition

Requirement: Only participants with type: control may be decomposed into sub-process diagrams. Attempting to decompose an actor, boundary, or entity participant is a structural violation.

Valid: