A sound implementation does not ask users to refresh until it works. Each phase has an input, an output, a timeout, and a terminal state. At-least-once delivery and duplicated listeners are normal. If every message immediately creates a task and toast, one fact causes repeated side effects.
Frontend architecture is about state ownership, repeatable events, invalidation of stale async work, and cleanup after unmount—not the shape of the source directory.
Define the system contract first
Start from facts the data and protocol can guarantee, then decide what the interface may promise. Each rule below needs an owner, a bound, and a compatibility policy rather than an oral convention from one review.
- Give protocol events stable IDs and record the applied version before side effects.
- Upsert entities by request or transfer ID so duplicates update one record.
- Create an intent ID for actions and disable the same intent until terminal state instead of relying on debounce.
Idempotency is not hiding duplicate UI. Entity updates and external effects execute once under stable IDs, making retries safe.
What can break that contract
Prioritize faults that silently preserve false facts: the interface looks recovered while a queue, permission, or counter has diverged. The defect often appears only on the next action.
- The dedupe set is memory-only, so replay after refresh creates the same notification.
- Text-based dedupe drops a legitimate identical message from another sender.
- Download runs before the applied marker, so crash and replay execute it twice.
How to test the contract line by line
Observe both endpoints, persisted records, and operational signals during verification. One button state or one successful response cannot prove the complete loop.
- Duplicate, reorder, and replay every event across refresh while asserting entities and toast counts.
- Double-click while the server retries and verify one intent and one external side effect.
- Test dedupe expiry boundaries while stale-session events remain unable to mutate new entities.
The result must be correct, recoverable, and explainable. If any part depends on refreshing the page or an engineer guessing, the protocol loop remains incomplete.