initial commit

Change-Id: I11e12d8d4c914eabdc30ba4d8be494fd09b617a3

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.