/033-architecture-diagrams

name: 033-architecture-diagrams
description: Use when you need to generate Java project diagrams — including UML sequence diagrams, UML class diagrams, C4 model diagrams, UML state machine diagrams, UML Deployment Diagrams, ER (Entity Relationship) diagrams, and bounded-context diagrams — through a modular, step-based interactive process that adapts to your specific visualization needs. This should trigger for requests such as Generate UML diagram; Create sequence diagram; Create class diagram; Create state machine diagram; Create deployment diagram; Create C4 diagram; Create bounded-context diagram; Create context-map diagram. Part of Plinth Toolkit
license: Apache-2.0
metadata:
  author: Juan Antonio Breña Moral
  version: 0.18.0

Java Diagrams Generator with modular step-based configuration

Generate comprehensive Java project diagrams through a modular, step-based interactive process that covers UML sequence diagrams, UML class diagrams, C4 model diagrams, UML state machine diagrams, UML Deployment Diagrams, ER (Entity Relationship) diagrams, and bounded-context diagrams using PlantUML syntax. **This is an interactive SKILL**.

**What is covered in this Skill?**

• UML sequence diagram generation for application workflows and API interactions
• UML class diagram generation for package structure and class relationships
• C4 model diagram generation for Context, Container, and Component diagrams
• UML state machine diagram generation for entity lifecycles and business workflows
• UML Deployment Diagram generation for runtime topology, nodes, execution environments, deployed components, data stores, queues, external systems, and communication paths
• ER diagram generation from SQL schema (DDL, migrations) using PlantUML Chen notation
• Bounded-context diagram generation for DDD context maps across one or more repositories
• PlantUML syntax for all diagram types
• File organization strategies: single-file, separate-files, or integrated with existing documentation
• Final diagram validation with PlantUML syntax checking
• PlantUML validation and PNG/SVG rendering with a trusted local PlantUML installation or repository-approved wrapper

Constraints

Before applying any diagram generation, ensure the project validates. If validation fails, stop immediately — do not proceed until all validation errors are resolved.

• **MANDATORY**: Run `./mvnw validate` or `mvn validate` before applying any diagram generation
• **SAFETY**: If validation fails, stop immediately — do not proceed until all validation errors are resolved
• **BEFORE READING DIAGRAM REFERENCES**: Run the question flow embedded in this SKILL.md first. Ask the diagram preference questions one by one, collect selected diagram families and output preferences, then read only the implementation references selected by the user's answers
• **C4 SCOPE**: C4 diagrams are restricted to Context, Container, and Component diagrams
• **SUPPLY CHAIN**: Generated PlantUML diagrams must use trusted local includes only; do not use remote `!include` URLs for C4 or icon libraries
• **TOOLING SAFETY**: Use only trusted local PlantUML tooling or a repository-approved wrapper; do not pull or run remote container images as part of this skill

When to use this skill

• Generate UML diagram
• Create sequence diagram
• Create class diagram
• Create state machine diagram
• Create deployment diagram
• Create C4 diagram
• Generate ER diagram
• Create bounded-context diagram
• Create context-map diagram

Workflow

1. **Validate project state**

Run `./mvnw validate` or `mvn validate` before applying any diagram generation.

Step constraints:

• If validation fails, stop and ask to resolve errors first

2. **Ask diagram assessment questions before reading references**

Run this XML-included question flow before reading any diagram-family implementation reference. Ask questions one-by-one in strict order, wait for the user's answer to each question, and record selected diagram families, C4 scope, bounded-context repository scope, output organization, file format, and documentation preference before continuing.

IMPORTANT: You MUST ask these questions in the exact order and wording shown here. The very first question to the user MUST be "Question 1: What diagrams do you want to generate?". Do not ask any other questions prior to it.

Diagrams Selection

Conditional Flow Rules:

• Based on your selection here, only the relevant diagram generation steps will be executed.
• If you choose "Skip", no diagrams will be generated.
• Each diagram type has its own conditional follow-up questions.

---

**Question 1**: What diagrams do you want to generate?

Options:

• UML sequence diagrams
• UML class diagrams
• UML state-machine diagrams
• C4 model diagrams (Context, Container, Component)
• UML Deployment Diagrams
• ER diagrams (Entity Relationship)
• Bounded-context diagrams
• All diagrams
• Skip

---

**Question 2**: For UML sequence diagrams, which types would you like to generate? Ask this question only if you selected "UML sequence diagrams" or "All diagrams" in Question 1.

Options:

• Main application flows (user journeys, authentication, core features)
• API interactions (REST endpoints, request/response patterns)
• Complex business logic flows (multi-step processes, transactions)
• All sequence diagram types
• Skip

---

**Question 3**: For UML class diagrams, which scope would you like to cover? Ask this question only if you selected "UML class diagrams" or "All diagrams" in Question 1.

Options:

• All packages (complete project structure)
• Core business logic packages only
• Specific packages (I'll specify which ones)
• Skip

---

**Question 4**: For UML class diagrams, what level of detail do you prefer? Ask this question only if you selected "UML class diagrams" or "All diagrams" in Question 1 and did not select "Skip" in Question 3.

Options:

• High-level (classes and relationships only)
• Detailed (include key methods and attributes)
• Ful