Architecture Integrity
Architecture should reduce the cost of known change, not speculate about every future possibility. Preserve ownership, dependency direction, invariants, and clear boundaries; do not redesign unrelated layers to make a local change look cleaner.
Decision frame
- Which current and expected use cases must the design serve? Which quality attributes matter here: reliability, security, latency, scale, operability, portability, cost?
- What is the smallest boundary that localizes change without hiding essential behavior?
- Which option is easiest to test, observe, migrate, and remove?
- Start from requirements, trust boundaries, failure modes, deployment constraints, and the existing sources of truth.
Design rules
- Keep domain policy separate from transport, storage, framework, and vendor adapters.
- Depend toward stable contracts. Avoid circular dependencies, shared mutable authority, duplicated business rules, and cross-domain database ownership.
- Make ownership of data, transactions, retries, timeouts, and cleanup explicit.
- Do not introduce a service, queue, cache, datastore, framework, or abstraction unless the existing architecture cannot meet the requirement cleanly. Prefer boring, existing technology.
- Model failure, recovery, operability, and ownership, not only the happy path. Keep distributed systems no more complex than necessary.
- Design migrations for mixed versions, rollback, and partial failure. Add observability at boundaries where failures would otherwise be ambiguous.
Record the decision
Write an ADR in the repository's established mechanism when the choice affects multiple components, introduces infrastructure or a dependency, changes a public contract, has meaningful alternatives, or will be costly to reverse. Capture context, decision, alternatives, consequences, migration, and rollback. Do not turn the ADR into a tutorial.
Verify
Validate the architecture against implementation reality before claiming compliance: imports and dependency direction, ownership of data and transactions, and the actual deployment topology. A diagram that does not match the code is a finding.
Output
## Design: <scope>
Requirements & constraints: ...
Options considered: <A> / <B> — chosen <X> because ...
Boundaries & ownership: ...
Failure & migration model: ...
ADR: <path or "not needed because ...">
1---2name: architecture-integrity3description: >-4 Design or change system structure without breaking invariants: module and5 domain boundaries, dependency direction, new services, queues, caches,6 datastores, or frameworks, and lasting trade-offs recorded as ADRs. Use when7 a change crosses components, introduces a durable boundary, or is hard to8 reverse.9license: MIT10metadata:11 source: https://skillmd.com/skills/al-janef/architecture-integrity12---1314# Architecture Integrity1516Architecture should reduce the cost of known change, not speculate about every future possibility. Preserve ownership, dependency direction, invariants, and clear boundaries; do not redesign unrelated layers to make a local change look cleaner.1718## Decision frame1920- Which current and expected use cases must the design serve? Which quality attributes matter here: reliability, security, latency, scale, operability, portability, cost?21- What is the smallest boundary that localizes change without hiding essential behavior?22- Which option is easiest to test, observe, migrate, and remove?23- Start from requirements, trust boundaries, failure modes, deployment constraints, and the existing sources of truth.2425## Design rules2627- Keep domain policy separate from transport, storage, framework, and vendor adapters.28- Depend toward stable contracts. Avoid circular dependencies, shared mutable authority, duplicated business rules, and cross-domain database ownership.29- Make ownership of data, transactions, retries, timeouts, and cleanup explicit.30- Do not introduce a service, queue, cache, datastore, framework, or abstraction unless the existing architecture cannot meet the requirement cleanly. Prefer boring, existing technology.31- Model failure, recovery, operability, and ownership, not only the happy path. Keep distributed systems no more complex than necessary.32- Design migrations for mixed versions, rollback, and partial failure. Add observability at boundaries where failures would otherwise be ambiguous.3334## Record the decision3536Write an ADR in the repository's established mechanism when the choice affects multiple components, introduces infrastructure or a dependency, changes a public contract, has meaningful alternatives, or will be costly to reverse. Capture context, decision, alternatives, consequences, migration, and rollback. Do not turn the ADR into a tutorial.3738## Verify3940Validate the architecture against implementation reality before claiming compliance: imports and dependency direction, ownership of data and transactions, and the actual deployment topology. A diagram that does not match the code is a finding.4142## Output4344```45## Design: <scope>46Requirements & constraints: ...47Options considered: <A> / <B> — chosen <X> because ...48Boundaries & ownership: ...49Failure & migration model: ...50ADR: <path or "not needed because ...">51```