X Ipe Tool Architecture Dsl

Architecture DSL Tool

Purpose

AI Agents follow this skill to generate Architecture DSL definitions to:

1. Create layered architecture diagrams (Module View) from requirements
2. Create application landscape diagrams (Landscape View) from system descriptions
3. Refine or update existing Architecture DSL definitions

Important Notes

BLOCKING: Document MUST start with @startuml module-view or @startuml landscape-view and end with @enduml. The view keyword is NOT valid — only @startuml is recognized by the parser. BLOCKING: Module cols within a layer MUST sum to 12. Violation produces invalid diagrams. BLOCKING: component is the mandatory smallest unit. Every layer MUST contain at least one component. module is optional — use it only when grouping components adds clarity; otherwise place components directly in the layer. BLOCKING: After generating or refining DSL, run python3 .github/skills/x-ipe-tool-architecture-dsl/scripts/lint_dsl.py {file} --format json to validate. Fix ALL errors before outputting. CRITICAL: IPE natively renders Architecture DSL in markdown via architecture-dsl code blocks — no HTML files needed. CRITICAL: Stereotyped components render at half width (0.5x) and 1.5x height. Use horizontal grid (grid N x 1) for stereotype-only modules. CRITICAL: Do NOT invent keywords. Only use keywords defined in the grammar (layer, module, component, cols, rows, grid, align, gap, color, border-color, text-align, title, theme, direction, canvas, side-column). Unknown keywords like desc, description, note are silently ignored by the parser and will cause missing content.

Quick Syntax Reference

BLOCKING: Use this as a checklist when generating architecture-dsl code blocks.

Module View — Minimal Valid Structure:

@startuml module-view          ← MUST start with this (NOT `view: module`)
title "Your Title"             ← MUST use double quotes
theme "theme-default"
direction top-to-bottom
grid 12 x {total_rows}         ← MUST declare at document level

layer "Layer Name" {            ← MUST use double quotes
  color "#hex"
  border-color "#hex"
  rows N

  module "Module Name" {        ← optional grouping; cols MUST sum to 12 per layer
    cols N
    rows N
    grid CxR                    ← internal layout (cols x rows >= component count)
    align center center
    gap 8px
    component "Name" { cols 1, rows 1 }   ← MANDATORY smallest unit
  }
}

@enduml                         ← MUST end with this

Valid keywords: layer, module, component, cols, rows, grid, align, gap, color, border-color, text-align, title, theme, direction, canvas, side-column

INVALID keywords (silently ignored — NEVER use): view, desc, description, tech, note, [Name]

About

Architecture DSL is a domain-specific language for defining software architecture diagrams using a Bootstrap-inspired 12-column grid system. It supports two view types: Module View (layered decomposition) and Landscape View (application integration).

Key Concepts:

• Module View - Layered architecture with layers, modules, and components arranged in a 12-column grid
• Landscape View - Application integration diagrams with zones, apps, databases, and action flows
• Grid System - 12-column layout where module cols must sum to 12 per layer
• Stereotypes - Component decorators (<<file>>, <<folder>>, <<model>>, <<service>>, <<icon>>, <<api>>, <<db>>) that alter rendering size

IPE Markdown Embedding:

```architecture-dsl
@startuml module-view
title "Your Architecture"
...
@enduml
```

When to Use

triggers:
  - "architecture diagram"
  - "layer diagram"
  - "module view"
  - "landscape view"
  - "draw architecture"
  - "system architecture"
  - "application landscape"

not_for:
  - "flowcharts -> use Mermaid"
  - "sequence diagrams -> use Mermaid"
  - "class/ER diagrams -> use Mermaid"

Input Parameters

input:
  operation: "generate_module_view | generate_landscape_view | refine_dsl"
  context:
    requirements: "text description or structured requirements"
    existing_dsl: "optional - current DSL to refine"
  options:
    theme: "theme name (default: theme-default)"
    canvas: "optional explicit dimensions (e.g., 1200px, 600px)"
    direction: "top-to-bottom | left-to-right (default: top-to-bottom)"

Definition of Ready

<definition_of_ready>
  <checkpoint required="true">
    <name>Requirements Available</name>
    <verification>Text description, idea summary, or existing DSL provided as input</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>View Type Determined</name>
    <verification>Either module-view (layered) or landscape-view (integration) identified</verification>
  </checkpoint>
