Context
Upload failures and intermediate states often originate from low-level systems (network, storage, validation, permissions). Exposing raw technical errors or internal state names directly in the UI leads to:
- confusing user experience
- leakage of internal implementation details
- noisy and intimidating error messages
- brittle UI coupled to backend internals
The upload UI must communicate status clearly without requiring users to understand infrastructure concepts.
Decision
All upload states and errors exposed to the UI must be human-readable and user-centric.
UI-facing states use descriptive labels such as:
- “Uploading”
- “Processing”
- “Completed”
- “Needs Attention”
Technical details (error codes, stack traces, provider messages) are:
- not shown by default
- optionally available behind secondary affordances (e.g. tooltip, details view)
Consequences
- Upload UI remains calm and understandable
- Users can act without technical knowledge
- Backend and storage internals remain encapsulated
- UI copy can evolve independently of engine implementation
- Localization and copy changes are clearly scoped
Notes
- This decision explicitly separates:
- engine-level state (technical, internal)
- UI-level state (descriptive, actionable)
- Any direct exposure of raw technical errors in the primary upload UI is considered a violation of this ADR.