initial commit

Change-Id: I860821ca882fd9717c02879c18a7d9049a089aaa

docs/adr/index.md

@@ -0,0 +1,61 @@
+# Architecture Decision Records
+
+This directory tracks Architecture Decision Records (ADRs) for **petclinic-demo-andrej-doc**.
+
+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
+
+- ...
+```