marketplaces/docs/architecture/foundation/adr/ADR-002-layered-feature-architecture.md

ADR-002: Layered Feature Architecture with Single Responsibility

Status: Accepted Date: 2026-07-03

Context

The platform must support Website, Builder, and Backoffice while keeping shared capabilities reusable and independent.

Decision

Adopt the following architecture layers and responsibilities:

• Core: bootstrap, app wiring, global policies, base adapters.
• Shared: pure contracts, pure utilities, generic primitives.
• UI Library: reusable presentational components only.
• Widgets: configurable functional blocks built from UI components.
• Layouts: page section composition and structural orchestration.
• Pages: route containers mapping configuration to layouts/widgets.
• Website: public commerce experience.
• Builder: configuration editing domain.
• Backoffice: business data management domain.

Single responsibility is mandatory for each layer.

Consequences

Positive:

• Predictable layering and ownership.
• Higher reuse across Website, Builder, and Backoffice.
• Reduced accidental coupling.

Negative:

• Requires import boundary enforcement.
• Requires upfront contracts before feature implementation.

Compliance Requirements

• Shared and UI layers cannot depend on feature layers.
• Feature layers interact through contracts/facades, not direct imports.
• New artifacts must be placed in the correct layer folder.