Tool Architecture Draw

Tool: Architecture Draw

Purpose

AI Agents follow this skill to generate architecture diagrams from idea context to:

1. Analyze system structure and select appropriate diagram type
2. Generate Architecture DSL code (module-view or landscape-view)
3. Render visual HTML diagrams from DSL
4. Save versioned artifacts to the idea folder

Important Notes

BLOCKING: If you have NOT learned x-ipe-tool-architecture-dsl skill, learn it first. This skill generates diagrams, not DSL syntax definitions.

CRITICAL: Focus ONLY on architectural structure. Do NOT include UI/UX mockups, user interaction flows, screen layouts, or visual styling preferences. UI mockups are handled by x-ipe-tool-frontend-design.

About

Architecture Draw generates professional architecture diagrams from idea summaries using the Architecture DSL format. It produces grid-based, version-controlled diagram artifacts stored alongside idea documentation.

Key Concepts:

• Module View - Layered architecture decomposition showing internal structure (layers, modules, components)
• Landscape View - Enterprise integration showing how applications connect (zones, apps, databases, flows)
• Architecture DSL - Domain-specific language for defining diagrams with grid-based layouts
• 12-Column Grid - All module-view diagrams use a 12-column grid; module cols must sum to 12 per layer

When to Use

triggers:
  - "draw architecture"
  - "create module diagram"
  - "visualize landscape"
  - "generate architecture diagram"

not_for:
  - "UI/UX mockups (use x-ipe-tool-frontend-design)"
  - "DSL syntax reference (use x-ipe-tool-architecture-dsl)"

Input Parameters

input:
  operation: "generate-diagram"
  context:
    idea_folder: "path to idea folder (required)"
    diagram_type: "module-view | landscape-view | auto (default: auto)"
    architecture_context: "extracted from idea summary"

Definition of Ready

<definition_of_ready>
  <checkpoint required="true">
    <name>Idea folder exists</name>
    <verification>Current Idea Folder path is set and directory exists</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Idea summary available</name>
    <verification>idea-summary-vN.md exists with architecture-relevant content</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Diagram type determined</name>
    <verification>Explicitly set to module-view/landscape-view, or auto-detect enabled</verification>
  </checkpoint>
</definition_of_ready>

Operations

Operation: Validate Context

When: Starting diagram generation

<operation name="validate-context">
  <action>
    1. Verify Current Idea Folder exists
    2. Load latest idea-summary-vN.md
    3. Extract architecture-relevant content:
       - System components mentioned
       - Integration points
       - Technology stack
       - Data flows
  </action>
  <constraints>
    - BLOCKING: Do not proceed if idea folder or summary is missing
  </constraints>
  <output>Validated context with extracted architecture information</output>
</operation>

Operation: Analyze and Select Diagram Type

When: Architecture context is validated

<operation name="analyze-and-select">
  <action>
    1. Determine if single application or multi-application ecosystem
       - Single application = module-view
       - Multi-application = landscape-view
    2. Identify 2-4 primary structural groupings (layers or zones)
    3. List main building blocks (components or apps)
    4. Map relationships and data flows between elements
  </action>
  <constraints>
    - CRITICAL: Use structure extraction mapping below
  </constraints>
  <output>Selected diagram type with structural analysis</output>
</operation>

Structure Extraction Mapping:

Type Selection Matrix:

Operation: Generate Module View DSL

When: Diagram type is module-view

<operation name="generate-module-view">
  <action>
    1. Define document grid: always 12 columns, rows = layer_count * 2
    2. Create layer blocks with color, border-color, and rows
    3. Add modules within each layer (cols MUST sum to 12)
    4. Add components within each module using internal grid
    5. Wrap in @startuml/@enduml tags
  </action>
  <constraints>
    - BLOCKING: Module cols MUST sum to 12 within each layer
    - CRITICAL: Every layer requires rows property
    - CRITICAL: Use suggested colors (see below)
  </constraints>
  <output>Valid module-view DSL code</output>
</operation>

Module View Template:

@startuml module-view
title "{Idea Name} Architecture"
direction top-to-bottom
grid 12 x {layer_count * 2}

