Skip to content

Architecture Decision Records

An Architecture Decision Record (ADR) captures a single significant architectural decision: its context, the decision taken, its status, and its consequences. ADRs make the why behind the architecture durable and auditable, so future contributors (human and agent) understand the reasoning rather than re-litigating settled choices.

Why ADRs in an AI factory

The factory generates software autonomously. ADRs are the canonical record of the constraints the agents operate under — they ground the Architecture Principles and the technology choices baked into templates and generation. The Architecture Decision Record Agent proposes and maintains ADRs as part of the workflow.

Status lifecycle

flowchart LR
    proposed["Proposed"] --> accepted["Accepted"]
    proposed --> rejected["Rejected"]
    accepted --> deprecated["Deprecated"]
    accepted --> superseded["Superseded"]
    superseded --> newadr["New ADR"]
Hold "Alt" / "Option" to enable pan & zoom
Status Meaning
Proposed Under discussion; not yet binding.
Accepted The decision is in force and binding on the architecture.
Rejected Considered and explicitly not adopted.
Deprecated No longer recommended but not yet replaced.
Superseded Replaced by a later ADR (linked).

How to add an ADR

  1. Copy the ADR template.
  2. Number it sequentially (NNNN-short-title.md).
  3. Fill in Context, Decision, Status, Consequences, and Alternatives.
  4. Link related ADRs and the principle/architecture pages it affects.
  5. Add it to the index table below and to the nav.

Index

ADR Decision Status
0001 .NET 10 as the backend platform Accepted
0002 Microsoft Agent Framework over Semantic Kernel Accepted
0003 MassTransit on Azure Service Bus as primary messaging Accepted
0004 Pulumi over Bicep for Infrastructure as Code Accepted
0005 Qdrant as the primary vector store Accepted
0006 NHibernate as the primary ORM Accepted
0007 Blazor micro-frontend (MFE) for the Studio Accepted
0008 OpenIddict for identity and OAuth2/OIDC Accepted
0009 Clean Architecture + DDD for services Accepted
0010 Event-driven architecture with a canonical envelope Accepted
0011 Shared-with-tenant-guard multi-tenancy model Accepted