# 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.