ADR-007: Error Handling Architecture

Context

Error handling in ONECMS spans multiple layers including execution logic, transports, and UI rendering.
Without an explicit architectural decision, error handling risks becoming inconsistent, with unclear boundaries around normalization, transport semantics, and UI containment.

A decision was required to:

• prevent unknown errors from leaking across layers
• decouple domain errors from transport and UI concerns
• establish a predictable and repeatable error handling model

This ADR reflects the error handling model already implemented and in use.

Decision

ONECMS adopts a layered error handling architecture with explicit responsibilities:

• Execution boundaries normalize all thrown values into a canonical error type.
• AppError is the single, portable error primitive used across the system.
• ErrorMap defines stable error codes, messages, and transport semantics.
• Transport layers adapt AppError to protocol-specific responses.
• UI error boundaries contain unhandled failures and present safe fallback UI.

Each layer is responsible only for its scope and must not subsume responsibilities from other layers.

Consequences

• Errors are normalized early and handled deterministically.
• unknown values do not propagate beyond execution boundaries.
• Transport and UI layers remain decoupled from domain error creation.
• Error exposure is consistent and externally safe.
• The system favors explicit boundaries over implicit or global interception.

Trade-offs accepted:

• Additional structure and ceremony around error creation
• Explicit boundaries instead of convenience-based handling

Notes

• Detailed behavior and usage are documented under Error Handling.
• Deviations from this model require a new ADR that supersedes this one.