Architecture Decisions
This register distinguishes accepted architecture from implementation backlog and research. Accepted decisions remain in force until a later record supersedes them.
Accepted
Section titled “Accepted”| ID | Decision | Consequence |
|---|---|---|
| AD-001 | Delivery uses S0-S22: SQL VM first; Azure SQL; managed, VM, and containerized PostgreSQL; Bicep; Terraform; general Git/CI; then Fabric and later targets | Delivery order is explicit and is not a resource dependency |
| AD-002 | YAML is canonical; precedence is defaults, template, YAML, explicit flags | Every resolved value must carry provenance |
| AD-003 | The normalized plan is versioned, canonical, hashed, and engine-neutral | Approval and evidence bind to one immutable meaning |
| AD-004 | -Plan is deterministic, offline, unauthenticated, and non-mutating |
Unavailable external facts are marked unverified |
| AD-005 | -WhatIf is authenticated, Azure-aware, and non-mutating |
It reports create, reuse, update, replace, conflict, drift, or no-change |
| AD-006 | Core, target providers, capability modules, catalog sources, solution packs, probes, and engines are distinct contracts | Providers do not implement Bicep or Terraform export |
| AD-007 | PowerShell is first; Bicep and Terraform support export and orchestrated apply after stable target contracts and before Fabric delivery | Engine-native previews supplement but do not redefine toolkit WhatIf; Terraform does not depend technically on Bicep |
| AD-008 | Protected interactive runs may use local append-only state, snapshots, locking, and live reconciliation | Resume is idempotent and stops on ambiguity |
| AD-009 | Ownership is owned, adopted, reused, or external |
Unknown, reused, and external resources are never deleted |
| AD-010 | Assessment, migration, cost estimation, deployment, and teardown are separate operations | One result never implies approval for another |
| AD-011 | Reports share a versioned evidence envelope | Console, JSON, Markdown, and HTML are renderings of one record |
| AD-012 | Secrets are references only in YAML, plans, state, logs, and reports | An explicitly selected secret store holds values |
| AD-013 | External triggers may request read-only work or resume an approved run by run ID and idempotency key | Automation cannot bypass approval, spend, secret, sensitivity, licensing, adoption, or teardown controls |
| AD-014 | Catalog and private artifacts use the same provenance, integrity, license, and sensitivity policy | Community content remains optional |
| AD-015 | Every target and solution pack emits secretStoreDecision: deploy or reuse Key Vault, use an approved external store, or justify not applicable |
Key Vault remains a reusable capability; no provider silently ignores secret storage |
| AD-016 | Every Azure VM emits administrativeAccessDecision; Bastion with no public IP is the default |
Reuse or opt-out needs rationale and approval and remains visible in Plan, WhatIf, cost, and security evidence |
| AD-017 | CI, webhook, or other unattended mutation requires encrypted remote state, leases, fencing, resumable events, and OIDC or managed identity | A local file lock cannot coordinate independent runners |
| AD-018 | Assessment is a release requirement where applicable, not a prerequisite for security, planning, cost, or an initial canary | Assessment can mature alongside the target without blocking foundational controls |
Current repository state
Section titled “Current repository state”- The repository contains a scaffold, documentation, and backlog.
- No deployable Azure Data Lab Toolkit cmdlets are present.
- The project is not production ready.
- Azure SQLVM Toolkit is unfinished and is a source of lessons, not a working production baseline.
Implementation backlog
Section titled “Implementation backlog”- Implement the versioned YAML schema and provenance resolver.
- Implement normalized plan canonicalization, validation, and hashing.
- Implement local event state, snapshots, locking, and reconciliation.
- Implement the PowerShell engine and SQL VM provider end to end.
- Implement evidence renderers and HTML output.
- Add Azure SQL Database and SQL MI, then the three PostgreSQL paths.
- Add Bicep, Terraform, and general Git and CI/CD adapters before Fabric.
- Add Fabric workspaces, items, shortcuts, CI/CD, and separately gated solution packs.
- Add governed catalogs, probes, cost, Key Vault, Bastion, and remote state capabilities against the accepted contracts.
Backlog order does not create technical coupling between target providers.
Exploratory
Section titled “Exploratory”- How completely Fabric workspaces, capacities, items, shortcuts, and deployment pipelines can be managed through infrastructure as code.
- Which Fabric capabilities belong in deployment engines versus authenticated data-plane adapters.
- Which remote backend implementations should follow the Azure Blob reference design.
- Which pricing sources and confidence model can support reproducible estimates.
- Which signatures, quarantine, or sandbox controls are practical for each artifact class.
- Which container host should be the first declared containerized PostgreSQL adapter.
Exploratory work must not be presented as supported capability.
Deferred
Section titled “Deferred”- Kubernetes and AKS target providers until a required container workload and its lifecycle contracts pass release.
- Automatic migration workflows.
- General autonomous multi-session execution beyond authenticated resume of an already approved run.
Explicitly outside the baseline
Section titled “Explicitly outside the baseline”- A deployment engine cannot override core policy or silently alter a plan.
- A resource name, resource group, or tag alone cannot establish ownership.
- A trigger, CI identity, or AI session cannot approve its own mutation.
- Production readiness is not inferred from documentation completeness.
Related guidance: Roadmap, Testing, Cost and Lifecycle, and Git and CI/CD.