initial commit

Change-Id: Ia7bbd259893786bfd9076bffb8c9e973288defde

docs/.pages

@@ -0,0 +1,6 @@
+nav:
+  - Home: index.md
+  - Architecture: architecture.md
+  - API Reference: api.md
+  - Runbooks: runbooks
+  - Architecture Decisions: adr

docs/adr/.pages

@@ -0,0 +1,4 @@
+title: Architecture Decisions
+nav:
+  - index.md
+  - ...

docs/adr/index.md

@@ -0,0 +1,61 @@
+# Architecture Decision Records
+
+This directory tracks Architecture Decision Records (ADRs) for **test-ms-c6**.
+
+ADRs capture the context, trade-offs, and consequences of significant technical choices. They are lightweight documents — typically one to two pages — following the [MADR format](https://adr.github.io/madr/).
+
+## Why ADRs?
+
+- **Preserve context**: Future engineers understand *why* a decision was made, not just what was decided.
+- **Reduce re-litigation**: A documented decision stops teams re-debating the same trade-offs every quarter.
+- **Accelerate onboarding**: New team members read ADRs to understand the service's evolution without archaeology.
+
+## Index
+
+| # | Title | Status | Date |
+|---|-------|--------|------|
+| *(add entries here as ADRs are created)* | | | |
+
+## Creating a new ADR
+
+1. Copy the template below into `docs/adr/NNNN-<short-title>.md` where `NNNN` is the next sequential number.
+2. Fill in every section — even if the answer is "not applicable, because...".
+3. Open a pull request so the team can review the decision **before** it is finalized.
+4. Update the index table above once the ADR is accepted.
+
+---
+
+## ADR Template
+
+```
+# NNNN. <Short imperative title of the decision>
+
+Date: YYYY-MM-DD
+Status: Proposed | Accepted | Deprecated | Superseded by [NNNN](NNNN-<title>.md)
+
+## Context and problem statement
+
+Describe the problem or question that drove this decision.
+
+## Decision drivers
+
+- Driver 1
+- Driver 2
+
+## Considered options
+
+- **Option A** — brief description
+- **Option B** — brief description
+
+## Decision outcome
+
+Chosen option: **Option X**, because ...
+
+### Positive consequences
+
+- ...
+
+### Negative consequences
+
+- ...
+```

docs/api.md

@@ -0,0 +1,20 @@
+# API Reference
+
+Base URL: `https://test-ms-c6.kyndemo.live`
+
+## Items `/api/items`
+
+| Method | Path | Body | Response |
+|--------|------|------|----------|
+| GET | `/api/items` | — | Array of items |
+| POST | `/api/items` | `{"name":"...","description":"..."}` | Created item (201) |
+| GET | `/api/items/{id}` | — | Item or 404 |
+| PUT | `/api/items/{id}` | `{"name":"...","description":"..."}` | Updated item |
+| DELETE | `/api/items/{id}` | — | `{"deleted":id}` |
+
+## Observability
+
+| Path | Description |
+|------|-------------|
+| `/actuator/health` | Health check — `{"status":"UP"}` |
+| `/metrics` | Prometheus exposition format |

docs/architecture.md

@@ -0,0 +1,30 @@
+# Architecture
+
+`test-ms-c6` is a `java-springboot` service.
+
+| Component | Detail |
+|-----------|--------|
+| Runtime | `java-springboot` |
+| Container port | `8080` |
+| Health check | `/actuator/health` |
+| Metrics | `/metrics` (Prometheus format) |
+| Image | Azure Container Registry (`bstagecjotdevacr`) |
+
+## Deployment flow
+
+```
+Push to dev/staging/prod
+  → build-push.yml  (build + test → push image to ACR)
+  → deploy-humanitec.yml (hctl score deploy)
+```
+
+## Branch model
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | System of record — catalog, docs, score.yaml, platform config |
+| `dev` | Active development |
+| `staging` | Pre-production (lazy-created on first promote) |
+| `prod` | Production (lazy-created on first promote) |
+
+Promotions between environments are triggered from the Backstage CI/CD tab.

docs/index.md

@@ -0,0 +1,45 @@
+# test-ms-c6
+
+test-ms-c6
+
+## Overview
+
+This service was scaffolded from the **Create Microservice** golden-path template on the Kyndryl Platform.
+
+- **Runtime**: `java-springboot`
+- **Owner**: group:default/platform-lead
+- **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-ms-c6        │
+              │  :8080     │
+              │  /api/items              │
+              │  /actuator/health         │
+              └──────────────────────────┘
+```
+
+## API Reference
+
+See [api.md](api.md) for the full OpenAPI reference.

docs/runbooks/.pages

@@ -0,0 +1,4 @@
+title: Runbooks
+nav:
+  - index.md
+  - ...

docs/runbooks/index.md

@@ -0,0 +1,28 @@
+# Runbooks
+
+Operational runbooks for **test-ms-c6**.
+
+Each runbook documents a specific procedure — incident response, rollback steps, scaling operations, or routine maintenance — so that on-call engineers can resolve issues safely and quickly without deep system knowledge.
+
+## How to use these runbooks
+
+1. **Identify the scenario** — check the index below or use the search bar at the top of the page.
+2. **Follow each step exactly** — runbooks are written to be safe to execute under pressure.
+3. **Record deviations** — if you had to improvise, open a pull request to update the runbook so the next engineer benefits.
+
+## Index
+
+| Runbook | Trigger / Alert | Severity |
+|---------|-----------------|----------|
+| *(add runbooks below)* | | |
+
+## Creating a new runbook
+
+Add a file `docs/runbooks/<scenario-name>.md` using this structure:
+
+**Severity:** P1 / P2 / P3
+**Trigger:** What symptom or alert brings an engineer here
+**Owner:** Team name
+**Last tested:** YYYY-MM-DD
+
+Include the following sections: Prerequisites, Steps (numbered), Verification, Escalation, Post-incident.