initial commit

Change-Id: I732e7af790c42cbd6fc2c2e754882fef44f90c00

docs/.pages

@@ -0,0 +1,4 @@
+nav:
+  - Home: index.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-argocd-gitops-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/index.md

@@ -0,0 +1,81 @@
+# test-argocd-gitops-c6
+
+Deployed from **https://github.com/spring-projects/spring-petclinic** via the Backstage Hello Demo template.
+
+| Property | Value |
+|---|---|
+| **Environment** | `dev` |
+| **Namespace** | `demo-apps` |
+| **ArgoCD Project** | `veterinary-platform` |
+| **Branch** | `main` |
+| **Observability** | Enabled (OpenTelemetry) |
+
+## Quick Links
+
+- **Repository**: [https://gitea.kyndemo.live/validate/test-argocd-gitops-c6](https://gitea.kyndemo.live/validate/test-argocd-gitops-c6)
+- **ArgoCD**: [https://argocd.kyndemo.live/applications/test-argocd-gitops-c6](https://argocd.kyndemo.live/applications/test-argocd-gitops-c6)
+- **Live App**: [https://test-argocd-gitops-c6.kyndemo.live](https://test-argocd-gitops-c6.kyndemo.live)
+
+- **Grafana Dashboard**: [https://grafana.kyndemo.live/d/otel-app-observability-v2/...?var-app=test-argocd-gitops-c6](https://grafana.kyndemo.live/d/otel-app-observability-v2/opentelemetry-application-observability?orgId=1&var-app=test-argocd-gitops-c6)
+
+
+## Architecture
+
+This service was scaffolded using the **Application Migration Factory** Backstage template.
+
+**Deployment flow:**
+
+1. Source cloned from `https://github.com/spring-projects/spring-petclinic`
+2. Catalog entity and CI workflows overlaid by Backstage
+
+3. The Watcher scanned the repository and injected OpenTelemetry auto-instrumentation via Kustomize overlay
+
+4. ArgoCD Application created targeting the `demo-apps` namespace
+5. ArgoCD continuously syncs from the `main` branch
+
+**ArgoCD sync path:** `overlays/otel`
+
+## Development Workflow
+
+```bash
+git clone https://gitea.kyndemo.live/validate/test-argocd-gitops-c6.git
+cd test-argocd-gitops-c6
+# make changes, then:
+git add . && git commit -m "your change" && git push origin main
+```
+
+ArgoCD monitors the repository and automatically syncs changes to the `demo-apps` namespace.
+
+## Rollback
+
+To roll back to a previous version:
+
+1. Open the [ArgoCD UI](https://argocd.kyndemo.live/applications/test-argocd-gitops-c6)
+2. Click **History and Rollback**
+3. Select the desired revision and click **Rollback**
+
+Alternatively, revert the commit in Git and push — ArgoCD will auto-sync the rollback.
+
+
+## Observability
+
+This service has OpenTelemetry auto-instrumentation enabled. Traces, metrics, and logs are exported to the OTel Collector and visualised in Grafana.
+
+**Viewing telemetry:**
+
+- Open the [Grafana Dashboard](https://grafana.kyndemo.live/d/otel-app-observability-v2/opentelemetry-application-observability?orgId=1&var-app=test-argocd-gitops-c6)
+- Filter by `app=test-argocd-gitops-c6` to see service-specific data
+- Check the **Alerts** tab in Backstage for any firing Grafana alerts
+
+**OTel Collector endpoint:** `http://otel-collector.monitoring.svc.cluster.local:4318`
+
+
+## SLOs and Monitoring
+
+Define your service level objectives here once the service is stable:
+
+| SLI | Target | Dashboard |
+|---|---|---|
+| Availability | 99.9% | [Grafana](https://grafana.kyndemo.live) |
+| Latency (p99) | < 500ms | [Grafana](https://grafana.kyndemo.live) |
+| Error rate | < 1% | [Grafana](https://grafana.kyndemo.live) |

docs/runbooks/.pages

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

docs/runbooks/index.md

@@ -0,0 +1,55 @@
+# Runbooks
+
+Operational runbooks for **test-argocd-gitops-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 template:
+
+```
+# Runbook: <Scenario Name>
+
+**Severity:** P1 / P2 / P3
+**Trigger:** <What symptom or alert brings an engineer here>
+**Owner:** <Team name>
+**Last tested:** YYYY-MM-DD
+
+---
+
+## Prerequisites
+
+- Access to ...
+- Permissions for ...
+
+## Steps
+
+1. Confirm the symptom by checking ...
+2. ...
+3. ...
+
+## Verification
+
+After completing the steps, verify the issue is resolved by ...
+
+## Escalation
+
+If this runbook does not resolve the issue within _N_ minutes, escalate to ...
+
+## Post-incident
+
+Open a post-mortem ticket and link it here.
+```