# Core Modular Design
> Every principle in this category is listed as a record.
Page: Ontology · Principles
Canonical: https://banes-lab.com/ontology#architecture-category-core-modular-design
Listed in [Ontology · Principles](https://banes-lab.com/api/pages/ontology/principles.md), after [Portability / Infrastructure / Deployment](https://banes-lab.com/ontology/principles/architecture-category-portability-infrastructure-deployment.md) and before [SOLID / Object-Oriented Design](https://banes-lab.com/ontology/principles/architecture-category-solid-object-oriented-design.md).
Every principle in this category is listed as a record. Each record carries its kind, its severity, the scopes it applies at and the layer it lives in, then the edge relations that join it to other records, the records that point back at it, the contracts that answer to it and the tensions it takes part in. The descriptors say how it is violated, detected, measured, repaired and enforced. Where the record carries one, an exemplar shows the shape before and after the principle is applied.
Relations diagram
The relations inside this category.
```mermaid
flowchart LR
n_single_responsibility["Single Responsibility Principle (SRP)"]
n_separation_of_concerns["Separation of Concerns"]
n_duplicate_code["Do Not Repeat Yourself (DRY)"]
n_high_cohesion["High Cohesion"]
n_low_coupling["Low Coupling"]
n_encapsulation["Encapsulation"]
n_information_hiding["Information Hiding"]
n_abstraction["Abstraction"]
n_modularity["Modularity"]
n_composability["Composability"]
n_composition_over_inheritance["Composition Over Inheritance"]
n_reusability["Reusability"]
n_replaceability["Replaceability"]
n_interchangeability["Interchangeability"]
n_independence["Independence"]
n_autonomy["Autonomy"]
n_single_responsibility --> n_high_cohesion
n_single_responsibility --> n_separation_of_concerns
n_single_responsibility --> n_modularity
n_single_responsibility --> n_replaceability
n_single_responsibility --> n_reusability
n_separation_of_concerns --> n_abstraction
n_separation_of_concerns --> n_single_responsibility
n_separation_of_concerns --> n_modularity
n_separation_of_concerns --> n_replaceability
n_duplicate_code --> n_abstraction
n_duplicate_code --> n_reusability
n_high_cohesion --> n_single_responsibility
n_high_cohesion --> n_modularity
n_high_cohesion --> n_encapsulation
n_high_cohesion --> n_replaceability
n_low_coupling --> n_abstraction
n_low_coupling --> n_modularity
n_low_coupling --> n_replaceability
n_encapsulation --> n_information_hiding
n_encapsulation --> n_abstraction
n_encapsulation --> n_low_coupling
n_information_hiding --> n_encapsulation
n_information_hiding --> n_low_coupling
n_information_hiding --> n_replaceability
n_abstraction --> n_low_coupling
n_abstraction --> n_replaceability
n_modularity --> n_high_cohesion
n_modularity --> n_low_coupling
n_modularity --> n_separation_of_concerns
n_modularity --> n_composability
n_modularity --> n_replaceability
n_composability --> n_low_coupling
n_composability --> n_modularity
n_composability --> n_reusability
n_composition_over_inheritance --> n_low_coupling
n_composition_over_inheritance --> n_replaceability
n_reusability --> n_abstraction
n_reusability --> n_duplicate_code
n_reusability --> n_composability
n_replaceability --> n_low_coupling
n_interchangeability --> n_replaceability
n_independence --> n_low_coupling
n_independence --> n_autonomy
n_autonomy --> n_independence
```
### Single Responsibility Principle (SRP)
- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [mandatory](https://banes-lab.com/records/vocabulary/severity-mandatory.md)
- Scope: class, module, service
- Aliases: SRP, Single Responsibility Principle (SRP)
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
A design rule that a class or module has one reason to change, because it serves one responsibility.
Requires
[High Cohesion](https://banes-lab.com/records/architecture/high-cohesion.md), [Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md)
Reinforces
[Separation of Concerns](https://banes-lab.com/records/architecture/separation-of-concerns.md), [Modularity](https://banes-lab.com/records/architecture/modularity.md), [Testability](https://banes-lab.com/records/architecture/testability.md)
Enables
[Replaceability](https://banes-lab.com/records/architecture/replaceability.md), [Reusability](https://banes-lab.com/records/architecture/reusability.md)
In tension with
[Excessive Fragmentation](https://banes-lab.com/records/lexicon/excessive-fragmentation.md)
Conflicts with
[God Object](https://banes-lab.com/records/architecture/god-object.md), [Divergent Change](https://banes-lab.com/records/architecture/divergent-change.md)
Referenced by
[Domain Service](https://banes-lab.com/records/architecture/domain-service.md), [Separation of Concerns](https://banes-lab.com/records/architecture/separation-of-concerns.md), [High Cohesion](https://banes-lab.com/records/architecture/high-cohesion.md), [Interface Segregation Principle (ISP)](https://banes-lab.com/records/architecture/interface-segregation.md), [Command Pattern](https://banes-lab.com/records/architecture/command-pattern.md), [Chain of Responsibility Pattern](https://banes-lab.com/records/architecture/chain-of-responsibility-pattern.md), [Iterator Pattern](https://banes-lab.com/records/architecture/iterator-pattern.md), [Pipes and Filters](https://banes-lab.com/records/architecture/pipes-and-filters.md)
Tensions
[Single Responsibility Principle (SRP) / Excessive Fragmentation](https://banes-lab.com/records/tension/excessive-fragmentation-single-responsibility-principle-srp.md)
Distinct from
[Interface Segregation Principle (ISP)](https://banes-lab.com/records/architecture/interface-segregation.md): Single responsibility limits a module's reasons to change, while interface segregation limits what a client depends on.
Distinct from
[Open/Closed Principle (OCP)](https://banes-lab.com/records/architecture/open-closed.md): Single responsibility limits reasons to change, while the open/closed principle governs adding behavior without editing.
Distinct from
[Composability](https://banes-lab.com/records/architecture/composability.md): Single responsibility limits what one part does, while composability governs how parts combine.
Distinct from
[Separation of Concerns](https://banes-lab.com/records/architecture/separation-of-concerns.md): Single responsibility is one reason to change per class or module, while separation of concerns separates the named concerns of a system.
Violated by
Mixed Responsibilities, Multi-Reason Change
Detected by
high fan-in/fan-out, unrelated methods, unrelated dependencies
Measured by
cohesion score, responsibility count, change-coupling
Refactored by
Extract Class, Extract Module, Split Service, Move Method
Enforced by
architecture tests, package boundaries, [static analysis](https://banes-lab.com/records/reasoning/technique-static-analysis.md)
Before
```typescript
class FooService {
save(foo: Foo) { fooDb.insert(foo); }
send(foo: Foo) { fooMail.send(foo); }
report(foo: Foo) { return `${foo.id}:${foo.name}`; }
}
```
After
```typescript
class FooRepository { save(foo: Foo) { return fooDb.insert(foo); } }
class FooNotifier { send(foo: Foo) { return fooMail.send(foo); } }
class FooReporter { report(foo: Foo) { return `${foo.id}:${foo.name}`; } }
```
How it is checked
Checked by
architecture tests, package boundaries, static analysis
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[High Cohesion](https://banes-lab.com/records/architecture/high-cohesion.md), [Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md), [Separation of Concerns](https://banes-lab.com/records/architecture/separation-of-concerns.md), [Modularity](https://banes-lab.com/records/architecture/modularity.md), [Testability](https://banes-lab.com/records/architecture/testability.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md), [Reusability](https://banes-lab.com/records/architecture/reusability.md)
Shape it refuses
[God Object](https://banes-lab.com/records/architecture/god-object.md), [God Object](https://banes-lab.com/records/architecture/god-object.md), [Divergent Change](https://banes-lab.com/records/architecture/divergent-change.md)
### Separation of Concerns
- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [mandatory](https://banes-lab.com/records/vocabulary/severity-mandatory.md)
- Scope: module, package, component, system
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
A design rule that parsing, business logic, persistence and presentation each live in their own part of the code.
Requires
[Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md), [Abstraction](https://banes-lab.com/records/architecture/abstraction.md)
Reinforces
[Single Responsibility Principle (SRP)](https://banes-lab.com/records/architecture/single-responsibility.md), [Modularity](https://banes-lab.com/records/architecture/modularity.md), [Layered Architecture](https://banes-lab.com/records/architecture/layered-architecture.md)
Enables
[Maintainability](https://banes-lab.com/records/lexicon/maintainability.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md)
In tension with
[Over-Layering](https://banes-lab.com/records/lexicon/over-layering.md)
Conflicts with
[Cross-Cutting Leakage](https://banes-lab.com/records/lexicon/cross-cutting-leakage.md), [Mixed Layers](https://banes-lab.com/records/lexicon/mixed-layers.md)
Referenced by
[Single Responsibility Principle (SRP)](https://banes-lab.com/records/architecture/single-responsibility.md), [Modularity](https://banes-lab.com/records/architecture/modularity.md), [Visitor Pattern](https://banes-lab.com/records/architecture/visitor-pattern.md), [Statecharts](https://banes-lab.com/records/architecture/statecharts.md), [Layered Architecture](https://banes-lab.com/records/architecture/layered-architecture.md), [One Concern Per File](https://banes-lab.com/records/architecture/one-concern-per-file.md)
Tensions
[Separation of Concerns / Over-Layering](https://banes-lab.com/records/tension/over-layering-separation-of-concerns.md)
Distinct from
[One Concern Per File](https://banes-lab.com/records/architecture/one-concern-per-file.md): Separation of concerns splits code by responsibility, while one concern per file binds each file to one declared role tag.
Distinct from
[Open/Closed Principle (OCP)](https://banes-lab.com/records/architecture/open-closed.md): Separation of concerns decides where concerns live, while the open/closed principle decides how behavior is added.
Distinct from
[Composability](https://banes-lab.com/records/architecture/composability.md): Separation of concerns keeps concerns apart, while composability lets parts combine.
Violated by
business logic in controllers, persistence logic in domain
Detected by
layer imports, mixed naming roles, cross-boundary logic
Measured by
dependency direction, layer purity, concern overlap
Refactored by
Extract Layer, Move Logic, Introduce Boundary
Enforced by
import rules, dependency graph checks
Refused by rules
separation-of-concerns
Before
```typescript
function handleFoo(request: Request) {
const foo = JSON.parse(request.body);
fooDb.insert(foo);
return `${foo.name}
`;
}
```
After
```typescript
function parseFoo(request: Request): Foo { return decodeFoo(request.body); }
function saveFoo(foo: Foo) { return fooDb.insert(foo); }
function renderFoo(foo: Foo) { return `${foo.name}
`; }
```
How it is checked
Checked by
import rules, dependency graph checks
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md), [Abstraction](https://banes-lab.com/records/architecture/abstraction.md), [Single Responsibility Principle (SRP)](https://banes-lab.com/records/architecture/single-responsibility.md), [Modularity](https://banes-lab.com/records/architecture/modularity.md), [Layered Architecture](https://banes-lab.com/records/architecture/layered-architecture.md), [Maintainability](https://banes-lab.com/records/lexicon/maintainability.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md)
Shape it refuses
[Cross-Cutting Leakage](https://banes-lab.com/records/lexicon/cross-cutting-leakage.md), [Mixed Layers](https://banes-lab.com/records/lexicon/mixed-layers.md)
### Do Not Repeat Yourself (DRY)
- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [mandatory](https://banes-lab.com/records/vocabulary/severity-mandatory.md)
- Scope: function, module, domain
- Aliases: DRY
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
A design rule that each piece of logic, constant or schema has one source in the code, and every other use refers to it.
Requires
[Abstraction](https://banes-lab.com/records/architecture/abstraction.md), [Canonical Source](https://banes-lab.com/records/lexicon/canonical-source.md)
Reinforces
[Single Source of Truth](https://banes-lab.com/records/architecture/single-source-of-truth.md), [Reusability](https://banes-lab.com/records/architecture/reusability.md)
Enables
[Consistency](https://banes-lab.com/records/architecture/consistency.md), [Maintainability](https://banes-lab.com/records/lexicon/maintainability.md)
In tension with
[Locality of Behavior](https://banes-lab.com/records/lexicon/locality-of-behavior.md), [Simplicity](https://banes-lab.com/records/lexicon/simplicity.md)
Conflicts with
[Copy-Paste Programming](https://banes-lab.com/records/lexicon/copy-paste-programming.md)
Referenced by
[Reusability](https://banes-lab.com/records/architecture/reusability.md), [Metaprogramming](https://banes-lab.com/records/architecture/metaprogramming.md), [Single Source of Truth](https://banes-lab.com/records/architecture/single-source-of-truth.md), [Normalization](https://banes-lab.com/records/architecture/normalization.md)
Tensions
[Do Not Repeat Yourself (DRY) / Locality of Behavior](https://banes-lab.com/records/tension/do-not-repeat-yourself-dry-locality-of-behavior.md), [Do Not Repeat Yourself (DRY) / Simplicity](https://banes-lab.com/records/tension/do-not-repeat-yourself-dry-simplicity.md)
Violated by
duplicated logic, duplicated constants, duplicated schemas
Detected by
clone detection, duplicated branches, repeated literals
Measured by
duplication percentage, clone count
Refactored by
Extract Function, Extract Module, Parameterize, Centralize Rule
Enforced by
clone analyzers, lint rules, review gates
Refused by rules
duplicate-code
Before
```typescript
function validateFoo(foo: Foo) {
if (!foo.name || foo.name.length > 40) throw new Error("invalid name");
}
function validateBar(bar: Bar) {
if (!bar.name || bar.name.length > 40) throw new Error("invalid name");
}
```
After
```typescript
function validateName(name: string) {
if (!name || name.length > 40) throw new Error("invalid name");
}
function validateFoo(foo: Foo) { validateName(foo.name); }
function validateBar(bar: Bar) { validateName(bar.name); }
```
How it is checked
Checked by
clone analyzers, lint rules, review gates
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Abstraction](https://banes-lab.com/records/architecture/abstraction.md), [Canonical Source](https://banes-lab.com/records/lexicon/canonical-source.md), [Single Source of Truth](https://banes-lab.com/records/architecture/single-source-of-truth.md), [Reusability](https://banes-lab.com/records/architecture/reusability.md), [Consistency](https://banes-lab.com/records/architecture/consistency.md), [Maintainability](https://banes-lab.com/records/lexicon/maintainability.md)
Shape it refuses
[Copy-Paste Programming](https://banes-lab.com/records/lexicon/copy-paste-programming.md)
### High Cohesion
- Kind: [quality-attribute](https://banes-lab.com/records/kind/quality-attribute.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [mandatory](https://banes-lab.com/records/vocabulary/severity-mandatory.md)
- Scope: class, module, component
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
The degree to which the members of a class or module work on the same data towards the same purpose.
Requires
[Single Responsibility Principle (SRP)](https://banes-lab.com/records/architecture/single-responsibility.md), [Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md)
Reinforces
[Modularity](https://banes-lab.com/records/architecture/modularity.md), [Encapsulation](https://banes-lab.com/records/architecture/encapsulation.md)
Enables
[Testability](https://banes-lab.com/records/architecture/testability.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md)
In tension with
[Over-Specialization](https://banes-lab.com/records/lexicon/over-specialization.md)
Conflicts with
[God Object](https://banes-lab.com/records/architecture/god-object.md), [Utility Dump](https://banes-lab.com/records/architecture/utility-dump.md), [Shotgun Surgery](https://banes-lab.com/records/architecture/shotgun-surgery.md)
Referenced by
[Single Responsibility Principle (SRP)](https://banes-lab.com/records/architecture/single-responsibility.md), [Modularity](https://banes-lab.com/records/architecture/modularity.md)
Tensions
[High Cohesion / Over-Specialization](https://banes-lab.com/records/tension/high-cohesion-over-specialization.md)
Distinct from
[Over-Specialization](https://banes-lab.com/records/lexicon/over-specialization.md): High cohesion is members sharing one purpose, while over-specialization is the reuse lost by narrowing that purpose too far.
Violated by
unrelated methods, unrelated fields, unstable responsibility grouping
Detected by
low LCOM, scattered dependencies, unrelated public API
Measured by
cohesion metrics, change locality
Refactored by
Extract Class, Split Module, Move Method
Enforced by
module ownership, [architecture review](https://banes-lab.com/records/architecture/architecture-review.md)
Before
```typescript
class FooManager {
saveFoo(foo: Foo) { return fooDb.insert(foo); }
resizeImage(image: Image) { return image.resize(100, 100); }
parseBar(raw: string) { return JSON.parse(raw) as Bar; }
}
```
After
```typescript
class FooRepository {
save(foo: Foo) { return fooDb.insert(foo); }
load(id: FooId) { return fooDb.find(id); }
remove(id: FooId) { return fooDb.delete(id); }
}
class ImageResizer { resize(image: Image) { return image.resize(100, 100); } }
class BarParser { parse(raw: string) { return JSON.parse(raw) as Bar; } }
```
How it is checked
Checked by
module ownership, architecture review
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Single Responsibility Principle (SRP)](https://banes-lab.com/records/architecture/single-responsibility.md), [Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md), [Modularity](https://banes-lab.com/records/architecture/modularity.md), [Encapsulation](https://banes-lab.com/records/architecture/encapsulation.md), [Testability](https://banes-lab.com/records/architecture/testability.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md)
Shape it refuses
[God Object](https://banes-lab.com/records/architecture/god-object.md), [Utility Dump](https://banes-lab.com/records/architecture/utility-dump.md), [Shotgun Surgery](https://banes-lab.com/records/architecture/shotgun-surgery.md)
### Low Coupling
- Kind: [quality-attribute](https://banes-lab.com/records/kind/quality-attribute.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [mandatory](https://banes-lab.com/records/vocabulary/severity-mandatory.md)
- Scope: module, component, service
- Aliases: Loose Coupling, Decoupling
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
The degree to which a module can change without forcing changes in the modules around it.
Requires
[Abstraction](https://banes-lab.com/records/architecture/abstraction.md), [Stable Interfaces](https://banes-lab.com/records/architecture/stable-interfaces.md)
Reinforces
[Modularity](https://banes-lab.com/records/architecture/modularity.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md), [Portability](https://banes-lab.com/records/architecture/portability.md)
Enables
[Independent Deployment](https://banes-lab.com/records/lexicon/independent-deployment.md), [Independent Testing](https://banes-lab.com/records/lexicon/independent-testing.md)
In tension with
[Runtime Indirection](https://banes-lab.com/records/lexicon/runtime-indirection.md)
Conflicts with
[Tight Coupling](https://banes-lab.com/records/lexicon/tight-coupling.md), [Circular Dependency](https://banes-lab.com/records/architecture/circular-dependency.md), [Inappropriate Intimacy](https://banes-lab.com/records/architecture/inappropriate-intimacy.md), [Message Chain](https://banes-lab.com/records/architecture/message-chain.md)
Referenced by
[Anti-Corruption Layer](https://banes-lab.com/records/architecture/anti-corruption-layer.md), [Stable Interfaces](https://banes-lab.com/records/architecture/stable-interfaces.md), [Testability](https://banes-lab.com/records/architecture/testability.md), [Encapsulation](https://banes-lab.com/records/architecture/encapsulation.md), [Information Hiding](https://banes-lab.com/records/architecture/information-hiding.md), [Abstraction](https://banes-lab.com/records/architecture/abstraction.md), [Modularity](https://banes-lab.com/records/architecture/modularity.md), [Composability](https://banes-lab.com/records/architecture/composability.md), [Composition Over Inheritance](https://banes-lab.com/records/architecture/composition-over-inheritance.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md), [Independence](https://banes-lab.com/records/architecture/independence.md), [Interface Segregation Principle (ISP)](https://banes-lab.com/records/architecture/interface-segregation.md), [Dependency Inversion Principle (DIP)](https://banes-lab.com/records/architecture/dependency-inversion.md), [Event-Driven Architecture](https://banes-lab.com/records/architecture/event-driven-architecture.md), [Publish/Subscribe Pattern](https://banes-lab.com/records/architecture/publish-subscribe-pattern.md), [Message Broker](https://banes-lab.com/records/architecture/message-broker.md), [Asynchronous Communication](https://banes-lab.com/records/architecture/asynchronous-communication.md), [Mediator Pattern](https://banes-lab.com/records/architecture/mediator-pattern.md), [Service-Oriented Architecture](https://banes-lab.com/records/architecture/service-oriented-architecture.md)
Tensions
[Low Coupling / Runtime Indirection](https://banes-lab.com/records/tension/low-coupling-runtime-indirection.md)
Distinct from
[High Cohesion](https://banes-lab.com/records/architecture/high-cohesion.md): Low coupling is about the dependencies between modules, while high cohesion is about the purpose inside one.
Distinct from
[Portability](https://banes-lab.com/records/architecture/portability.md): Low coupling limits how far a change ripples between modules, while portability is running on another platform unchanged.
Distinct from
[Replaceability](https://banes-lab.com/records/architecture/replaceability.md): Low coupling limits how far a change spreads, while replaceability is swapping an implementation without editing its callers.
Distinct from
[Stable Interfaces](https://banes-lab.com/records/architecture/stable-interfaces.md): Low coupling is few forced changes between modules, while stable interfaces are signatures that keep across releases.
Distinct from
[Testability](https://banes-lab.com/records/architecture/testability.md): Low coupling concerns change between modules, while testability is running code in isolation with supplied dependencies.
Distinct from
[Domain Purity](https://banes-lab.com/records/lexicon/domain-purity.md): Low coupling applies between any modules, while domain purity keeps the domain model free of infrastructure concerns.
Violated by
concrete imports, [global state](https://banes-lab.com/records/lexicon/global-state.md), bidirectional dependencies
Detected by
dependency cycles, high afferent/efferent coupling
Measured by
coupling metrics, dependency graph density
Refactored by
Introduce Interface, [Dependency Injection](https://banes-lab.com/records/architecture/dependency-injection.md), Adapter Extraction
Enforced by
dependency rules, architecture fitness tests
Before
```typescript
class FooService {
save(foo: Foo) {
const db = new SqlDatabase("foo-prod");
barIndex.update(foo);
return db.table("foos").insert(foo);
}
}
```
After
```typescript
class FooService {
constructor(private readonly events: EventSink) {}
save(foo: Foo) { return this.events.emit({ type: "FooSaved", foo }); }
}
```
How it is checked
Checked by
dependency rules, architecture fitness tests
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Abstraction](https://banes-lab.com/records/architecture/abstraction.md), [Stable Interfaces](https://banes-lab.com/records/architecture/stable-interfaces.md), [Modularity](https://banes-lab.com/records/architecture/modularity.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md), [Portability](https://banes-lab.com/records/architecture/portability.md), [Independent Deployment](https://banes-lab.com/records/lexicon/independent-deployment.md), [Independent Testing](https://banes-lab.com/records/lexicon/independent-testing.md)
Shape it refuses
[Tight Coupling](https://banes-lab.com/records/lexicon/tight-coupling.md), [Circular Dependency](https://banes-lab.com/records/architecture/circular-dependency.md), [Inappropriate Intimacy](https://banes-lab.com/records/architecture/inappropriate-intimacy.md), [Message Chain](https://banes-lab.com/records/architecture/message-chain.md)
### Encapsulation
- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [mandatory](https://banes-lab.com/records/vocabulary/severity-mandatory.md)
- Scope: class, module, component
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
A design rule that an object's state is changed only through its own operations, which keep its invariants.
Requires
[Information Hiding](https://banes-lab.com/records/architecture/information-hiding.md), [Stable Interfaces](https://banes-lab.com/records/architecture/stable-interfaces.md)
Reinforces
[Abstraction](https://banes-lab.com/records/architecture/abstraction.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md)
Enables
[Change Isolation](https://banes-lab.com/records/lexicon/change-isolation.md), [Invariant Protection](https://banes-lab.com/records/lexicon/invariant-protection.md)
In tension with
[Debuggability](https://banes-lab.com/records/lexicon/debuggability.md)
Conflicts with
[Exposed Internals](https://banes-lab.com/records/lexicon/exposed-internals.md), [Exposed Internals](https://banes-lab.com/records/lexicon/exposed-internals.md), [Feature Envy](https://banes-lab.com/records/architecture/feature-envy.md)
Referenced by
[Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md), [Aggregate](https://banes-lab.com/records/architecture/aggregate.md), [Value Object](https://banes-lab.com/records/architecture/value-object.md), [Entity](https://banes-lab.com/records/architecture/entity.md), [Invariant](https://banes-lab.com/records/architecture/invariant.md), [High Cohesion](https://banes-lab.com/records/architecture/high-cohesion.md), [Information Hiding](https://banes-lab.com/records/architecture/information-hiding.md), [Introspection](https://banes-lab.com/records/architecture/introspection.md), [Command Pattern](https://banes-lab.com/records/architecture/command-pattern.md), [Iterator Pattern](https://banes-lab.com/records/architecture/iterator-pattern.md), [Memento Pattern](https://banes-lab.com/records/architecture/memento-pattern.md), [Factory Pattern](https://banes-lab.com/records/architecture/factory-pattern.md), [Facade Pattern](https://banes-lab.com/records/architecture/facade-pattern.md), [Proxy Pattern](https://banes-lab.com/records/architecture/proxy-pattern.md), [State Isolation](https://banes-lab.com/records/architecture/state-isolation.md)
Tensions
[Encapsulation / Debuggability](https://banes-lab.com/records/tension/debuggability-encapsulation.md)
Distinct from
[Abstraction](https://banes-lab.com/records/architecture/abstraction.md): Encapsulation guards an object's state behind its operations, while abstraction expresses what a thing does without how.
Distinct from
[Information Hiding](https://banes-lab.com/records/architecture/information-hiding.md): Encapsulation protects state and its invariants, while information hiding keeps implementation decisions private behind an interface.
Distinct from
[Single Responsibility Principle (SRP)](https://banes-lab.com/records/architecture/single-responsibility.md): Encapsulation guards state, while single responsibility limits a module to one reason to change.
Distinct from
[Immutability](https://banes-lab.com/records/architecture/immutability.md): Encapsulation controls how state changes, while immutability forbids change after creation.
Distinct from
[Open/Closed Principle (OCP)](https://banes-lab.com/records/architecture/open-closed.md): Encapsulation protects existing state, while the open/closed principle governs how new behavior is added.
Distinct from
[State Isolation](https://banes-lab.com/records/architecture/state-isolation.md): Encapsulation limits writes to an object's own operations, while state isolation limits writes to one unit of concurrent execution.
Violated by
public mutable fields, leaky getters, direct state mutation
Detected by
public state, excessive setters, external invariant manipulation
Measured by
public surface area, mutation exposure
Refactored by
Hide Field, Introduce Method, Restrict Visibility
Enforced by
visibility rules, linting, API review
Refused by rules
encapsulation
Before
```typescript
class FooCounter {
count = 0;
}
const counter = new FooCounter();
counter.count = -100;
```
After
```typescript
class FooCounter {
#count = 0;
increment() { this.#count += 1; }
value() { return this.#count; }
}
```
How it is checked
Checked by
visibility rules, linting, API review
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Information Hiding](https://banes-lab.com/records/architecture/information-hiding.md), [Stable Interfaces](https://banes-lab.com/records/architecture/stable-interfaces.md), [Abstraction](https://banes-lab.com/records/architecture/abstraction.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Change Isolation](https://banes-lab.com/records/lexicon/change-isolation.md), [Invariant Protection](https://banes-lab.com/records/lexicon/invariant-protection.md)
Shape it refuses
[Exposed Internals](https://banes-lab.com/records/lexicon/exposed-internals.md), [Exposed Internals](https://banes-lab.com/records/lexicon/exposed-internals.md), [Feature Envy](https://banes-lab.com/records/architecture/feature-envy.md)
### Information Hiding
- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [mandatory](https://banes-lab.com/records/vocabulary/severity-mandatory.md)
- Scope: class, module, package
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
A design rule that a module exposes an interface and keeps the implementation decisions behind it private.
Requires
[Encapsulation](https://banes-lab.com/records/architecture/encapsulation.md), [Explicit Interfaces](https://banes-lab.com/records/lexicon/explicit-interfaces.md)
Reinforces
[Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md)
Enables
[Internal Refactoring](https://banes-lab.com/records/lexicon/internal-refactoring.md)
In tension with
[Observability](https://banes-lab.com/records/architecture/observability.md)
Conflicts with
[Leaky Abstraction](https://banes-lab.com/records/lexicon/leaky-abstraction.md)
Referenced by
[Encapsulation](https://banes-lab.com/records/architecture/encapsulation.md), [Memento Pattern](https://banes-lab.com/records/architecture/memento-pattern.md), [Facade Pattern](https://banes-lab.com/records/architecture/facade-pattern.md)
Tensions
[Information Hiding / Observability](https://banes-lab.com/records/tension/information-hiding-observability.md)
Violated by
exposing implementation details, shared internals
Detected by
internal packages imported externally, exposed persistence models
Measured by
internal API exposure, dependency leakage
Refactored by
Introduce Facade, Hide Module, Restrict Exports
Enforced by
package visibility, module export rules
Before
```typescript
class FooStore {
public readonly rows = new Map();
}
fooStore.rows.set(foo.id, foo);
```
After
```typescript
interface FooStore {
save(foo: Foo): void;
find(id: string): Foo | undefined;
}
class MapFooStore implements FooStore {
#rows = new Map();
save(foo: Foo) { this.#rows.set(foo.id, foo); }
find(id: string) { return this.#rows.get(id); }
}
```
How it is checked
Checked by
package visibility, module export rules
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Encapsulation](https://banes-lab.com/records/architecture/encapsulation.md), [Explicit Interfaces](https://banes-lab.com/records/lexicon/explicit-interfaces.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md), [Internal Refactoring](https://banes-lab.com/records/lexicon/internal-refactoring.md)
Shape it refuses
[Leaky Abstraction](https://banes-lab.com/records/lexicon/leaky-abstraction.md)
### Abstraction
- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [mandatory](https://banes-lab.com/records/vocabulary/severity-mandatory.md)
- Scope: class, module, service, system
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
A design rule that a concept is expressed by what it does for the code that uses it, and the detail of how it does it stays out of that expression.
Requires
[Stable Semantics](https://banes-lab.com/records/lexicon/stable-semantics.md), [Interface Definition](https://banes-lab.com/records/lexicon/interface-definition.md)
Reinforces
[Dependency Inversion Principle (DIP)](https://banes-lab.com/records/architecture/dependency-inversion.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Portability](https://banes-lab.com/records/architecture/portability.md)
Enables
[Polymorphism](https://banes-lab.com/records/architecture/polymorphism.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md)
In tension with
[Simplicity](https://banes-lab.com/records/lexicon/simplicity.md)
Conflicts with
[Concrete Coupling](https://banes-lab.com/records/architecture/concrete-coupling.md), [Middle Man](https://banes-lab.com/records/architecture/middle-man.md)
Referenced by
[Dynamic Binding](https://banes-lab.com/records/architecture/dynamic-binding.md), [Interface-Based Design](https://banes-lab.com/records/architecture/interface-based-design.md), [Portability](https://banes-lab.com/records/architecture/portability.md), [Separation of Concerns](https://banes-lab.com/records/architecture/separation-of-concerns.md), [Do Not Repeat Yourself (DRY)](https://banes-lab.com/records/architecture/duplicate-code.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Encapsulation](https://banes-lab.com/records/architecture/encapsulation.md), [Reusability](https://banes-lab.com/records/architecture/reusability.md), [Dependency Inversion Principle (DIP)](https://banes-lab.com/records/architecture/dependency-inversion.md), [Open/Closed Principle (OCP)](https://banes-lab.com/records/architecture/open-closed.md), [Polymorphism](https://banes-lab.com/records/architecture/polymorphism.md), [Inversion of Control (IoC)](https://banes-lab.com/records/architecture/inversion-of-control.md), [Dependency Injection](https://banes-lab.com/records/architecture/dependency-injection.md)
Tensions
[Abstraction / Simplicity](https://banes-lab.com/records/tension/abstraction-simplicity.md)
Distinct from
[Dependency Inversion Principle (DIP)](https://banes-lab.com/records/architecture/dependency-inversion.md): Abstraction expresses a concept by what it does, while dependency inversion fixes that the high-level policy owns that expression.
Distinct from
[Do Not Repeat Yourself (DRY)](https://banes-lab.com/records/architecture/duplicate-code.md): Abstraction hides how a thing works behind what it does, while DRY keeps one source for each piece of logic.
Distinct from
[Interface-Based Design](https://banes-lab.com/records/architecture/interface-based-design.md): Abstraction is the general rule, while interface-based design applies it to module dependencies supplied from outside.
Distinct from
[Inversion of Control (IoC)](https://banes-lab.com/records/architecture/inversion-of-control.md): Abstraction hides detail, while inversion of control moves object creation and control flow to a framework or composition root.
Distinct from
[Open/Closed Principle (OCP)](https://banes-lab.com/records/architecture/open-closed.md): Abstraction hides detail, while the open/closed principle adds behavior at an extension point without editing existing code.
Distinct from
[Separation of Concerns](https://banes-lab.com/records/architecture/separation-of-concerns.md): Abstraction separates what from how, while separation of concerns separates parsing, logic, persistence and presentation.
Violated by
hardcoded implementation dependency, implementation leakage
Detected by
concrete type usage across boundaries
Measured by
abstraction ratio, interface stability
Refactored by
Extract Interface, Introduce Port, Generalize Dependency
Enforced by
architecture tests, dependency inversion rules
Before
```typescript
function saveFoo(foo: Foo) {
return sqlClient.query("insert into foos(id,name) values($1,$2)", [foo.id, foo.name]);
}
```
After
```typescript
interface FooRepository { save(foo: Foo): Promise; }
class SqlFooRepository implements FooRepository {
save(foo: Foo) { return sqlClient.query("insert into foos(id,name) values($1,$2)", [foo.id, foo.name]); }
}
class HttpFooRepository implements FooRepository {
save(foo: Foo) { return http.post("/foos", foo); }
}
function saveFoo(foo: Foo, repository: FooRepository) { return repository.save(foo); }
```
How it is checked
Checked by
architecture tests, dependency inversion rules
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Stable Semantics](https://banes-lab.com/records/lexicon/stable-semantics.md), [Interface Definition](https://banes-lab.com/records/lexicon/interface-definition.md), [Dependency Inversion Principle (DIP)](https://banes-lab.com/records/architecture/dependency-inversion.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Portability](https://banes-lab.com/records/architecture/portability.md), [Polymorphism](https://banes-lab.com/records/architecture/polymorphism.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md)
Shape it refuses
[Concrete Coupling](https://banes-lab.com/records/architecture/concrete-coupling.md), [Middle Man](https://banes-lab.com/records/architecture/middle-man.md)
### Modularity
- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [mandatory](https://banes-lab.com/records/vocabulary/severity-mandatory.md)
- Scope: package, component, service, system
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
A design rule that a system is divided into cohesive modules with explicit boundaries and few dependencies between them.
Requires
[High Cohesion](https://banes-lab.com/records/architecture/high-cohesion.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md)
Reinforces
[Separation of Concerns](https://banes-lab.com/records/architecture/separation-of-concerns.md), [Composability](https://banes-lab.com/records/architecture/composability.md)
Enables
[Replaceability](https://banes-lab.com/records/architecture/replaceability.md), [Plugin Architecture](https://banes-lab.com/records/architecture/plugin-architecture.md)
In tension with
[Cross-Cutting Concerns](https://banes-lab.com/records/lexicon/cross-cutting-concerns.md)
Conflicts with
[Big Ball of Mud](https://banes-lab.com/records/architecture/big-ball-of-mud.md)
Referenced by
[Bounded Context](https://banes-lab.com/records/architecture/bounded-context.md), [Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md), [Single Responsibility Principle (SRP)](https://banes-lab.com/records/architecture/single-responsibility.md), [Separation of Concerns](https://banes-lab.com/records/architecture/separation-of-concerns.md), [High Cohesion](https://banes-lab.com/records/architecture/high-cohesion.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Composability](https://banes-lab.com/records/architecture/composability.md), [Plugin Architecture](https://banes-lab.com/records/architecture/plugin-architecture.md), [Component-Based Architecture](https://banes-lab.com/records/architecture/component-based-architecture.md), [Package by Feature](https://banes-lab.com/records/architecture/package-by-feature.md)
Tensions
[Modularity / Cross-Cutting Concerns](https://banes-lab.com/records/tension/cross-cutting-concerns-modularity.md)
Distinct from
[Autonomy](https://banes-lab.com/records/architecture/autonomy.md): Modularity divides a system into cohesive parts, while autonomy gives each owner its own data and decisions.
Distinct from
[Composability](https://banes-lab.com/records/architecture/composability.md): Modularity divides a system, while composability lets its parts combine.
Distinct from
[Encapsulation](https://banes-lab.com/records/architecture/encapsulation.md): Modularity is division into modules, while encapsulation protects one object's state.
Distinct from
[Open/Closed Principle (OCP)](https://banes-lab.com/records/architecture/open-closed.md): Modularity divides the system, while the open/closed principle governs adding behavior at an extension point.
Distinct from
[Package by Feature](https://banes-lab.com/records/architecture/package-by-feature.md): Modularity is the rule to divide, while package by feature chooses the axis of division, the feature.
Distinct from
[Separation of Concerns](https://banes-lab.com/records/architecture/separation-of-concerns.md): Modularity divides into cohesive modules, while separation of concerns names which concerns must not share a part.
Distinct from
[Single Responsibility Principle (SRP)](https://banes-lab.com/records/architecture/single-responsibility.md): Modularity is the division of a system, while single responsibility limits one class or module to one reason to change.
Violated by
[cyclic dependencies](https://banes-lab.com/records/architecture/circular-dependency.md), [shared mutable state](https://banes-lab.com/records/architecture/shared-mutable-state.md), [boundary leakage](https://banes-lab.com/records/architecture/boundary-leakage.md)
Detected by
dependency cycles, unstable module graph
Measured by
modularity score, graph density, instability
Refactored by
Split Module, Introduce Boundary, Invert Dependency
Enforced by
module rules, package ownership, [fitness functions](https://banes-lab.com/records/architecture/fitness-functions.md)
Before
```typescript
class FooApplication {
parse(raw: string) { return JSON.parse(raw) as Foo; }
save(foo: Foo) { return fooDb.insert(foo); }
publish(foo: Foo) { return fooBus.emit(foo); }
}
```
After
```typescript
export const fooParser = { parse: (raw: string) => decodeFoo(raw) };
export const fooRepository = { save: (foo: Foo) => fooDb.insert(foo) };
export const fooPublisher = { publish: (foo: Foo) => fooBus.emit(foo) };
```
How it is checked
Checked by
module rules, package ownership, fitness functions
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[High Cohesion](https://banes-lab.com/records/architecture/high-cohesion.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md), [Separation of Concerns](https://banes-lab.com/records/architecture/separation-of-concerns.md), [Composability](https://banes-lab.com/records/architecture/composability.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md), [Plugin Architecture](https://banes-lab.com/records/architecture/plugin-architecture.md)
Shape it refuses
[Big Ball of Mud](https://banes-lab.com/records/architecture/big-ball-of-mud.md)
### Composability
- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [recommended](https://banes-lab.com/records/vocabulary/severity-recommended.md)
- Scope: function, component, system
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
A design rule that parts share compatible interfaces and carry no hidden side effects, so they can be combined into larger parts.
Requires
[Stable Interfaces](https://banes-lab.com/records/architecture/stable-interfaces.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md)
Reinforces
[Modularity](https://banes-lab.com/records/architecture/modularity.md), [Reusability](https://banes-lab.com/records/architecture/reusability.md)
Enables
[Pipeline Architecture](https://banes-lab.com/records/architecture/pipeline-architecture.md), [Plugin Architecture](https://banes-lab.com/records/architecture/plugin-architecture.md)
In tension with
[Performance Overhead](https://banes-lab.com/records/lexicon/performance-overhead.md)
Conflicts with
[Monolithic Procedures](https://banes-lab.com/records/lexicon/monolithic-procedures.md)
Referenced by
[Modularity](https://banes-lab.com/records/architecture/modularity.md), [Reusability](https://banes-lab.com/records/architecture/reusability.md), [Decorator Pattern](https://banes-lab.com/records/architecture/decorator-pattern.md), [Pipeline Architecture](https://banes-lab.com/records/architecture/pipeline-architecture.md), [Component-Based Architecture](https://banes-lab.com/records/architecture/component-based-architecture.md), [Pipes and Filters](https://banes-lab.com/records/architecture/pipes-and-filters.md)
Tensions
[Composability / Performance Overhead](https://banes-lab.com/records/tension/composability-performance-overhead.md)
Distinct from
[Do Not Repeat Yourself (DRY)](https://banes-lab.com/records/architecture/duplicate-code.md): Composability lets parts combine through compatible interfaces, while DRY keeps one source for each piece of logic.
Violated by
[hidden side effects](https://banes-lab.com/records/architecture/hidden-side-effect.md), [incompatible interfaces](https://banes-lab.com/records/lexicon/incompatible-interfaces.md)
Detected by
non-chainable APIs, incompatible contracts
Measured by
composition count, interface compatibility
Refactored by
Normalize Interface, Extract Component, Introduce Adapter
Enforced by
contract tests, type checks
Before
```typescript
function processFoo(raw: string) {
const foo = JSON.parse(raw) as Foo;
const normalized = { ...foo, name: foo.name.trim() };
return fooDb.insert(normalized);
}
```
After
```typescript
const parseFoo = (raw: string): Foo => decodeFoo(raw);
const normalizeFoo = (foo: Foo): Foo => ({ ...foo, name: foo.name.trim() });
const saveFoo = (foo: Foo) => fooDb.insert(foo);
const processFoo = flow(parseFoo, normalizeFoo, saveFoo);
```
How it is checked
Checked by
contract tests, type checks
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Stable Interfaces](https://banes-lab.com/records/architecture/stable-interfaces.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Modularity](https://banes-lab.com/records/architecture/modularity.md), [Reusability](https://banes-lab.com/records/architecture/reusability.md), [Pipeline Architecture](https://banes-lab.com/records/architecture/pipeline-architecture.md), [Plugin Architecture](https://banes-lab.com/records/architecture/plugin-architecture.md)
Shape it refuses
[Monolithic Procedures](https://banes-lab.com/records/lexicon/monolithic-procedures.md)
### Composition Over Inheritance
- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [recommended](https://banes-lab.com/records/vocabulary/severity-recommended.md)
- Scope: class, component
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
A design rule that behavior is reused by holding and delegating to another object instead of extending its class.
Requires
[Delegation](https://banes-lab.com/records/lexicon/delegation.md), [Interface-Based Design](https://banes-lab.com/records/architecture/interface-based-design.md)
Reinforces
[Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md)
Enables
[Strategy Pattern](https://banes-lab.com/records/architecture/strategy-pattern.md), [Decorator Pattern](https://banes-lab.com/records/architecture/decorator-pattern.md)
In tension with
[Simplicity for Trivial Reuse](https://banes-lab.com/records/lexicon/simplicity-for-trivial-reuse.md)
Conflicts with
[Deep Inheritance Hierarchy](https://banes-lab.com/records/lexicon/deep-inheritance-hierarchy.md)
Referenced by
[Bridge Pattern](https://banes-lab.com/records/architecture/bridge-pattern.md)
Tensions
[Composition Over Inheritance / Simplicity for Trivial Reuse](https://banes-lab.com/records/tension/composition-over-inheritance-simplicity-for-trivial-reuse.md)
Violated by
fragile base class, inherited behavior misuse
Detected by
inheritance depth, overridden behavior conflicts
Measured by
inheritance depth, composition ratio
Refactored by
Replace Inheritance with Delegation, Extract Strategy
Enforced by
inheritance depth limits, review rules
Before
```typescript
class RetryingSqlFooStore extends SqlFooStore {
async save(foo: Foo) {
for (let attempt = 0; attempt < 3; attempt += 1) {
try { return await super.save(foo); } catch (error) { if (attempt === 2) throw error; }
}
}
}
```
After
```typescript
class RetryingFooStore implements FooStore {
constructor(private readonly inner: FooStore, private readonly attempts: number) {}
async save(foo: Foo) {
for (let attempt = 0; attempt < this.attempts; attempt += 1) {
try { return await this.inner.save(foo); } catch (error) { if (attempt === this.attempts - 1) throw error; }
}
}
}
```
How it is checked
Checked by
inheritance depth limits, review rules
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Delegation](https://banes-lab.com/records/lexicon/delegation.md), [Interface-Based Design](https://banes-lab.com/records/architecture/interface-based-design.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md), [Strategy Pattern](https://banes-lab.com/records/architecture/strategy-pattern.md), [Decorator Pattern](https://banes-lab.com/records/architecture/decorator-pattern.md)
Shape it refuses
[Deep Inheritance Hierarchy](https://banes-lab.com/records/lexicon/deep-inheritance-hierarchy.md)
### Reusability
- Kind: [quality-attribute](https://banes-lab.com/records/kind/quality-attribute.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [recommended](https://banes-lab.com/records/vocabulary/severity-recommended.md)
- Scope: function, module, component
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
The degree to which a function or module can serve a new caller without change, because it carries no context of its first one.
Requires
[Abstraction](https://banes-lab.com/records/architecture/abstraction.md), [Stable Contracts](https://banes-lab.com/records/lexicon/stable-contracts.md)
Reinforces
[Do Not Repeat Yourself (DRY)](https://banes-lab.com/records/architecture/duplicate-code.md), [Composability](https://banes-lab.com/records/architecture/composability.md)
Enables
[Shared Libraries](https://banes-lab.com/records/lexicon/shared-libraries.md), [Product Lines](https://banes-lab.com/records/lexicon/product-lines.md)
In tension with
[YAGNI](https://banes-lab.com/records/lexicon/yagni.md), [Over-Generalization](https://banes-lab.com/records/lexicon/over-generalization.md)
Conflicts with
[Context-Specific Coupling](https://banes-lab.com/records/lexicon/context-specific-coupling.md)
Referenced by
[Single Responsibility Principle (SRP)](https://banes-lab.com/records/architecture/single-responsibility.md), [Do Not Repeat Yourself (DRY)](https://banes-lab.com/records/architecture/duplicate-code.md), [Composability](https://banes-lab.com/records/architecture/composability.md)
Tensions
[Reusability / YAGNI](https://banes-lab.com/records/tension/reusability-yagni.md), [Reusability / Over-Generalization](https://banes-lab.com/records/tension/over-generalization-reusability.md)
Distinct from
[Over-Generalization](https://banes-lab.com/records/lexicon/over-generalization.md): Reusability serves new callers unchanged, while over-generalization is the clarity lost by making code serve every case.
Violated by
hardcoded context, hidden assumptions
Detected by
environment-specific logic in reusable code
Measured by
reuse count, dependency portability
Refactored by
Parameterize, Extract Library, Remove Context Coupling
Enforced by
API review, dependency rules
Before
```typescript
function saveAdminFoo(foo: Foo) { return adminFooDb.insert(foo); }
function savePublicFoo(foo: Foo) { return publicFooDb.insert(foo); }
```
After
```typescript
function saveFoo(store: FooStore, foo: Foo) { return store.save(foo); }
const saveAdminFoo = (foo: Foo) => saveFoo(adminFooStore, foo);
const savePublicFoo = (foo: Foo) => saveFoo(publicFooStore, foo);
```
How it is checked
Checked by
API review, dependency rules
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Abstraction](https://banes-lab.com/records/architecture/abstraction.md), [Stable Contracts](https://banes-lab.com/records/lexicon/stable-contracts.md), [Do Not Repeat Yourself (DRY)](https://banes-lab.com/records/architecture/duplicate-code.md), [Composability](https://banes-lab.com/records/architecture/composability.md), [Shared Libraries](https://banes-lab.com/records/lexicon/shared-libraries.md), [Product Lines](https://banes-lab.com/records/lexicon/product-lines.md)
Shape it refuses
[Context-Specific Coupling](https://banes-lab.com/records/lexicon/context-specific-coupling.md)
### Replaceability
- Kind: [quality-attribute](https://banes-lab.com/records/kind/quality-attribute.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [recommended](https://banes-lab.com/records/vocabulary/severity-recommended.md)
- Scope: component, service, infrastructure
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
The degree to which a component can be swapped for another implementation of its interface without editing its callers.
Requires
[Stable Interfaces](https://banes-lab.com/records/architecture/stable-interfaces.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md)
Reinforces
[Dependency Inversion Principle (DIP)](https://banes-lab.com/records/architecture/dependency-inversion.md), [Ports and Adapters](https://banes-lab.com/records/lexicon/ports-and-adapters.md)
Enables
[Vendor Swap](https://banes-lab.com/records/lexicon/vendor-swap.md), [Plugin Architecture](https://banes-lab.com/records/architecture/plugin-architecture.md)
In tension with
[Deep Optimization](https://banes-lab.com/records/lexicon/deep-optimization.md)
Conflicts with
[Concrete Coupling](https://banes-lab.com/records/architecture/concrete-coupling.md)
Referenced by
[Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md), [Stable Interfaces](https://banes-lab.com/records/architecture/stable-interfaces.md), [Portability](https://banes-lab.com/records/architecture/portability.md), [Protocol Independence](https://banes-lab.com/records/architecture/protocol-independence.md), [Single Responsibility Principle (SRP)](https://banes-lab.com/records/architecture/single-responsibility.md), [Separation of Concerns](https://banes-lab.com/records/architecture/separation-of-concerns.md), [High Cohesion](https://banes-lab.com/records/architecture/high-cohesion.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Information Hiding](https://banes-lab.com/records/architecture/information-hiding.md), [Abstraction](https://banes-lab.com/records/architecture/abstraction.md), [Modularity](https://banes-lab.com/records/architecture/modularity.md), [Composition Over Inheritance](https://banes-lab.com/records/architecture/composition-over-inheritance.md), [Interchangeability](https://banes-lab.com/records/architecture/interchangeability.md), [Adapter Pattern](https://banes-lab.com/records/architecture/adapter-pattern.md), [Dependency Injection](https://banes-lab.com/records/architecture/dependency-injection.md), [Ports and Adapters Architecture](https://banes-lab.com/records/architecture/ports-and-adapters-architecture.md), [Component-Based Architecture](https://banes-lab.com/records/architecture/component-based-architecture.md)
Tensions
[Replaceability / Deep Optimization](https://banes-lab.com/records/tension/deep-optimization-replaceability.md)
Distinct from
[High Cohesion](https://banes-lab.com/records/architecture/high-cohesion.md): Replaceability is swapping an implementation, while high cohesion is members sharing one purpose.
Distinct from
[Interchangeability](https://banes-lab.com/records/architecture/interchangeability.md): Replaceability is substituting one implementation when the code changes, while interchangeability is selecting among several live implementations at runtime.
Distinct from
[Portability](https://banes-lab.com/records/architecture/portability.md): Replaceability swaps one component, while portability moves the whole software to another platform.
Distinct from
[Reusability](https://banes-lab.com/records/architecture/reusability.md): Replaceability puts a new implementation behind the same callers, while reusability serves a new caller with the same implementation.
Distinct from
[Testability](https://banes-lab.com/records/architecture/testability.md): Replaceability swaps an implementation in production, while testability supplies dependencies in a test.
Distinct from
[Stable Interfaces](https://banes-lab.com/records/architecture/stable-interfaces.md): Replaceability swaps what sits behind an interface, while stable interfaces keep the interface itself unchanged across releases.
Distinct from
[Maintainability](https://banes-lab.com/records/lexicon/maintainability.md): Replaceability makes one kind of change cheap, while maintainability is the ease of every kind of correction and extension.
Violated by
direct vendor SDK usage in domain/application
Detected by
infrastructure imports in core layers
Measured by
adapter coverage, boundary purity
Refactored by
Introduce Port, Extract Adapter, Invert Dependency
Enforced by
import restrictions, adapter tests
Before
```typescript
class FooService {
private readonly store = new SqlFooStore();
save(foo: Foo) { return this.store.save(foo); }
}
```
After
```typescript
class FooService {
constructor(private readonly store: FooStore) {}
save(foo: Foo) { return this.store.save(foo); }
}
test("saves without a database", async () => {
const store = new MemoryFooStore();
await new FooService(store).save(foo);
expect(store.find(foo.id)).toEqual(foo);
});
```
How it is checked
Checked by
import restrictions, adapter tests
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Stable Interfaces](https://banes-lab.com/records/architecture/stable-interfaces.md), [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Dependency Inversion Principle (DIP)](https://banes-lab.com/records/architecture/dependency-inversion.md), [Ports and Adapters](https://banes-lab.com/records/lexicon/ports-and-adapters.md), [Vendor Swap](https://banes-lab.com/records/lexicon/vendor-swap.md), [Plugin Architecture](https://banes-lab.com/records/architecture/plugin-architecture.md)
Shape it refuses
[Concrete Coupling](https://banes-lab.com/records/architecture/concrete-coupling.md)
### Interchangeability
- Kind: [quality-attribute](https://banes-lab.com/records/kind/quality-attribute.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [recommended](https://banes-lab.com/records/vocabulary/severity-recommended.md)
- Scope: component, plugin, service
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
The degree to which several implementations conform to one contract closely enough to be selected at runtime.
Requires
[Contract Compatibility](https://banes-lab.com/records/lexicon/contract-compatibility.md), [Contract Compatibility](https://banes-lab.com/records/lexicon/contract-compatibility.md)
Reinforces
[Replaceability](https://banes-lab.com/records/architecture/replaceability.md), [Polymorphism](https://banes-lab.com/records/architecture/polymorphism.md)
Enables
[Strategy Swap](https://banes-lab.com/records/lexicon/strategy-swap.md), [Strategy Swap](https://banes-lab.com/records/lexicon/strategy-swap.md)
In tension with
[Specialized Optimization](https://banes-lab.com/records/lexicon/specialized-optimization.md)
Conflicts with
[Implementation-Specific Contracts](https://banes-lab.com/records/lexicon/implementation-specific-contracts.md)
Referenced by
[Polymorphism](https://banes-lab.com/records/architecture/polymorphism.md), [Abstract Factory Pattern](https://banes-lab.com/records/architecture/abstract-factory-pattern.md)
Tensions
[Interchangeability / Specialized Optimization](https://banes-lab.com/records/tension/interchangeability-specialized-optimization.md)
Distinct from
[Specialized Optimization](https://banes-lab.com/records/lexicon/specialized-optimization.md): Interchangeability lets implementations be swapped, while specialized optimization is the tuning for one implementation that it gives up.
Violated by
non-conforming substitutes
Detected by
contract test failure, incompatible schema
Measured by
conformance score, compatibility tests
Refactored by
Normalize Interface, Add Adapter, Align Contract
Enforced by
contract tests, [schema validation](https://banes-lab.com/records/architecture/schema-validation.md)
Before
```typescript
function loadFoo(kind: "sql" | "memory", id: FooId) {
if (kind === "sql") return sqlFooStore.find(id);
return memoryFooStore.get(id);
}
```
After
```typescript
interface FooStore { find(id: FooId): Promise; }
function loadFoo(store: FooStore, id: FooId) { return store.find(id); }
```
How it is checked
Checked by
contract tests, schema validation
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Contract Compatibility](https://banes-lab.com/records/lexicon/contract-compatibility.md), [Contract Compatibility](https://banes-lab.com/records/lexicon/contract-compatibility.md), [Replaceability](https://banes-lab.com/records/architecture/replaceability.md), [Polymorphism](https://banes-lab.com/records/architecture/polymorphism.md), [Strategy Swap](https://banes-lab.com/records/lexicon/strategy-swap.md), [Strategy Swap](https://banes-lab.com/records/lexicon/strategy-swap.md)
Shape it refuses
[Implementation-Specific Contracts](https://banes-lab.com/records/lexicon/implementation-specific-contracts.md)
### Independence
- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [recommended](https://banes-lab.com/records/vocabulary/severity-recommended.md)
- Scope: module, service, deployment
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
A design rule that a module can be tested and deployed without the modules around it being present or released.
Requires
[Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md)
Reinforces
[Autonomy](https://banes-lab.com/records/architecture/autonomy.md), [Portability](https://banes-lab.com/records/architecture/portability.md)
Enables
[Independent Testing](https://banes-lab.com/records/lexicon/independent-testing.md), [Independent Deployment](https://banes-lab.com/records/lexicon/independent-deployment.md)
In tension with
[Coordination Cost](https://banes-lab.com/records/lexicon/coordination-cost.md)
Conflicts with
[Shared Runtime Dependency](https://banes-lab.com/records/lexicon/shared-runtime-dependency.md)
Referenced by
[Autonomy](https://banes-lab.com/records/architecture/autonomy.md)
Tensions
[Independence / Coordination Cost](https://banes-lab.com/records/tension/coordination-cost-independence.md)
Violated by
shared database coupling, synchronous dependency chains
Detected by
shared mutable resources, deployment coupling
Measured by
independent deployability, dependency count
Refactored by
Split Boundary, Introduce Events, Decouple Persistence
Enforced by
deployment rules, service ownership
Before
```typescript
class FooModule {
create(foo: Foo) {
barModule.refresh(foo.id);
bazModule.rebuild(foo.id);
return fooDb.insert(foo);
}
}
```
After
```typescript
class FooModule {
constructor(private readonly store: FooStore, private readonly events: EventSink) {}
async create(foo: Foo) {
await this.store.save(foo);
this.events.emit({ type: "FooCreated", fooId: foo.id });
}
}
```
How it is checked
Checked by
deployment rules, service ownership
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md), [Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md), [Autonomy](https://banes-lab.com/records/architecture/autonomy.md), [Portability](https://banes-lab.com/records/architecture/portability.md), [Independent Testing](https://banes-lab.com/records/lexicon/independent-testing.md), [Independent Deployment](https://banes-lab.com/records/lexicon/independent-deployment.md)
Shape it refuses
[Shared Runtime Dependency](https://banes-lab.com/records/lexicon/shared-runtime-dependency.md)
### Autonomy
- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Category: [Core Modular Design](https://banes-lab.com/ontology/principles/architecture-category-core-modular-design.md)
- Severity: [contextual](https://banes-lab.com/records/vocabulary/severity-contextual.md)
- Scope: service, team, bounded context
- Aliases: Service Autonomy
- Layer: [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
Details
Definition
A design rule that a service or team owns its data and decisions, so it alone writes its data and others reach or change it only through its published API or events.
Requires
[Independence](https://banes-lab.com/records/architecture/independence.md), [Own Data](https://banes-lab.com/records/lexicon/own-data.md), [Explicit Contracts](https://banes-lab.com/records/architecture/explicit-contracts.md)
Reinforces
[Decentralization](https://banes-lab.com/records/architecture/decentralization.md), [Resilience](https://banes-lab.com/records/architecture/resilience.md)
Enables
[Microservices](https://banes-lab.com/records/architecture/microservices.md), [Bounded Context Ownership](https://banes-lab.com/records/lexicon/bounded-context-ownership.md), [Independent Deployment](https://banes-lab.com/records/lexicon/independent-deployment.md)
In tension with
[Governance](https://banes-lab.com/records/architecture/governance.md), [Standardization](https://banes-lab.com/records/architecture/standardization.md), [Global Consistency](https://banes-lab.com/records/lexicon/global-consistency.md)
Conflicts with
[Centralized Runtime Control](https://banes-lab.com/records/lexicon/centralized-runtime-control.md), [Shared Database](https://banes-lab.com/records/lexicon/shared-database.md), [Cyclic Deployment Dependency](https://banes-lab.com/records/architecture/cyclic-deployment-dependency.md)
Referenced by
[Bounded Context](https://banes-lab.com/records/architecture/bounded-context.md), [Service Contract](https://banes-lab.com/records/architecture/service-contract.md), [Decentralization](https://banes-lab.com/records/architecture/decentralization.md), [Choreography](https://banes-lab.com/records/architecture/choreography.md), [Independence](https://banes-lab.com/records/architecture/independence.md), [Microservices](https://banes-lab.com/records/architecture/microservices.md), [Service-Oriented Architecture](https://banes-lab.com/records/architecture/service-oriented-architecture.md)
Tensions
[Autonomy / Governance](https://banes-lab.com/records/tension/autonomy-governance.md), [Autonomy / Standardization](https://banes-lab.com/records/tension/autonomy-standardization.md), [Autonomy / Global Consistency](https://banes-lab.com/records/tension/autonomy-global-consistency.md)
Distinct from
[Explicit Contracts](https://banes-lab.com/records/architecture/explicit-contracts.md): Autonomy is ownership of data and decisions, while explicit contracts are the declared boundaries others use to reach them.
Distinct from
[Governance](https://banes-lab.com/records/architecture/governance.md): Autonomy leaves decisions with their owner, while governance holds decisions to shared policy.
Distinct from
[Standardization](https://banes-lab.com/records/architecture/standardization.md): Autonomy lets each owner choose, while standardization fixes one choice everywhere.
Distinct from
[Decentralization](https://banes-lab.com/records/architecture/decentralization.md): Autonomy is one unit owning its data and decisions, while decentralization is the system-wide placement of control with those units.
Distinct from
[Independence](https://banes-lab.com/records/architecture/independence.md): Autonomy is ownership, while independence is being tested and deployed without the neighboring modules.
Violated by
cross-service database writes, shared business logic ownership
Detected by
external writes to owned data, cross-team coupling
Measured by
ownership clarity, deployment independence
Refactored by
[Own Data](https://banes-lab.com/records/lexicon/own-data.md), Split Context, Introduce Events
Enforced by
ownership boundaries, API policies
Before
```typescript
async function createFoo(foo: Foo) {
const bar = await barService.get(foo.barId);
await bazService.validate(foo, bar);
return fooStore.save(foo);
}
```
After
```typescript
async function createFoo(foo: Foo) {
await fooStore.save(foo);
await outbox.append({ type: "FooCreated", fooId: foo.id, barId: foo.barId });
}
```
How it is checked
Checked by
ownership boundaries, API policies
Population
Every class, module and package boundary in the codebase
Freshness
A verdict stands until the module's contents, exports or imports change
Refusal
The dependency, visibility or clone rule fails the build on the change that breaks the property
Observation
Cohesion, coupling, duplication and export metrics read from source and the import graph
Evidence
None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it
Authoritative side
The declared module boundary, which every import and export conforms to
Depends on
[Independence](https://banes-lab.com/records/architecture/independence.md), [Own Data](https://banes-lab.com/records/lexicon/own-data.md), [Explicit Contracts](https://banes-lab.com/records/architecture/explicit-contracts.md), [Decentralization](https://banes-lab.com/records/architecture/decentralization.md), [Resilience](https://banes-lab.com/records/architecture/resilience.md), [Microservices](https://banes-lab.com/records/architecture/microservices.md), [Bounded Context Ownership](https://banes-lab.com/records/lexicon/bounded-context-ownership.md), [Independent Deployment](https://banes-lab.com/records/lexicon/independent-deployment.md)
Shape it refuses
[Centralized Runtime Control](https://banes-lab.com/records/lexicon/centralized-runtime-control.md), [Shared Database](https://banes-lab.com/records/lexicon/shared-database.md), [Cyclic Deployment Dependency](https://banes-lab.com/records/architecture/cyclic-deployment-dependency.md)
## Links to
- [principle](https://banes-lab.com/records/kind/principle.md)
- [mandatory](https://banes-lab.com/records/vocabulary/severity-mandatory.md)
- [Structural Core](https://banes-lab.com/records/layer/structural-core.md)
- [High Cohesion](https://banes-lab.com/records/architecture/high-cohesion.md)
- [Explicit Boundaries](https://banes-lab.com/records/architecture/explicit-boundaries.md)
- [Separation of Concerns](https://banes-lab.com/records/architecture/separation-of-concerns.md)
- [Modularity](https://banes-lab.com/records/architecture/modularity.md)
- [Testability](https://banes-lab.com/records/architecture/testability.md)
- [Replaceability](https://banes-lab.com/records/architecture/replaceability.md)
- [Reusability](https://banes-lab.com/records/architecture/reusability.md)
- [Excessive Fragmentation](https://banes-lab.com/records/lexicon/excessive-fragmentation.md)
- [God Object](https://banes-lab.com/records/architecture/god-object.md)
- [Divergent Change](https://banes-lab.com/records/architecture/divergent-change.md)
- [Domain Service](https://banes-lab.com/records/architecture/domain-service.md)
- [Interface Segregation Principle](https://banes-lab.com/records/architecture/interface-segregation.md)
- [Command Pattern](https://banes-lab.com/records/architecture/command-pattern.md)
- [Chain of Responsibility Pattern](https://banes-lab.com/records/architecture/chain-of-responsibility-pattern.md)
- [Iterator Pattern](https://banes-lab.com/records/architecture/iterator-pattern.md)
- [Pipes and Filters](https://banes-lab.com/records/architecture/pipes-and-filters.md)
- [Single Responsibility Principle (SRP) / Excessive Fragmentation](https://banes-lab.com/records/tension/excessive-fragmentation-single-responsibility-principle-srp.md)
- [Open/Closed Principle](https://banes-lab.com/records/architecture/open-closed.md)
- [Composability](https://banes-lab.com/records/architecture/composability.md)
- [Static Analysis](https://banes-lab.com/records/reasoning/technique-static-analysis.md)
- [Abstraction](https://banes-lab.com/records/architecture/abstraction.md)
- [Single Responsibility Principle](https://banes-lab.com/records/architecture/single-responsibility.md)
- [Layered Architecture](https://banes-lab.com/records/architecture/layered-architecture.md)
- [Maintainability](https://banes-lab.com/records/lexicon/maintainability.md)
- [Over-Layering](https://banes-lab.com/records/lexicon/over-layering.md)
- [Cross-Cutting Leakage](https://banes-lab.com/records/lexicon/cross-cutting-leakage.md)
- [Mixed Layers](https://banes-lab.com/records/lexicon/mixed-layers.md)
- [Visitor Pattern](https://banes-lab.com/records/architecture/visitor-pattern.md)
- [Statecharts](https://banes-lab.com/records/architecture/statecharts.md)
- [One Concern Per File](https://banes-lab.com/records/architecture/one-concern-per-file.md)
- [Separation of Concerns / Over-Layering](https://banes-lab.com/records/tension/over-layering-separation-of-concerns.md)
- [Canonical Source](https://banes-lab.com/records/lexicon/canonical-source.md)
- [Single Source of Truth](https://banes-lab.com/records/architecture/single-source-of-truth.md)
- [Consistency](https://banes-lab.com/records/architecture/consistency.md)
- [Locality of Behavior](https://banes-lab.com/records/lexicon/locality-of-behavior.md)
- [Simplicity](https://banes-lab.com/records/lexicon/simplicity.md)
- [Copy-Paste Programming](https://banes-lab.com/records/lexicon/copy-paste-programming.md)
- [Metaprogramming](https://banes-lab.com/records/architecture/metaprogramming.md)
- [Normalization](https://banes-lab.com/records/architecture/normalization.md)
- [Do Not Repeat Yourself (DRY) / Locality of Behavior](https://banes-lab.com/records/tension/do-not-repeat-yourself-dry-locality-of-behavior.md)
- [Do Not Repeat Yourself (DRY) / Simplicity](https://banes-lab.com/records/tension/do-not-repeat-yourself-dry-simplicity.md)
- [quality-attribute](https://banes-lab.com/records/kind/quality-attribute.md)
- [Encapsulation](https://banes-lab.com/records/architecture/encapsulation.md)
- [Over-Specialization](https://banes-lab.com/records/lexicon/over-specialization.md)
- [Utility Dump](https://banes-lab.com/records/architecture/utility-dump.md)
- [Shotgun Surgery](https://banes-lab.com/records/architecture/shotgun-surgery.md)
- [High Cohesion / Over-Specialization](https://banes-lab.com/records/tension/high-cohesion-over-specialization.md)
- [Architecture Review](https://banes-lab.com/records/architecture/architecture-review.md)
- [Stable Interfaces](https://banes-lab.com/records/architecture/stable-interfaces.md)
- [Portability](https://banes-lab.com/records/architecture/portability.md)
- [Independent Deployment](https://banes-lab.com/records/lexicon/independent-deployment.md)
- [Independent Testing](https://banes-lab.com/records/lexicon/independent-testing.md)
- [Runtime Indirection](https://banes-lab.com/records/lexicon/runtime-indirection.md)
- [Tight Coupling](https://banes-lab.com/records/lexicon/tight-coupling.md)
- [Circular Dependency](https://banes-lab.com/records/architecture/circular-dependency.md)
- [Inappropriate Intimacy](https://banes-lab.com/records/architecture/inappropriate-intimacy.md)
- [Message Chain](https://banes-lab.com/records/architecture/message-chain.md)
- [Anti-Corruption Layer](https://banes-lab.com/records/architecture/anti-corruption-layer.md)
- [Information Hiding](https://banes-lab.com/records/architecture/information-hiding.md)
- [Composition Over Inheritance](https://banes-lab.com/records/architecture/composition-over-inheritance.md)
- [Independence](https://banes-lab.com/records/architecture/independence.md)
- [Dependency Inversion Principle](https://banes-lab.com/records/architecture/dependency-inversion.md)
- [Event-Driven Architecture](https://banes-lab.com/records/architecture/event-driven-architecture.md)
- [Publish/Subscribe Pattern](https://banes-lab.com/records/architecture/publish-subscribe-pattern.md)
- [Message Broker](https://banes-lab.com/records/architecture/message-broker.md)
- [Asynchronous Communication](https://banes-lab.com/records/architecture/asynchronous-communication.md)
- [Mediator Pattern](https://banes-lab.com/records/architecture/mediator-pattern.md)
- [Service-Oriented Architecture](https://banes-lab.com/records/architecture/service-oriented-architecture.md)
- [Low Coupling / Runtime Indirection](https://banes-lab.com/records/tension/low-coupling-runtime-indirection.md)
- [Domain Purity](https://banes-lab.com/records/lexicon/domain-purity.md)
- [Global State](https://banes-lab.com/records/lexicon/global-state.md)
- [Dependency Injection](https://banes-lab.com/records/architecture/dependency-injection.md)
- [Low Coupling](https://banes-lab.com/records/architecture/low-coupling.md)
- [Change Isolation](https://banes-lab.com/records/lexicon/change-isolation.md)
- [Invariant Protection](https://banes-lab.com/records/lexicon/invariant-protection.md)
- [Debuggability](https://banes-lab.com/records/lexicon/debuggability.md)
- [Exposed Internals](https://banes-lab.com/records/lexicon/exposed-internals.md)
- [Feature Envy](https://banes-lab.com/records/architecture/feature-envy.md)
- [Aggregate](https://banes-lab.com/records/architecture/aggregate.md)
- [Value Object](https://banes-lab.com/records/architecture/value-object.md)
- [Entity](https://banes-lab.com/records/architecture/entity.md)
- [Invariant](https://banes-lab.com/records/architecture/invariant.md)
- [Introspection](https://banes-lab.com/records/architecture/introspection.md)
- [Memento Pattern](https://banes-lab.com/records/architecture/memento-pattern.md)
- [Factory Pattern](https://banes-lab.com/records/architecture/factory-pattern.md)
- [Facade Pattern](https://banes-lab.com/records/architecture/facade-pattern.md)
- [Proxy Pattern](https://banes-lab.com/records/architecture/proxy-pattern.md)
- [State Isolation](https://banes-lab.com/records/architecture/state-isolation.md)
- [Encapsulation / Debuggability](https://banes-lab.com/records/tension/debuggability-encapsulation.md)
- [Immutability](https://banes-lab.com/records/architecture/immutability.md)
- [Explicit Interfaces](https://banes-lab.com/records/lexicon/explicit-interfaces.md)
- [Internal Refactoring](https://banes-lab.com/records/lexicon/internal-refactoring.md)
- [Observability](https://banes-lab.com/records/architecture/observability.md)
- [Leaky Abstraction](https://banes-lab.com/records/lexicon/leaky-abstraction.md)
- [Information Hiding / Observability](https://banes-lab.com/records/tension/information-hiding-observability.md)
- [Stable Semantics](https://banes-lab.com/records/lexicon/stable-semantics.md)
- [Interface Definition](https://banes-lab.com/records/lexicon/interface-definition.md)
- [Polymorphism](https://banes-lab.com/records/architecture/polymorphism.md)
- [Concrete Coupling](https://banes-lab.com/records/architecture/concrete-coupling.md)
- [Middle Man](https://banes-lab.com/records/architecture/middle-man.md)
- [Dynamic Binding](https://banes-lab.com/records/architecture/dynamic-binding.md)
- [Interface-Based Design](https://banes-lab.com/records/architecture/interface-based-design.md)
- [Do Not Repeat Yourself](https://banes-lab.com/records/architecture/duplicate-code.md)
- [Inversion of Control](https://banes-lab.com/records/architecture/inversion-of-control.md)
- [Abstraction / Simplicity](https://banes-lab.com/records/tension/abstraction-simplicity.md)
- [Plugin Architecture](https://banes-lab.com/records/architecture/plugin-architecture.md)
- [Cross-Cutting Concerns](https://banes-lab.com/records/lexicon/cross-cutting-concerns.md)
- [Big Ball of Mud](https://banes-lab.com/records/architecture/big-ball-of-mud.md)
- [Bounded Context](https://banes-lab.com/records/architecture/bounded-context.md)
- [Component-Based Architecture](https://banes-lab.com/records/architecture/component-based-architecture.md)
- [Package by Feature](https://banes-lab.com/records/architecture/package-by-feature.md)
- [Modularity / Cross-Cutting Concerns](https://banes-lab.com/records/tension/cross-cutting-concerns-modularity.md)
- [Autonomy](https://banes-lab.com/records/architecture/autonomy.md)
- [Shared Mutable State](https://banes-lab.com/records/architecture/shared-mutable-state.md)
- [Boundary Leakage](https://banes-lab.com/records/architecture/boundary-leakage.md)
- [Fitness Functions](https://banes-lab.com/records/architecture/fitness-functions.md)
- [recommended](https://banes-lab.com/records/vocabulary/severity-recommended.md)
- [Pipeline Architecture](https://banes-lab.com/records/architecture/pipeline-architecture.md)
- [Performance Overhead](https://banes-lab.com/records/lexicon/performance-overhead.md)
- [Monolithic Procedures](https://banes-lab.com/records/lexicon/monolithic-procedures.md)
- [Decorator Pattern](https://banes-lab.com/records/architecture/decorator-pattern.md)
- [Composability / Performance Overhead](https://banes-lab.com/records/tension/composability-performance-overhead.md)
- [Hidden Side Effect](https://banes-lab.com/records/architecture/hidden-side-effect.md)
- [Incompatible Interfaces](https://banes-lab.com/records/lexicon/incompatible-interfaces.md)
- [Delegation](https://banes-lab.com/records/lexicon/delegation.md)
- [Strategy Pattern](https://banes-lab.com/records/architecture/strategy-pattern.md)
- [Simplicity for Trivial Reuse](https://banes-lab.com/records/lexicon/simplicity-for-trivial-reuse.md)
- [Deep Inheritance Hierarchy](https://banes-lab.com/records/lexicon/deep-inheritance-hierarchy.md)
- [Bridge Pattern](https://banes-lab.com/records/architecture/bridge-pattern.md)
- [Composition Over Inheritance / Simplicity for Trivial Reuse](https://banes-lab.com/records/tension/composition-over-inheritance-simplicity-for-trivial-reuse.md)
- [Stable Contracts](https://banes-lab.com/records/lexicon/stable-contracts.md)
- [Shared Libraries](https://banes-lab.com/records/lexicon/shared-libraries.md)
- [Product Lines](https://banes-lab.com/records/lexicon/product-lines.md)
- [YAGNI](https://banes-lab.com/records/lexicon/yagni.md)
- [Over-Generalization](https://banes-lab.com/records/lexicon/over-generalization.md)
- [Context-Specific Coupling](https://banes-lab.com/records/lexicon/context-specific-coupling.md)
- [Reusability / YAGNI](https://banes-lab.com/records/tension/reusability-yagni.md)
- [Reusability / Over-Generalization](https://banes-lab.com/records/tension/over-generalization-reusability.md)
- [Ports and Adapters](https://banes-lab.com/records/lexicon/ports-and-adapters.md)
- [Vendor Swap](https://banes-lab.com/records/lexicon/vendor-swap.md)
- [Deep Optimization](https://banes-lab.com/records/lexicon/deep-optimization.md)
- [Protocol Independence](https://banes-lab.com/records/architecture/protocol-independence.md)
- [Interchangeability](https://banes-lab.com/records/architecture/interchangeability.md)
- [Adapter Pattern](https://banes-lab.com/records/architecture/adapter-pattern.md)
- [Ports and Adapters Architecture](https://banes-lab.com/records/architecture/ports-and-adapters-architecture.md)
- [Replaceability / Deep Optimization](https://banes-lab.com/records/tension/deep-optimization-replaceability.md)
- [Contract Compatibility](https://banes-lab.com/records/lexicon/contract-compatibility.md)
- [Strategy Swap](https://banes-lab.com/records/lexicon/strategy-swap.md)
- [Specialized Optimization](https://banes-lab.com/records/lexicon/specialized-optimization.md)
- [Implementation-Specific Contracts](https://banes-lab.com/records/lexicon/implementation-specific-contracts.md)
- [Abstract Factory Pattern](https://banes-lab.com/records/architecture/abstract-factory-pattern.md)
- [Interchangeability / Specialized Optimization](https://banes-lab.com/records/tension/interchangeability-specialized-optimization.md)
- [Schema Validation](https://banes-lab.com/records/architecture/schema-validation.md)
- [Coordination Cost](https://banes-lab.com/records/lexicon/coordination-cost.md)
- [Shared Runtime Dependency](https://banes-lab.com/records/lexicon/shared-runtime-dependency.md)
- [Independence / Coordination Cost](https://banes-lab.com/records/tension/coordination-cost-independence.md)
- [contextual](https://banes-lab.com/records/vocabulary/severity-contextual.md)
- [Own Data](https://banes-lab.com/records/lexicon/own-data.md)
- [Explicit Contracts](https://banes-lab.com/records/architecture/explicit-contracts.md)
- [Decentralization](https://banes-lab.com/records/architecture/decentralization.md)
- [Resilience](https://banes-lab.com/records/architecture/resilience.md)
- [Microservices](https://banes-lab.com/records/architecture/microservices.md)
- [Bounded Context Ownership](https://banes-lab.com/records/lexicon/bounded-context-ownership.md)
- [Governance](https://banes-lab.com/records/architecture/governance.md)
- [Standardization](https://banes-lab.com/records/architecture/standardization.md)
- [Global Consistency](https://banes-lab.com/records/lexicon/global-consistency.md)
- [Centralized Runtime Control](https://banes-lab.com/records/lexicon/centralized-runtime-control.md)
- [Shared Database](https://banes-lab.com/records/lexicon/shared-database.md)
- [Cyclic Deployment Dependency](https://banes-lab.com/records/architecture/cyclic-deployment-dependency.md)
- [Service Contract](https://banes-lab.com/records/architecture/service-contract.md)
- [Choreography](https://banes-lab.com/records/architecture/choreography.md)
- [Autonomy / Governance](https://banes-lab.com/records/tension/autonomy-governance.md)
- [Autonomy / Standardization](https://banes-lab.com/records/tension/autonomy-standardization.md)
- [Autonomy / Global Consistency](https://banes-lab.com/records/tension/autonomy-global-consistency.md)
## Linked from
- [The layer topology](https://banes-lab.com/ontology/schema/the-layer-topology.md)
- [The membership](https://banes-lab.com/ontology/schema/the-membership.md)