Layers

Purpose

FDD 4-layer decomposition — UI/SI/MD/PD as fundamental organizing principle

Context

Systems with multiple levels of abstraction where each level has a distinct responsibility. The system is large enough that mixing abstraction levels creates maintenance problems. Teams may own different layers independently. The system must support substitutability — replacing one layer's implementation without affecting others. Portability across platforms or environments is desirable.

Problem

How to organize a complex system so that each concern lives at an appropriate
level of abstraction, changes at one level do not cascade to unrelated levels,
and the dependency structure remains comprehensible?

Forces:
(1) Different parts of the system operate at different abstraction levels
(2) Changes to low-level mechanisms should not force changes in high-level policy
(3) Teams need clear ownership boundaries aligned with abstraction levels
(4) Components at the same level of abstraction should be interchangeable
(5) The dependency direction must be enforceable, not just conventional
(6) Cross-layer communication adds runtime overhead (indirection cost)
(7) Some use cases legitimately need to bypass intermediate layers (strict vs relaxed)

Solution

Decompose the system into an ordered set of layers, where each layer groups
subtasks at a single level of abstraction. Define a strict ordering: higher
layers depend on lower layers, never the reverse. Each layer exposes a public
interface (services it provides to the layer above) and has a private
implementation (how it uses the layer below). The bottom layer provides
foundational services independent of the application domain. The top layer
provides the user-facing entry points.

Choose strict or relaxed layering based on the system's performance and
complexity needs. Strict layering (each layer calls only the layer immediately
below) maximizes substitutability but adds indirection. Relaxed layering
(skip-level calls permitted) reduces indirection but increases coupling.

Consequences

Benefits: - Separation of concerns: each layer addresses one abstraction level - Substitutability: any layer can be replaced if its interface is preserved - Testability: lower layers can be tested in isolation from upper layers - Team independence: different teams can own and evolve layers separately - Portability: platform-specific code is confined to lower layers - Comprehensibility: the dependency structure is a simple linear ordering

Liabilities: - Performance overhead: each layer boundary adds indirection and potential marshalling - Cascading changes: modifying a lower layer's interface affects all layers above - Over-layering: too many layers add complexity without proportional benefit - Difficulty of correct decomposition: choosing the right layer boundaries requires deep understanding of the domain - Strict layering tension: real systems often need relaxed layering for performance, which weakens the pattern's guarantees - Entity identity dispersion: a single domain concept may have representations in every layer, requiring cross-layer traceability

Collaborations

Client initiates a request through the top Layer's interface. Each Layer transforms the request into operations at its abstraction level, delegating lower-level work to the Layer below via its LayerInterface. Results propagate upward: each Layer transforms lower-level responses into its own abstraction before returning to the Layer above. In strict layering, each Layer communicates only with its immediate neighbors. In relaxed layering, a Layer may bypass intermediate layers when the abstraction mapping is trivial.

Structure

Participants:
- Layer: a group of related subtasks at one abstraction level
- LayerInterface: the public contract exposed upward
- LayerImplementation: internal realization consuming the layer below
- Client: external consumer of the topmost layer

Relationships:
- Client uses top Layer (invocation)
- Layer(N) uses Layer(N-1) via LayerInterface (dependency — always downward)
- LayerImplementation realizes LayerInterface (implementation)
- Bottom Layer has no downward dependency (terminal)

SBX FDD 4-Layer Structure:
  Layer 4 (UI)  — Entry points, presentation, CLI commands, web components
  Layer 3 (SI)  — Adapters, infrastructure, external service connectors
  Layer 2 (MD)  — Types, schemas, value objects, documents, dictionaries
  Layer 1 (PD)  — Specifications, domain rules, protocols, governance

Implementation

In SBX Monorepo (FDD Layer Mapping):
  1. PD layer lives in `.sbx/` — YAML protocols, schemas, governance rules
  2. MD layer lives in `projects/sbx/packages/core/go/pkg/` — Go types, schemas
  3. SI layer lives in `projects/sbx/packages/core/go/internal/` + `infrastructure/`
  4. UI layer lives in `projects/sbx/packages/core/go/cmd/` + `projects/*/web/`

Layer Boundary Enforcement:
  1. Go package imports enforce direction: cmd/ imports internal/ imports pkg/
  2. .sbx/ protocols are read-only data consumed by MD layer parsers
  3. SI adapters implement interfaces defined in MD (dependency inversion at boundary)
  4. UI components receive pre-validated data from SI, never call PD directly

Choosing Strict vs Relaxed:
  1. Default to strict layering — maximize substitutability
  2. Profile before relaxing — measure actual performance cost of indirection
  3. If relaxing, document the skip-level dependency explicitly
  4. Never allow upward dependencies — this is non-negotiable regardless of layering mode

Example

Consider a workspace automation framework (SBX) that must manage entities across
four distinct concerns: the specifications and domain rules that define what an
entity IS (problem domain), the types and schemas that give it structure (model
domain), the adapters and infrastructure that connect it to external systems
(service integration), and the entry points and visual representations that
expose it to users (user interface). Without layering, these concerns interleave
freely — a CLI command directly manipulates database schemas, a UI component
embeds business rules, and an adapter hard-codes domain logic. Changes to any
concern ripple unpredictably through the entire codebase. When a new client
project is onboarded, there is no clear boundary between what can be customized
(UI, SI) and what must remain stable (MD, PD).

Resolution

Applying layers to the SBX workspace framework: the FDD 4-layer model assigns
each concern to exactly one layer. Protocol specifications (PD) define what
entities are. Go types and schemas (MD) give them structure. Filesystem and
database adapters (SI) connect them to storage. CLI commands and web dashboards
(UI) expose them to users. When a new client (Bestie) is onboarded, the UI and
SI layers are customized while MD and PD layers are shared. When the storage
backend changes from filesystem to PostgreSQL, only SI adapters are replaced.
The entity modeling guideline (knowledge/guidelines/architecture/entity-modeling) traces through
all four layers, with each activity executing at the appropriate abstraction level.

Known Uses

OSI 7-Layer Network Model — physical, data link, network, transport, session, presentation, application
TCP/IP 4-Layer Stack — link, internet, transport, application
FDD 4-Layer Decomposition (Coad/Palmer) — UI, SI, MD, PD — adopted as SBX's fundamental organizing principle
Clean Architecture (Robert C. Martin) — entities, use cases, interface adapters, frameworks
Java EE N-Tier — presentation (JSF), business (EJB), integration (JPA), resource (JDBC)

Tags

Overview