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"]| 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¶
- Copy the ADR template.
- Number it sequentially (
NNNN-short-title.md). - Fill in Context, Decision, Status, Consequences, and Alternatives.
- Link related ADRs and the principle/architecture pages it affects.
- 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 |
| 0012 | Messaging port with transport profiles (amends 0003) | Accepted 2026-10-09 |
| 0013 | Vector store as a retrieval profile (amends 0005) | Accepted 2026-10-09 |
| 0014 | Run identity and lifecycle envelopes (amends 0010) | Accepted 2026-10-09 |
| 0015 | Factory tenancy and scope under canonical ADR-0100 (amends 0011) | Accepted 2026-10-09 |
| 0016 | Architecture meta-model: planes, platforms, bounded contexts, services | Accepted 2026-10-09 |
| 0017 | Deployment profiles (saas-default, hybrid, on-prem, hybrid-compute) | Accepted 2026-10-09 |
| 0018 | NFR baseline for the pilot class | Accepted 2026-10-09 |
| 0019 | Data governance: regions, classification, retention, deletion, export | Accepted 2026-10-09 |
| 0020 | Commercial model on the SaaS templates | Accepted 2026-10-09 |
| 0021 | Evaluation-driven release gates | Accepted 2026-10-09 |
| 0022 | MCP as the tool, resource and prompt protocol | Accepted 2026-10-09 |
| 0023 | A2A as the agent-to-agent interoperability surface | Accepted 2026-10-09 |
| 0024 | Durable execution substrate: Orleans grains with the Agent Framework as adapter | Accepted 2026-10-12 |
| 0025 | SaaS descriptors are imported into blueprints; the recipe path is the single generation contract (closes Q-22) | Accepted 2026-10-14 |
| 0026 | Requirements-to-UX handoff: typed input bundle, Reviewer-approved alignment memo, readiness activation in the Workflow Engine, two UX passes | Accepted 2026-10-23, amended 2026-10-26 (D63–D64: readiness activation for every event-started definition, alignment after discovery, blueprint-submit-version shared-write) |
2026-10 review¶
All eleven original ADRs were reassessed against the repositories on 2026-10-09 (see handoffs/2026-10-09-independent-review/adr-dispositions.md). Each carries a dated review note under its header. Their Date field (2026-01-01) is the value from the 2026-06-17 bulk commit that introduced them, not an approval date; no retrospective date was invented.
| Disposition | ADRs |
|---|---|
| Retained with clarification | 0001, 0002, 0004 (IaC verified: Pulumi programs, zero Bicep), 0006, 0007, 0008, 0009 |
| Amended (original stays in force except where the amendment changes it) | 0003 → 0012, 0005 → 0013, 0010 → 0014, 0011 → 0015 (all accepted 2026-10-09) |
| New decisions of the full design plan (accepted 2026-10-09) | 0016 meta-model, 0017 deployment profiles, 0018 NFR baseline, 0019 data governance, 0020 commercial model, 0021 quality gates, 0022 MCP, 0023 A2A; 0024 durable execution substrate accepted 2026-10-12; 0025 SaaS descriptor import accepted 2026-10-14; 0026 requirements-to-UX handoff accepted 2026-10-23 |
Binding canonical decisions in ConnectSoft.Documentation apply in addition to this index: ADR-00xx (template layering and submodules), ADR-0100 (SaaS multitenancy resolution) and ADR-0101 (Identity Platform). They are not renumbered here; Factory ADRs reference them. A shared AI/messaging decision is proposed for the canonical repository with a Factory supplement (user decision D10).