unfolding-architecture

name	unfolding-architecture
description	This skill should be used when the user asks to "design the architecture", "should I add a service layer", "add an abstraction", "introduce an interface", "separate concerns", "add a repository", "use hexagonal architecture", "add domain events", "split into layers", "add ports and adapters", "decouple this", "add an anti-corruption layer", "review package structure", or when considering architectural changes during a TDD refactor phase. It also contains guides when starting a new project.
version	0.1.0

Unfolding Architecture

Progressive architectural decisions: start simple, add complexity only when it reduces complexity.

Architecture is not a blueprint drawn before construction. It unfolds from working code under concrete pressure. Each dimension of architecture starts at its simplest form (Level 0) and only moves to a higher level when a specific, demonstrable problem forces the change.

Default Starting Point

Level 0 in all dimensions. No deviation without a concrete reason backed by a violated constraint, or measurable complexity increase. "It might be useful later" is never a valid reason to unfold.

Dimensions

1. Data vs Logic

Level	Style	Description
0	OOP: data + logic together	Data and the logic that operates on it live in the same class. Logic hides data. This is the natural OOP default.
1	DOP: separate data from algorithms	Stable data structures with varying algorithms applied externally. Data is transparent; logic is separate.

Unfold to Level 1 when:

• Multiple independent algorithms need to operate on the same data
• Data structures are stable but processing varies significantly
• Serialization/deserialization concerns conflict with behavior encapsulation

Do NOT unfold when:

• Data and logic change together (they belong together)
• There is only a hand full of algorithms per data structure that are closely related to the data
• The separation would scatter related behavior across files

2. Indirection

Level	Style	Description
0	Direct dependencies	Everything knows about everything it uses. No interfaces, no layers, no DTOs. Persistence lives next to domain.
1	Targeted abstraction	Interface or anti-corruption layer at a specific pain point — persistence, external API, or unstable component.
2	Ports & adapters (hexagonal)	Full separation of domain from infrastructure via IoC: the domain defines ports (interfaces), adapters implement them, dependencies point inward. Persistence is just one adapter among many. A composition root wires adapters to ports.

Unfold to Level 1 when:

• A component has multiple concrete implementations that must be swappable
• A dependency crosses a deployment boundary (e.g., external service)
• Testing requires replacing a real dependency with a test double, e.g. calling an external service
• An external system's model leaks into and distorts the domain model
• An external API returns data in a shape that does not match domain concepts
• Changes in one component frequently force changes in an unrelated component
• Persistence technology needs to change and the domain should not be affected

Unfold to Level 2 when:

• Multiple adapters exist for the same port (e.g., database + in-memory for tests, but there is no suitable abstraction layer available in the platform, e.g. an EntityManager)
• It becomes too complex to test the domain in isolation from real infrastructure
• The system has many distinct infrastructure concerns (persistence, messaging, external APIs, etc.) that would clutter the domain

Do NOT unfold when:

• Only one implementation exists, and it can be seen as an implementation or model detail of the domain
• The "interface" would mirror the class 1:1 (interface bloat)
• The coupling is between genuinely related concepts (cohesion, not coupling)
• DTOs or DB Entities would be identical copies of domain objects (except for some annotations, etc.)
• The "boundary" is between two internal components that change together
• The application has a single persistence mechanism and no external integrations

Note: Even hexagonal architecture can evolve step-by-step. You do not need to introduce all ports and adapters at once. Start with a single targeted abstraction (Level 1) where the pressure is highest, then add more ports as concrete needs arise. Full hexagonal (Level 2) is the result of multiple incremental unfoldings, not a single architectural decision.

3. Communication

Level	Style	Description
0	Direct method calls	Components call each other directly. Simple, traceable, debuggable.
1	Domain events (in-process)	Components publish events that other components react to, but within the same process.
2	Async messaging (broker)	Communication through a message broker. Full decoupling of sender and receiver in time and space.

Unfold to Level 1 when:

• An action must trigger multiple independent side effects (e.g., send email AND update audit log) that change independently of the triggering action
• Circular dependencies emerge between components that cannot easily be resolved by other means

Unfold to Level 2 when:

• Components must be deployed and scaled independently
• Temporal decoupling is required (sender must not wait for receiver)
• The system spans multiple processes or services
• Exactly-one guarantees are necessary (mostly using Two-Phase-Commits)

Do NOT unfold when:

• There is only one consumer for each action
• Traceability and debuggability are more important than decoupling
• The indirection would obscure a simple, linear flow

