initial commit

Change-Id: I11e12d8d4c914eabdc30ba4d8be494fd09b617a3

docs/api.md

@@ -0,0 +1,91 @@
+# API Reference
+
+Base URL: `https://test-alex-2.kyndemo.live`
+
+## Items Resource
+
+### GET /api/items
+List all items.
+
+**Response 200**
+```json
+[
+  { "id": 1, "name": "Widget", "description": "A demo widget" }
+]
+```
+
+---
+
+### POST /api/items
+Create a new item.
+
+**Request body**
+```json
+{ "name": "Widget", "description": "A demo widget" }
+```
+
+**Response 200**
+```json
+{ "id": 1, "name": "Widget", "description": "A demo widget" }
+```
+
+---
+
+### GET /api/items/{id}
+Get a single item.
+
+**Path params**: `id` (integer)
+
+**Response 200**
+```json
+{ "id": 1, "name": "Widget", "description": "A demo widget" }
+```
+
+**Response 500** — item not found (throws `NoSuchElementException`)
+
+---
+
+### PUT /api/items/{id}
+Update an existing item.
+
+**Path params**: `id` (integer)
+
+**Request body** (partial update supported)
+```json
+{ "name": "Updated Widget" }
+```
+
+**Response 200**
+```json
+{ "id": 1, "name": "Updated Widget", "description": "A demo widget" }
+```
+
+---
+
+### DELETE /api/items/{id}
+Delete an item.
+
+**Response 200**
+```json
+{ "deleted": 1 }
+```
+
+---
+
+## Health & Observability
+
+### GET /actuator/health
+Spring Boot liveness check.
+
+```json
+{ "status": "UP" }
+```
+
+### GET /actuator/health/liveness
+Kubernetes liveness probe target.
+
+### GET /actuator/health/readiness
+Kubernetes readiness probe target.
+
+### GET /actuator/prometheus
+Prometheus-format metrics for scraping by Prometheus or Grafana Agent.

docs/architecture.md

@@ -0,0 +1,51 @@
+# Architecture
+
+## Overview
+
+`test-alex-2` is a stateless microservice built with **Spring Boot 3.2** and **Java 17**, deployed to **AKS** via the **Humanitec** platform using a **Score** workload descriptor.
+
+## Components
+
+| Component | Technology | Notes |
+|-----------|-----------|-------|
+| Web layer | Spring MVC `@RestController` | `ItemsController` |
+| Metrics | Micrometer + Prometheus | `/actuator/prometheus` |
+| Health | Spring Boot Actuator | Liveness + readiness probes |
+| Image registry | Azure Container Registry | Per-environment tags |
+| Runtime | AKS (via Humanitec) | Score-driven deployment |
+
+## Deployment Flow
+
+```
+Developer pushes to main
+        │
+        ▼
+Gitea Actions: build-push.yml
+  - mvn package
+  - docker build
+  - az acr login (OIDC / Workload Identity)
+  - docker push → ACR
+        │
+        ▼
+Gitea Actions: deploy-humanitec.yml  (triggers on build-push success)
+  - humctl score deploy
+    --org  skillful-wild-chicken-2617
+    --app  test-alex-2
+    --env  
+        │
+        ▼
+Humanitec creates / updates Deployment
+        │
+        ▼
+AKS Pod running test-alex-2 image
+```
+
+## Security
+
+- **No static credentials** — CI uses OIDC federated identity to authenticate against Azure ACR
+- **Humanitec token** stored in a Gitea repository secret (injected by the golden-path scaffolder)
+- **Non-root container** — Dockerfile creates a dedicated `appuser`
+
+## Scalability
+
+The Score workload descriptor defines CPU/memory requests/limits. Humanitec and AKS HPA can scale the deployment automatically based on Prometheus metrics.

docs/index.md

@@ -0,0 +1,46 @@
+# test-alex-2
+
+test-alex-2
+
+## Overview
+
+This service was scaffolded from the **Create Microservice** golden-path template on the Kyndryl Platform.
+
+- **Runtime**: Java 17 · Spring Boot 3.2
+- **Owner**: group:default/platform-engineering
+- **Deployment profile**: `stateless`
+
+## Architecture
+
+See [architecture.md](architecture.md) for the full architecture diagram.
+
+At a glance:
+
+```
+┌──────────────────────────────────────┐
+│  Gitea Actions CI/CD                 │
+│  ┌─────────────┐  ┌───────────────┐  │
+│  │ build-push  │→ │ deploy-       │  │
+│  │ .yml        │  │ humanitec.yml │  │
+│  └─────────────┘  └───────────────┘  │
+└──────────────────────────────────────┘
+          │                │
+          ▼                ▼
+       Azure ACR     Humanitec API
+                          │
+                          ▼
+                   AKS (via Score)
+                          │
+                          ▼
+              ┌─────────────────────┐
+              │  test-alex-2  │
+              │  :8080               │
+              │  /api/items          │
+              │  /actuator/health    │
+              │  /actuator/prometheus│
+              └─────────────────────┘
+```
+
+## API Reference
+
+See [api.md](api.md) for the full OpenAPI reference.