layer "{Layer Name}" {
  color "{layer_color}"
  border-color "{border_color}"
  rows 2

  module "{Module Name}" {
    cols {N}
    rows 2
    grid {C} x {R}
    align center center
    gap 8px

    component "{Component Name}" { cols 1, rows 1 }
  }
}

@enduml

Suggested Colors:

Operation: Generate Landscape View DSL

When: Diagram type is landscape-view

<operation name="generate-landscape-view">
  <action>
    1. Create zone blocks for each application domain
    2. Add apps with tech, platform, and status properties
    3. Add databases in data zones
    4. Define action flows between aliases
    5. Wrap in @startuml/@enduml tags
  </action>
  <constraints>
    - BLOCKING: All aliases must be unique
    - CRITICAL: Flow labels must use action verbs ("Submit Order"), not protocols ("HTTP")
    - CRITICAL: Flow targets must reference defined aliases
  </constraints>
  <output>Valid landscape-view DSL code</output>
</operation>

Landscape View Template:

@startuml landscape-view
title "{Ecosystem Name}"

zone "{Zone Name}" {
  app "{App Name}" as {alias} {
    tech: {Technology}
    platform: {Platform}
    status: healthy
  }
}

zone "Data" {
  database "{DB Name}" as {alias}
}

{source} --> {target} : "{Action Description}"

@enduml

Operation: Validate DSL

When: DSL code has been generated

<operation name="validate-dsl">
  <action>
    1. Verify @startuml and @enduml tags present
    2. Check grid declaration (module-view)
    3. Verify module cols sum to 12 in each layer
    4. Verify every layer has rows property
    5. Confirm all aliases are unique
    6. Confirm flow targets reference defined aliases
  </action>
  <constraints>
    - BLOCKING: Fix all validation errors before rendering
  </constraints>
  <output>Validated DSL or list of errors to fix</output>
</operation>

Operation: Render HTML

When: DSL validation passes

<operation name="render-html">
  <action>
    1. Parse DSL structure into element tree
    2. Calculate grid positions from layout properties
    3. Generate CSS Grid layout with proper sizing
    4. Apply colors and styling from DSL properties
    5. Create responsive HTML container
  </action>
  <output>Complete HTML file with rendered diagram</output>
</operation>

Operation: Save Artifacts

When: HTML rendering is complete

<operation name="save-artifacts">
  <action>
    1. Create architecture/ subdirectory in idea folder
    2. Save DSL file: {type}-{name}-v{version}.dsl
    3. Save HTML file: {type}-{name}-v{version}.html
    4. Create README.md with diagram explanation
  </action>
  <constraints>
    - CRITICAL: Follow naming convention: {type}-{name}-v{version}.{ext}
  </constraints>
  <output>Saved artifact paths</output>
</operation>

Directory Structure:

{Current Idea Folder}/
  idea-summary-vN.md
  architecture/
    {diagram-name}.dsl
    {diagram-name}.html
    README.md

Output Result

operation_output:
  success: true | false
  result:
    diagram_type: "module-view | landscape-view"
    dsl_path: "{idea_folder}/architecture/{name}.dsl"
    html_path: "{idea_folder}/architecture/{name}.html"
    elements:
      layers: N          # module-view only
      modules: N         # module-view only
      components: N      # module-view only
      zones: N           # landscape-view only
      apps: N            # landscape-view only
      flows: N           # landscape-view only
  errors: []

Definition of Done

<definition_of_done>
  <checkpoint required="true">
    <name>Architecture context extracted</name>
    <verification>Structural elements identified from idea summary</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Diagram type selected</name>
    <verification>module-view or landscape-view chosen with rationale</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>DSL generated and validated</name>
    <verification>All validation rules pass (grid, cols, aliases, flows)</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>HTML rendering created</name>
    <verification>Visual diagram renders correctly from DSL</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Artifacts saved</name>
    <verification>DSL and HTML files exist in {idea_folder}/architecture/</verification>
  </checkpoint>
</definition_of_done>

Error Handling

Templates

Examples

See examples/ for complete diagram examples:

• module-view-webapp.dsl - Standard web application
• landscape-view-enterprise.dsl - Enterprise integration map

See references/ for additional documentation:

• dsl-cheatsheet.md - DSL syntax quick reference
• patterns.md - Architecture patterns and anti-patterns

Converted and distributed by TomeVault — claim your Tome and manage your conversions.