4. Package Structure Guarantees

Level	Style	Description
0	Manual	No enforced dependency rules between packages. Any class can use any other class (as long as it's public).
1	Package dependency tests	Packages exist with clear responsibilities. Dependency rules between packages are enforced by tests.
2	Modulith	Separate modules within one deployable unit, each with explicit API boundaries and enforced encapsulation.
3	Microservices	Independent services, separately built and deployed, communicating over network boundaries.

Unfold to Level 1 when:

• The codebase grows beyond a handful of packages and accidental cross-package dependencies start appearing
• Changes in one package unexpectedly break another
• Package responsibilities become blurred because nothing enforces boundaries
• Dependency cycles emerge between packages

Unfold to Level 2 when:

• Dependency tests alone are insufficient to maintain isolation (too many rules, hard to reason about)
• Teams need stronger encapsulation with explicit public APIs per module
• You want independent module testing with enforced visibility constraints

Unfold to Level 3 when:

• Modules need independent scaling, i.e. scaling the full modulith to handle only a minor subset of functionality would be too expensive; this is often cited, but hardly really the case
• Different teams develop and deploy independently the different microservices
• Modules have different security requirements, so the non-critical parts make the attack surface too big for the critical ones

Do NOT unfold to Level 1 when:

• The system is small enough that a developer can hold the full dependency graph in their head

Do NOT unfold to Level 2 when:

• All packages change together and are released together (splitting adds overhead without benefit)

Do NOT unfold to Level 3 when:

• The team is small and communication overhead of service boundaries outweighs the decoupling benefit

5. Error Handling

Level	Style	Description
0	Exceptions	Throw exceptions for errors. Catch at appropriate boundaries. Simple and conventional.
1	Result types	Return result objects that explicitly model success and failure for business outcomes.
2	Circuit breakers / resilience	Resilience patterns for dealing with unreliable external dependencies.

Unfold to Level 1 when:

• Business logic has expected failure cases that are not exceptional (e.g., validation of user input)
• Callers must distinguish between multiple failure modes to make decisions
• Exception-based control flow obscures the business logic

Unfold to Level 2 when:

• External dependencies are unreliable and failures must be contained / backpressure applied
• Cascading failures are a real risk (not hypothetical)
• The system must degrade gracefully under partial failure, esp. on high load

Do NOT unfold when:

• Failures are truly exceptional and unexpected
• The language/framework has strong exception conventions that result types would fight
• There is no external dependency that warrants resilience patterns

Naming Conventions

• A companion class / repository / DAO to a domain entity should be the plural of the entity, e.g. Products for Product

How to Use

Unfolding happens during the TDD refactor phase:

1. Complete the Red-Green cycle — get the test passing first
2. During refactoring, check if any dimension is under pressure
3. Before unfolding, use AskUserQuestion to confirm:
   • Question: "I see pressure on [dimension] to unfold from Level N to N+1. Should we?"
   • Options:
     • "Yes, unfold (Recommended)" — include a one-line reason derived from the code (e.g., "Two independent algorithms now operate on the same data structure")
     • "No, keep current level" — explain what trade-off the user is accepting
     • "Let's discuss" — elaborate on the pressure signals before deciding
4. Unfold one dimension at a time — never unfold two dimensions simultaneously
5. Verify: all tests still pass after unfolding
6. Document the reason: state in one sentence why this unfolding was necessary

The decision checklist at decision-checklist.md provides a quick rubric.

Anti-Patterns

Speculative Architecture

Adding layers, interfaces, or patterns "because we might need them." If no concrete test or requirement demands it, do not add it.

Uniform Depth

Making all dimensions the same level. A system might legitimately need Level 2 indirection but Level 0 communication. Each dimension is independent.

Architecture Envy

Copying the architecture of a different system or a reference application. Architecture must emerge from the specific pressures of this system.

Premature DOP

Separating data from logic before multiple algorithms actually exist. Data and logic that change together should stay together.

Layer Cake

Adding layers for the sake of "proper architecture": Controller → Service → Repository → DAO, each doing nothing but delegating to the next. Every layer must justify its existence.

Integration with Other Skills

• TDD: Unfolding happens during refactor phases. A failing test or a refactoring need is the trigger — never unfold speculatively before a test demands it.
• Clean Code: Unfolding often shifts the indirection balance (Dimension 2). Apply clean code principles to evaluate whether the shift improves or worsens the design.
• APP: After unfolding, compare mass before and after. If mass increased without a proportional gain in clarity or testability, reconsider the change.