</definition_of_ready>

Operations

Operation: Generate Module View

When: Creating a layered architecture diagram from requirements.

<operation name="generate_module_view">
  <action>
    1. Identify architectural layers (standard: Presentation, Business, Data)
    2. Calculate document grid: cols = 12, rows = sum of all layer rows
    3. Allocate module cols per layer (must sum to 12):
       - 2 equal: 6 + 6
       - 3 equal: 4 + 4 + 4
       - 1 wide + 1 narrow: 8 + 4
       - 1 wide + 2 narrow: 6 + 3 + 3
    4. Plan component grid per module:
       - 1-2 components: grid 2 x 1
       - 3-4 components: grid 2 x 2
       - 5-6 components: grid 3 x 2 or grid 2 x 3
       - 7-9 components: grid 3 x 3
    5. Apply layer colors (see references/layout-principles.md)
    6. Use multi-line names with \n for long labels
    7. Run lint: `python3 .github/skills/x-ipe-tool-architecture-dsl/scripts/lint_dsl.py {file} --format json`
    8. Fix any errors reported by linter, re-run until valid
  </action>
  <constraints>
    - BLOCKING: Document MUST start with `@startuml module-view` and end with `@enduml` — the `view` keyword is NOT valid syntax
    - BLOCKING: Module cols MUST sum to 12 per layer
    - BLOCKING: Every layer MUST have rows declaration
    - BLOCKING: Every layer MUST contain at least one `component` (the smallest renderable unit)
    - BLOCKING: Stereotype-only modules MUST use horizontal grid (grid N x 1)
    - BLOCKING: Only use keywords defined in the grammar — unknown keywords (e.g. `desc`) are silently dropped
    - Module is OPTIONAL — use only when grouping components adds clarity
    - Document MUST have grid declaration at document level
  </constraints>
  <output>Complete Architecture DSL in architecture-dsl code block</output>
</operation>

Operation: Generate Landscape View

When: Creating an application integration diagram showing how systems connect.

<operation name="generate_landscape_view">
  <action>
    1. Identify application zones/domains from requirements
    2. Define apps with tech, platform, and status properties
    3. Define databases and data stores
    4. Create action flows between components using verb-based labels
    5. Validate alias uniqueness and flow target existence
    6. Run lint: `python3 .github/skills/x-ipe-tool-architecture-dsl/scripts/lint_dsl.py {file} --format json`
    7. Fix any errors reported by linter, re-run until valid
  </action>
  <constraints>
    - Flow labels MUST be action-focused (e.g., "Submit Order", not "order data")
    - All aliases MUST be unique
    - Flow sources and targets MUST reference defined aliases
    - App status MUST be one of: healthy, warning, critical
  </constraints>
  <output>Complete Architecture DSL in architecture-dsl code block</output>
</operation>

Operation: Refine DSL

When: Updating or correcting an existing Architecture DSL definition.

<operation name="refine_dsl">
  <action>
    1. Parse existing DSL and identify view type
    2. Apply requested changes (add/remove/modify elements)
    3. Recalculate grid dimensions if layers or modules changed
    4. Verify module cols still sum to 12 per layer
    5. Run lint: `python3 .github/skills/x-ipe-tool-architecture-dsl/scripts/lint_dsl.py {file} --format json`
    6. Fix any errors reported by linter, re-run until valid
  </action>
  <constraints>
    - BLOCKING: Preserve existing structure unless change is explicitly requested
    - Recalculate document grid rows when layer rows change
  </constraints>
  <output>Updated Architecture DSL in architecture-dsl code block</output>
</operation>

Operation: Lint DSL

When: Validating generated or existing Architecture DSL against the grammar specification.

<operation name="lint">
  <action>
    1. Save the DSL content to a temporary file (or pipe via stdin)
    2. Run the bundled linter:
       python3 .github/skills/x-ipe-tool-architecture-dsl/scripts/lint_dsl.py {file} --format json
    3. Parse JSON output — check "valid" field
    4. IF valid == false:
       - Read errors[] array for specific violations (E001–E009)
       - Fix each violation in the DSL
       - Re-run linter until valid == true
    5. IF valid == true:
       - Warnings (W001) may remain — review but not blocking
  </action>
  <constraints>
    - BLOCKING: Exit code 1 means errors — DSL must not be output until linter passes
    - Script requires Python 3.10+ with no external dependencies
    - Use --format json for machine-readable output
  </constraints>
  <output>Lint report (JSON) and corrected DSL if needed</output>
