docs: design brief for service catalog registration

Taskfile.yaml

@@ -1,6 +1,10 @@
 version: '3'
 
 includes:
+  # Documentation tasks
+  docs:
+    taskfile: ./docs/Taskfile.yaml
+    dir: ./docs
   dev:
     taskfile: ./Taskfile.dev.yaml
 
@@ -77,4 +81,9 @@ tasks:
             echo ""
             echo "🎉 All Prometheus rule tests passed."
           fi
-      silent: false
+      silent: false
+
+  generate:
+    desc: Run code generation (deepcopy, defaults)
+    deps:
+      - task: docs:generate

docs/Taskfile.yaml

@@ -0,0 +1,69 @@
+version: '3'
+
+vars:
+  DIAGRAMS_DIR: "{{.ROOT_DIR}}/docs/diagrams"
+  OUTPUT_FORMAT: "png"
+  PLANTUML_IMAGE: plantuml/plantuml:1.2026.4
+
+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 >/dev/null 2>&1; then
+          echo "❌ Error: PlantUML source files (*.puml) not found in {{.DIAGRAMS_DIR}}"
+          exit 1
+        fi
+
+        # Render using Docker (no local installation required)
+        docker run --rm \
+          -v "{{.DIAGRAMS_DIR}}":/data \
+          {{.PLANTUML_IMAGE}} \
+          -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..."
+        docker run --rm \
+          -v "{{.DIAGRAMS_DIR}}":/data \
+          {{.PLANTUML_IMAGE}} \
+          -syntax \
+          /data/*.puml
+        echo "✅ All diagrams are valid"
+    silent: true

docs/diagrams/http-metering-c4.puml

@@ -0,0 +1,25 @@
+@startuml http-metering-c4
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+LAYOUT_WITH_LEGEND()
+
+title C4 Container Diagram - HTTP Traffic Metering System
+
+Person(client, "End User / Client", "Requests services exposed via Datum Cloud Edge")
+
+System_Boundary(edge_cluster, "Edge Cluster") {
+    Container(envoy, "Envoy Gateway Proxy", "Envoy/Go", "Handles ingress HTTP traffic, terminates TLS, enforces WAF/rate-limiting, emits JSON access logs to stdout")
+    Container(vector_collector, "billing-usage-collector-vector", "Vector DaemonSet (Billing)", "Tails Envoy container logs, parses JSON access logs, translates to CloudEvents, and forwards them to the Billing System")
+    Container(nso, "Network Services Operator", "Go", "Deploys Envoy Gateway and configures EnvoyProxy logging policies")
+}
+
+System_Boundary(control_plane, "Platform Control Plane") {
+    Container(billing_system, "Billing System & Service Catalog", "Platform Service", "Handles service registration, event validation, attribution, and storage")
+}
+
+Rel(client, envoy, "Sends HTTPS requests to", "HTTPS")
+Rel(nso, envoy, "Configures & manages", "Kubernetes API / EnvoyProxy CR")
+Rel_D(envoy, vector_collector, "Outputs JSON access logs to", "stdout / container logs")
+Rel_D(vector_collector, billing_system, "Forwards batched events to", "HTTPS CloudEvents")
+
+@enduml

docs/diagrams/http-metering-sequence.puml

@@ -0,0 +1,35 @@
+@startuml http-metering-sequence
+skinparam BoxPadding 10
+skinparam ParticipantPadding 10
+
+actor Client as client
+box "Edge Cluster Node" #LightBlue
+  participant "Envoy Gateway (Proxy)" as envoy
+  participant "billing-usage-collector-vector\n(DaemonSet)" as vector
+end box
+
+box "Platform Control Plane" #LightYellow
+  participant "Billing System" as billing
+end box
+
+client -> envoy : 1. HTTP Request (GET /path)
+activate envoy
+envoy -> envoy : Route lookup & WAF checks
+envoy -> client : 2. HTTP Response (200 OK with Egress Bytes)
+deactivate envoy
+
+note over envoy : Request completed
+envoy -> vector : 3. Write structured JSON access log to stdout\n(contains bytes, duration, route name/namespace)
+activate vector
+
+vector -> vector : Tail logs, parse JSON,\nand map to CloudEvent\n(No enrichment)
+
+vector -> billing : 4. Forward batched CloudEvents\n(HTTPS batch ingest)
+activate billing
+
+billing -> billing : Validate, attribute, and persist
+billing --> vector : 200 OK / 202 Accepted
+deactivate billing
+deactivate vector
+
+@enduml