apk-deploy-02/docs/diagram-promt.md

K3s Infrastructure Diagram Formatting Guidelines

This document provides specific formatting guidelines for creating consistent, readable, and machine-parsable PlantUML diagrams for the K3s Kubernetes infrastructure project.

Activity Diagram Formatting

Activity diagrams should use the following formatting style with header separators (====) and detail separators (----):

:Activity Name
====
parameter1=value1
parameter2=value2
parameter3=value3
----
Additional context or explanation;

Key Formatting Rules

1. Activity Names: Clear, concise action descriptions
2. Parameter Section: Place after the header separator (====)
   • Use parameter=value format on separate lines
   • Parameters should be specific to the action (e.g., paths, commands, modes)
3. Context Section: Place after the detail separator (----)
   • Provide a brief explanation of the action's purpose
   • End with a semicolon
4. Variable Escaping: Enclose Terraform variables or special characters in single quotes
   • Example: local_path='${kubeconfig_path}' instead of local_path=${kubeconfig_path}
   • This prevents parsing errors in PlantUML

Example

:Install K3s Server
====
action=curl -sfL https://get.k3s.io
mode=server
k3s_version='${var.k3s_version}'
----
Configures node as a Kubernetes server;

Component Diagram Formatting

Component diagrams should use a consistent C4 model approach:

Component(id, "Name", "Technology", "Description", $tags="tag")

Key Formatting Rules

1. Component Definitions: Use C4 model component syntax
2. Tags: Use consistent tags for visual grouping (module, resource, data, provider)
3. Relationships: Clearly indicate direction and purpose of relationships
4. Systems: Group related components inside System_Boundary blocks
5. Special Characters: Escape variables or special characters with single quotes
   • Example: "Version: '${var.version}'" instead of "Version: ${var.version}"

Example

Component(k3s_module, "K3s Install Module", "terraform/modules/k3s-install", "Module for K3s Kubernetes cluster deployment", $tags="module")

Sequence Diagram Formatting

Sequence diagrams should use clear participant definitions and message formatting:

participant "Participant Name" as alias

For messages, follow this format:

sender -> receiver: Action
====
parameter1=value1
parameter2=value2
----
Additional context;

Key Formatting Rules

1. Participant Definitions: Clear names with meaningful aliases
2. Message Formatting: Include header and detail separators for complex actions
3. Grouping: Use group for parallel or related actions
4. Phases: Separate workflow into logical phases using ==Phase Name==
5. Special Characters: Escape variables with single quotes in message text
   • Example: Setup server at address: '${server_ip}'

Deployment Diagram Formatting

Deployment diagrams should use:

rectangle "Component Name\n(hostname)" as alias <<Type>> {
    rectangle "Subcomponent" as subAlias
}

Key Formatting Rules

1. Component Containers: Group related components inside rectangles
2. Stereotypes: Use <<Server>>, <<Worker>>, <<Config>> consistently
3. Connections: Use solid lines for network connections, dashed for data flows
4. Notes: Use notes to explain complex relationships or configurations
5. Special Characters: Escape variables with single quotes in component names
   • Example: "Server '${var.name}'" instead of "Server ${var.name}"

Class Diagram Formatting

Class diagrams representing Terraform resources should use:

class "Resource Name" as alias {
  + property: type
  - private_property: type
  + method()
}

Key Formatting Rules

1. Resource Representation: Each Terraform resource is a class
2. Properties: Include all significant properties with their types
3. Relationships: Show dependencies using standard UML notation
4. Packages: Group related resources into logical packages
5. Special Characters: Escape variables with single quotes in properties
   • Example: + url: '${var.domain}' instead of + url: ${var.domain}

General Formatting Guidelines

1. Naming Consistency: Use consistent naming across all diagrams
2. Color Schemes: Maintain consistent color themes across diagrams
3. Comments: Include descriptive comments/notes for complex elements
4. Escaping Special Characters: Always enclose Terraform variable references (${...}) in single quotes
5. Footer: Include version information in the footer
6. Title: Use clear, descriptive titles

These formatting guidelines ensure that all infrastructure diagrams are consistent, readable, and correctly processed by both PlantUML and Terraform code generators.