feat: add architecture docs for the service

.crd-ref-docs.yaml

@@ -0,0 +1,17 @@
+# Configuration for crd-ref-docs
+# See: https://github.com/elastic/crd-ref-docs
+
+processor:
+  # Ignore certain fields that are not relevant for API documentation
+  ignoreFields:
+    - "TypeMeta$"
+    - "ObjectMeta$"
+    - "ListMeta$"
+
+renderer:
+  kubernetesVersion: 1.34
+
+output:
+  # Use markdown format
+  markdown:
+    headerDepth: 1

Taskfile.yaml

@@ -46,6 +46,11 @@ includes:
     vars:
       ROOT_DIR: "{{.USER_WORKING_DIR}}"
 
+  # Documentation (diagrams, etc.)
+  docs:
+    taskfile: ./docs/Taskfile.yaml
+    dir: ./docs
+
 tasks:
   default:
     desc: List all available tasks
@@ -349,15 +354,23 @@ tasks:
         echo "✅ API documentation generation complete"
     silent: true
 
+  # Architecture diagram tasks
+  diagrams:
+    desc: Generate architecture diagrams from PlantUML
+    cmds:
+      - task: docs:diagrams
+    silent: true
+
   # Unified code generation task - composes all generate:* subtasks
   generate:
-    desc: Run all code generation tasks (OpenAPI, migrations ConfigMap, API docs, k6 tests, etc.)
+    desc: Run all code generation tasks (OpenAPI, migrations ConfigMap, API docs, diagrams, k6 tests, etc.)
     deps:
       - generate:openapi
       - migrations:generate
       - load:generate
       - observability:build-mixin
       - generate:docs
+      - docs:generate
     cmds:
       - |
         echo ""

docs/Taskfile.yaml

@@ -0,0 +1,75 @@
+version: '3'
+
+vars:
+  DIAGRAMS_DIR: "{{.USER_WORKING_DIR}}/docs/diagrams"
+  OUTPUT_FORMAT: "png"
+
+tasks:
+  generate:
+    desc: Generate all documentation artifacts (diagrams, etc.)
+    cmds:
+      - task: diagrams:render
+    silent: true
+
+  diagrams:
+    desc: Generate all architecture diagrams from PlantUML
+    cmds:
+      - task: diagrams:render
+    silent: true
+
+  diagrams:render:
+    desc: Render PlantUML diagrams to PNG format using Docker
+    cmds:
+      - |
+        set -e
+        echo "Rendering PlantUML diagrams..."
+        echo ""
+
+        # Check if PlantUML files exist
+        if ! ls {{.DIAGRAMS_DIR}}/*.puml 1>/dev/null 2>&1; then
+          echo "No PlantUML source files found in {{.DIAGRAMS_DIR}}"
+          exit 0
+        fi
+
+        # Render using Docker (no local installation required)
+        docker run --rm \
+          -v "{{.DIAGRAMS_DIR}}":/data \
+          plantuml/plantuml:latest \
+          -t{{.OUTPUT_FORMAT}} \
+          /data/*.puml
+
+        echo ""
+        echo "Diagrams rendered in {{.DIAGRAMS_DIR}}"
+        echo ""
+        echo "Generated files:"
+        ls -1 {{.DIAGRAMS_DIR}}/*.{{.OUTPUT_FORMAT}} 2>/dev/null | xargs -n1 basename || echo "No output files found"
+    silent: true
+
+  diagrams:clean:
+    desc: Remove generated diagram files
+    cmds:
+      - |
+        rm -f {{.DIAGRAMS_DIR}}/*.png {{.DIAGRAMS_DIR}}/*.svg
+        echo "Generated diagram files removed"
+    silent: true
+
+  diagrams:validate:
+    desc: Validate PlantUML syntax using Docker
+    cmds:
+      - |
+        set -e
+        echo "Validating PlantUML diagrams..."
+
+        # Check if PlantUML files exist
+        if ! ls {{.DIAGRAMS_DIR}}/*.puml 1>/dev/null 2>&1; then
+          echo "No PlantUML source files found in {{.DIAGRAMS_DIR}}"
+          exit 0
+        fi
+
+        docker run --rm \
+          -v "{{.DIAGRAMS_DIR}}":/data \
+          plantuml/plantuml:latest \
+          -syntax \
+          /data/*.puml
+        echo "All diagrams are valid"
+    silent: true