Architecture Decision Records, or ADRs, are short documents that capture important architectural choices. Carrier makes ADRs more useful because many architectural decisions have direct expression in source and generated metadata. The ADR becomes more than narrative — it becomes connected to evidence.
Capturing Service Boundaries
A service boundary decision should explain what the service owns and what it deliberately does not own. Good service-boundary ADRs prevent the boundary from being rediscovered in every design review. They name the business capability, the primary models, the routes exposed, the modules imported, the systems explicitly outside the boundary, and the team responsible.
Capturing Policy Decisions
Policy decisions deserve explicit records because they shape security behavior. A good policy decision is not only clinicians can view patients — it is more precise: clinicians can view patients assigned to their organization or care relationship, administrative users can view within tenant scope, and break-glass access requires audit.
Capturing Data Ownership
Data ownership ADRs are essential when multiple systems use the same business concept. Carrier models make ownership visible: the service that declares the model owns the persistent representation. But enterprise ecosystems often include derived copies, reporting stores, integration caches, and legacy systems. ADRs should explain the difference.
Linking ADRs to Generated Manifests
Carrier-generated metadata can make ADRs verifiable. An ADR can reference .carrier/manifest.json, openapi.json, and generated migrations. The ADR should not duplicate all generated detail. Instead, it should link the architectural decision to the generated evidence that proves how the system currently expresses it. This gives architecture governance a practical feedback loop.