</operation>

Output Result

operation_output:
  success: true | false
  result:
    view_type: "module-view | landscape-view"
    dsl: "complete DSL content in architecture-dsl code block"
    validation: "all checklist items passed"
    lint_report: "JSON lint report from scripts/lint_dsl.py (when lint operation used)"
  errors: []

Definition of Done

CRITICAL: After generating or refining DSL, run the bundled linter for deterministic validation, then use a sub-agent for semantic checks the linter cannot cover.

<definition_of_done>
  <lint_validation>
    <tool>python3 .github/skills/x-ipe-tool-architecture-dsl/scripts/lint_dsl.py {file} --format json</tool>
    <instructions>
      1. Save generated DSL to a temp file
      2. Run lint_dsl.py — if exit code 1, fix ALL errors and re-run
      3. Only proceed to sub-agent validation after linter reports valid=true
    </instructions>
  </lint_validation>

  <validation_sub_agent>
    <role>architecture-dsl-validator</role>
    <goal>Validate semantic aspects the linter cannot check (component grid capacity, stereotype layout, keyword correctness)</goal>
    <model_hint>sonnet</model_hint>
    <instructions>
      1. Read the complete DSL grammar from references/grammar.md
      2. Read the layout principles from references/layout-principles.md
      3. Verify ONLY the semantic checkpoints below (linter already covers structural checks)
      4. For each checkpoint: report PASS or FAIL with specific line references
      5. IF any FAIL: return the list of violations with fix suggestions
      6. The generating agent MUST fix all violations before output is accepted
    </instructions>
  </validation_sub_agent>

  <checkpoint required="true">
    <name>Lint Passes</name>
    <verification>scripts/lint_dsl.py exits 0 (no E001–E009 errors). Run BEFORE sub-agent validation.</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Structure Valid</name>
    <verification>Document starts with `@startuml module-view` or `@startuml landscape-view` (NOT `view`), ends with `@enduml`, grid declared at document level</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Grid Rules Satisfied</name>
    <verification>Each layer has rows, each module has cols, module cols sum to 12 per layer</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Components Present</name>
    <verification>Every layer contains at least one `component` — component is the mandatory smallest renderable unit</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Component Grid Valid</name>
    <verification>Each module's internal grid dimensions can contain all declared components (cols x rows >= component count)</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Stereotypes Correct</name>
    <verification>Stereotype-only modules use horizontal grid (grid N x 1)</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Aliases Valid</name>
    <verification>All aliases unique, all flow targets reference defined aliases</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Syntax Conforms to Grammar</name>
    <verification>Only grammar-defined keywords used (no `desc`, `description`, `note`, `view` etc.). Every keyword, property, and nesting level matches references/grammar.md specification</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Output Embedded</name>
    <verification>DSL wrapped in architecture-dsl code block for IPE rendering</verification>
  </checkpoint>
</definition_of_done>

Error Handling

Templates

Module View Structure

@startuml module-view
title "Title"
theme "theme-default"
direction top-to-bottom
canvas 1200px, 600px
grid 12 x 6

layer "Name" {
  color "#hex"
  border-color "#hex"
  rows 2

  module "Name" {
    cols 4
    rows 2
    grid 2 x 3
    align center center
    gap 8px
    component "Name" { cols 1, rows 1 }
  }
}

@enduml

Landscape View Structure

@startuml landscape-view
title "Title"
theme "theme-default"

zone "Zone Name" {
  app "App" as alias {
    tech: Technology
    platform: Platform
    status: healthy | warning | critical
  }
  database "DB" as alias
}

alias1 --> alias2 : "Action Description"

@enduml

Translation Patterns

Examples

• references/grammar.md - Complete DSL grammar specification
• references/layout-principles.md - Grid layout guidelines and color suggestions
• examples/module-view-v2.dsl - Module View example
• examples/landscape-view.dsl - Landscape View example

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