Merge pull request 'docs: documentation for validate/sonar-test-nest4' (#17) from documentor-validate-sonar-test-nest4-08037ae6 into main

catalog/component/default/sonar-test-nest4/README.md

@@ -1,7 +1,7 @@
 ---
 title: "sonar-test-nest4"
 generated_by: documentor-agent
-generated_at: "2026-05-15T15:19:48+00:00"
+generated_at: "2026-05-15T15:21:00+00:00"
 human_edited: false
 source_entity: "Component/default/sonar-test-nest4"
 source_repo: "https://gitea.kyndemo.live/validate/sonar-test-nest4"
@@ -9,18 +9,18 @@ source_repo: "https://gitea.kyndemo.live/validate/sonar-test-nest4"
 
 ## Overview
 
-`sonar-test-nest4` is a stateless microservice built using the `typescript-nestjs` runtime. It was scaffolded from the **Create Microservice** golden-path template on the Kyndryl Platform. The service provides a RESTful API for managing items, including endpoints for CRUD operations. It is designed to be lightweight, scalable, and observable, with integrated OpenTelemetry instrumentation and Prometheus metrics.
+`sonar-test-nest4` is a stateless microservice built using the `typescript-nestjs` runtime. It was scaffolded from the **Create Microservice** golden-path template on the Kyndryl Platform. The service provides a REST API for managing items, including endpoints for CRUD operations. It is designed to be lightweight, scalable, and observable, with integrated OpenTelemetry instrumentation and Prometheus metrics.
 
-This service plays a critical role in the demo-apps domain, serving as a foundational component for item management workflows. It is deployed via Humanitec and runs on Azure Kubernetes Service (AKS), leveraging Azure Container Registry for image storage. The CI/CD pipeline is managed through Gitea Actions, ensuring automated builds, tests, and deployments across environments (`dev`, `staging`, `prod`).
+This service plays a key role in the broader system by offering item management capabilities. It is deployed on Azure Kubernetes Service (AKS) via Humanitec's Score-based deployment model, with container images stored in Azure Container Registry (ACR). The CI/CD pipeline is managed through Gitea Actions, ensuring automated builds, tests, and deployments across development, staging, and production environments.
 
 ## Repository
 
-| Field          | Value                                                                                                           |
+| Field          | Value                                                                                                                              |
-|----------------|-----------------------------------------------------------------------------------------------------------------|
+|----------------|------------------------------------------------------------------------------------------------------------------------------------|
-| Source Repo    | [validate/sonar-test-nest4](https://gitea.kyndemo.live/validate/sonar-test-nest4)                               |
+| Source Repo    | [validate/sonar-test-nest4](https://gitea.kyndemo.live/validate/sonar-test-nest4)                                                  |
-| Branch         | `dev`                                                                                                          |
+| Branch         | `dev`                                                                                                                             |
-| ArgoCD App     | —                                                                                                              |
+| ArgoCD App     | —                                                                                                                                 |
-| Namespace      | `dev`                                                                                                          |
+| Namespace      | `dev`                                                                                                                             |
 
 ## Architecture
 
@@ -28,15 +28,19 @@ This service plays a critical role in the demo-apps domain, serving as a foundat
 
 - **Runtime**: `typescript-nestjs`
 - **Container Port**: `3000`
-- **Health Check**: `/health`
+- **Endpoints**:
-- **Metrics Endpoint**: `/metrics` (Prometheus format)
+  - `/api/items` for CRUD operations
-- **Image Registry**: Azure Container Registry (`bstagecjotdevacr`)
+  - `/health` for health checks
-
+  - `/metrics` for Prometheus metrics
-The deployment flow is managed through Gitea Actions workflows:
+- **Deployment Flow**:
-1. **build-push.yml**: Builds and tests the application, then pushes the container image to Azure Container Registry.
+  - Push to `dev`, `staging`, or `prod` triggers CI/CD workflows:
-2. **deploy-humanitec.yml**: Deploys the service to AKS via Humanitec using Score files.
+    - `build-push.yml`: Builds and tests the application, then pushes the container image to Azure Container Registry.
-
+    - `deploy-humanitec.yml`: Deploys the service to AKS using Humanitec's API.
-Promotions between environments (`dev`, `staging`, `prod`) are triggered through Backstage's CI/CD tab, ensuring controlled and gated deployments.
+- **Branch Model**:
+  - `dev`: Active development, auto-deploys to the dev environment.
+  - `staging`: Pre-production, promoted from `dev` via PR.
+  - `prod`: Production, promoted from `staging` via PR.
+  - `main`: System of record, receives merges from `prod`.
 
 ## Configuration
 
@@ -46,27 +50,25 @@ Promotions between environments (`dev`, `staging`, `prod`) are triggered through
 | `health_path`    | `/health`      |
 | `container_port` | `3000`         |
 
-Environment-specific configurations are managed via Humanitec and Score files. Additional configuration details can be found in `.platform/config.yaml`.
-
 ## Operations
 
 ### Deployment Steps
-1. Push changes to the `dev` branch for automatic deployment to the development environment.
+
-2. Open a PR for promotion to `staging` or `prod`. Ensure CI tests pass and obtain one approval before merging.
+1. Push changes to the `dev` branch for automatic deployment to the dev environment.
-3. Use Backstage's CI/CD tab to trigger environment promotions.
+2. Open a PR to promote changes from `dev` to `staging`. Ensure CI tests pass and obtain one approval.
+3. Open a PR to promote changes from `staging` to `prod`. Ensure CI tests pass and obtain one approval.
+4. Merge changes from `prod` to `main` for system-of-record updates.
 
 ### Runbook Notes
-- Monitor the `/health` endpoint for service health.
-- Use `/metrics` for Prometheus-based observability.
-- Refer to `.gitea/workflows/` for CI/CD pipeline configurations.
 
-<!-- TODO: FILL IN -->
+- Monitor `/health` for service status.
+- Use `/metrics` for Prometheus-based observability.
+- For load testing, refer to the K6 configuration in the `dev` namespace.
 
 ## Observability
 
 - **Grafana Dashboard**: [Opentelemetry Application Observability](https://grafana.kyndemo.live/d/otel-app-observability-v2/opentelemetry-application-observability?orgId=1&var-app=sonar-test-nest4)
-- **Prometheus Metrics**: Enabled (`/metrics` endpoint)
+- **Prometheus Metrics**: Enabled at `/metrics` on port `3000`.
-- **Alerting**: Configured via Grafana with label selector `app=sonar-test-nest4`
 
 ## Dependencies
 

catalog/component/default/sonar-test-nest4/_meta.json

@@ -0,0 +1,13 @@
+{
+  "sourceShas": {
+    "catalog-info.yaml": "5c2be634ddfec05ec6fed8c7b85cb2c8b9ab3c13",
+    ".platform/initialized.md": "24a574f77ac17059b313a824398b9bb19263232e",
+    "README.md": "b1f5c8dec0bf22d85c71f5049fb595bf1faa891c",
+    "docs/api.md": "86776bdd5e2fbe634709920102282ed589927c5b",
+    "docs/architecture.md": "6d022a6fee34ee24f7274bb18396d1c107be0c17",
+    "docs/index.md": "81f0ec2243665ad41daf93202c872cfc023eb21a"
+  },
+  "promptVersion": "1.0",
+  "generatedAt": "2026-05-15T15:21:17+00:00",
+  "contentHash": "c8f2f45262bf333754d6cb5a5e1e036b7ad2ceb7ec42d6618d086454aca34cad"
+}