Architecture Decision Records

Lightweight, numbered, immutable records of architectural decisions that govern the shared foundation plus the Azure Local and Hyper-V platform tracks.

These are project-scoped ADRs. Org-wide platform standards live in AzureLocal/platform/decisions/.

Design lane scope map

The early accepted ADRs were written for the Azure Local baseline. They do not automatically govern Hyper-V simply because both products use SCOM or share health terminology.

Design lane	Governing decisions
Shared portfolio architecture	ADRs 0020, 0021, 0024, and 0030
Shared SCOM product boundaries	ADR 0022 requires independent runtime products; ADR 0026 requires platform-owned DAs
Azure Local platform baseline	ADRs 0001–0003, 0007–0009, and 0014–0018
Azure Local SCOM	ADRs 0004, 0005, 0011, 0022, and 0026
Azure Local Azure Monitor	ADRs 0006, 0010, 0012, 0013, and 0019
Hyper-V platform and SCOM	Accepted ADRs 0022, 0025, and 0026 plus proposed ADRs 0027–0029 and 0031 for package, object/discovery, health/DA, and authoring-toolchain architecture
Hyper-V Azure Monitor	ADR 0023, proposed go/defer/no-go gate

Cross-cutting lifecycle ADRs can provide reusable patterns, but each platform and delivery lane must still validate its applicable topology, dependencies, artifacts, tests, and release contract.

Index

#	Title	Status
0001	Scope & topology — Azure Local infrastructure (3 layers, ~27 entities)	Accepted
0002	Primary signal source — Azure Local PowerShell APIs + ARM/Resource Graph	Accepted
0003	Health rollup policy — worst-state default with documented exceptions	Accepted
0004	SCOM discovery strategy — PowerShell Discovery (not WMI)	Accepted
0005	SCOM class hierarchy + hosting relationships (3-layer model)	Accepted
0006	Azure Monitor entity model alignment (mirrors SCOM 1:1)	Accepted
0007	Naming convention — cross-track parity	Accepted
0008	Customization strategy — sealed MP + override pack tiers; Bicep params + tiers	Accepted
0009	Alert vs health-state separation policy	Accepted
0010	Cloud-side prerequisites contract (HCI Insights, AMA, DCMA, Service Group, RBAC, networking)	Accepted
0011	L3 Azure-side scope: agent-local Arc health checks (Tier A) vs. management server ARM probes (Tier B)	Accepted
0012	Azure Monitor Workspace vs Log Analytics Workspace: metrics routing for the health model (dual-topology support)	Accepted
0013	Azure Monitor Health Model deployment strategy — Bicep-first, portal-bootstrap	Accepted
0014	CI/CD pipeline strategy — GitHub Actions, OIDC, release-please	Accepted
0015	Testing strategy — 5-layer pyramid, cross-track parity gate	Accepted
0016	Signing & secrets management — two-key MP signing, OIDC SPNs	Accepted
0017	Versioning & release policy — single repo SemVer, Conventional Commits, mike docs	Accepted
0018	Self-observability — monitor the monitoring pipeline as a parallel root branch	Accepted
0019	Cost, scale, and data retention — per-tier ingestion envelopes, sharding, retention policy	Accepted
0020	Documentation platform — VitePress with Mermaid and GitHub Pages	Accepted
0021	Platform-first architecture — Azure Local and Hyper-V, split by SCOM and Azure Monitor delivery surfaces	Accepted
0022	Independent SCOM packaging — no shared runtime MP dependencies	Accepted
0023	Hyper-V Azure Monitor through Arc-enabled SCVMM — go, defer, or no-go gate	Proposed
0024	Repository and publishing identity — Hybrid Solutions Cloud and labs.hybridsolutions.cloud	Accepted
0025	Hyper-V network-management authority — prefer Network ATC when eligible; distinguish SCVMM/SDN and manual paths	Accepted
0026	Platform-owned SCOM Distributed Applications — separate Azure Local and Hyper-V service roots	Accepted
0027	Hyper-V SCOM Management Pack decomposition — modular sealed product suite and customer override boundary	Proposed
0028	Hyper-V object and discovery architecture — stable mobility identity, staged discovery, and cookdown	Proposed
0029	Hyper-V health, alert, and DA rollup — evidence-driven state, actionable alerts, and topology-aware service health	Proposed
0030	Platform-first source tree — Azure Local and Hyper-V, each split into SCOM and Azure Monitor solution roots	Accepted
0031	Hyper-V Management Pack authoring toolchain — canonical XML/fragments, deterministic build, Microsoft verification/sealing, and SCOM lab authority	Proposed

When to write an ADR

• Any architectural choice that affects how the SCOM MP or Azure Monitor health model is built
• Any decision that creates a constraint on Phases 3–6
• Any cross-track parity decision
• Any decision the next maintainer would otherwise have to re-litigate

Format

See template.md. Numbered sequentially, ZERO-padded to four digits. Filename is NNNN-kebab-case-title.md. Once an ADR is Accepted it is immutable — supersede it with a new ADR rather than editing it in place.

Workflow

1. Open a PR adding the ADR with status Proposed
2. Discuss and refine in PR review
3. Merge with status Accepted once consensus reached
4. If later overturned, write a successor ADR and mark this one Superseded by ADR XXXX