bce-diagrams - SKILL.md Agent Skill

name: bce-diagrams description: Create high-level overview diagrams showing interactions between business components (BCs), subsystems, services, or systems. Use when asked to create architecture overviews, BC interaction diagrams, subsystem diagrams, service interaction diagrams, system landscapes, or integration maps. Triggers on "diagram", "overview diagram", "BC interaction", "business component diagram", "subsystem diagram", "service interaction", "component interaction", "architecture overview", "system diagram", "integration diagram", or requests to visualize how BCs, subsystems, or services communicate. Not for detailed class diagrams or sequence diagrams. argument-hint: "[services or components to visualize]"

BCE Overview Diagrams

Create diagrams that show interactions and dependencies between business components (BCs), subsystems, and external services at a high level of abstraction. Based on BCE architecture (see bce.design).

BCE Terminology

Business Component (BC) — a feature-based unit grouping related boundary, control, and entity packages. Named after its domain responsibility (e.g., orders, payments, speakers).
Boundary — the BC's external interface: JAX-RS resources, facades, health checks.
Subsystem — a grouping of related BCs at a higher level of abstraction.
In "between components" mode, show BCs and subsystems as opaque nodes. In "within components" mode, expand BCs to show their boundary, control, and entity layers.

Workflow

Gather information - Identify BCs, subsystems, and external services to visualize. Analyze the codebase package structure ([org].[project].[bc].[boundary|control|entity]) or use the user's description.
Choose detail level and format - Ask the user using a single AskUserQuestion call with two questions:
- Detail level: "Between components" (each BC is a single opaque node) or "Within components" (show boundary, control, entity layers inside each BC)
- Format: "Mermaid (Recommended)" (text-based, version-control friendly, renders natively in GitHub/GitLab — default for README.md in GitHub projects) or "draw.io" (visual editor, richer styling, exportable to PNG/SVG)
Invoke the chosen skill - Use the Skill tool to invoke either mermaid or drawio with the identified BCs, subsystems, interactions, and chosen detail level. When the diagram is destined for a README.md in a GitHub project, default to Mermaid without asking.

Diagram Content Guidelines

Between components (default)

Show BCs, subsystems, and external services — not classes, methods, or fields
Represent each BC as a single node labeled by its responsibility: Orders, Payments, Users
Group BCs into subsystems when they share a domain: subgraph Billing [Orders, Payments, Invoicing]
Focus on interactions between BCs: which boundary calls which boundary, what data flows where
Label arrows with the interaction type when not obvious: -->|REST|, -->|async|, -->|JPA|
Show external dependencies (third-party APIs, databases, message brokers) as separate nodes

Within components

Represent each BC as a subgraph containing its boundary, control, and entity layers
Show internal interactions: boundary → control → entity
Show cross-BC interactions at the boundary level: one BC's boundary calls another BC's boundary
External dependencies connect to the boundary or control layer that uses them

Information Gathering

When the user does not specify components, analyze the codebase:

Scan the package structure for BC packages (children of the top-level application package containing boundary/control/entity sub-packages)
Identify cross-BC interactions via injected references, REST client calls, or messaging
Determine external dependencies (third-party APIs, cloud services, databases)