avd-opsArchitecture
How the AVD repos fit together
Three repos are the foundation: what it is, what it should be, and how we build it. Two more sit on top and automate it, so it gets smarter over time. Nothing in the foundation needs the layer above it.
- Built on my own time for research and learning. Not affiliated with, endorsed by or supported by my employer or Microsoft.
- Don't run any of it in production or against tenants that matter. Test in a dedicated lab subscription and tenant first.
- Provided "as is", without warranty of any kind, under each repo's license. You use it at your own risk and own the Azure charges it incurs.
- Contributions and forks are welcome and encouraged. See Contribute.
The layers
Read it from the bottom up. Three repos are the foundation. The layer on top automates it and makes it smarter over time.
avd-ops: where to start. The map of the repos, what each one does and how they connect. Each repo stays the source of truth for itself.
Makes it smart: avd-second-brain
Remembers why the environment is the way it is, over its whole life, and learns from every change. It thinks; it never holds a write credential.
Automates it: avd-swarm
Agents run the work. They read freely and change nothing until a person approves the exact plan, with one kill switch only the owner resets. The avd-buddy chat lives here.
The top layer builds on the foundation. The foundation never needs it.
What it is: avd-current-state
Read-only collection and validation, offline: what is in the environment today, and whether a deployment landed correctly.
What it should be: avd-assess
The target, and why: a research index that links out to Microsoft's published guidance, pinned, and writes new method only for a gap.
How we build it: avd-landing-zone
Builds the landing zone in Bicep and changes it from here, through the portal-guided Cloud Shell flow, with preflight checks, cleanup and same-tenant DR.
What it is and How we build it work on their own, with no brain and no swarm.
What moves between them
The repos don't share code. They pass versioned contracts, each with one schema in avd-second-brain. Solid arrows are the family's own paths; dashed ones are optional.
The contracts
| Contract | From, to | What it carries | Today |
|---|---|---|---|
| C11 facts | avd-current-state to avd-second-brain | A redacted snapshot of the estate: counts, public values and pseudonyms, never names. | Built |
| C14 target state | The target design to avd-landing-zone | The manifest of what to build. The landing zone reads it and refuses anything it doesn't list. | Built |
| C17 run record | avd-landing-zone to avd-second-brain | What a deployment run did, what it cost, and where to resume. | Specified, being built |
| C18 lifecycle record | Inside avd-second-brain | One record per environment: use cases, decisions with the alternatives turned down, and every event from birth to retirement, linked to C14, C17 and C10. | Draft |
| C9 plans, C10 outcomes | avd-second-brain and avd-swarm | A proposed change with its evidence and its reason, and what happened after a person approved or refused it. | Draft |
| C19, C20, C21 | avd-assess method, avd-current-state, avd-second-brain | Intake answers, check rules, and the assessment report. | Planned |
Full definitions: contracts in avd-second-brain.
Optional pieces from outside
- Microsoft's published guidance (Microsoft Learn, the Well-Architected Reliability Assessment, the AVD review checklist) is linked and pinned by avd-assess, not copied or rewritten.
- Azure SRE Agent can run beside avd-swarm as an optional add-on. avd-swarm doesn't depend on it.