A capability stays maintainable only when the team can explain every state, retry, and piece of residual data—not merely show one successful run. Three booleans create eight combinations, most meaningless. Reordered callbacks produce connected-and-connecting or stopped-but-retrying; a state machine makes legal transitions explicit.
Frontend architecture is about state ownership, repeatable events, invalidation of stale async work, and cleanup after unmount—not the shape of the source directory.
Questions the design must answer
Write the following choices as reviewable rules instead of scattering them across callbacks and UI conditions. Explicit rules make scaling, compatibility, and diagnosis less dependent on guesswork.
- List stable, transient, and terminal states and allow each event from explicit sources.
- Start effects in entry or exit actions and fence old asynchronous callbacks by state version.
- Derive buttons, labels, and disabled conditions from one state instead of a second boolean truth.
A state machine turns races from lucky timing into rejectable invalid transitions and gives UI, effects, and persistence one source of truth.
Edge cases are part of the feature
Boundaries turn hidden assumptions into incidents. Weak networks, refresh, concurrency, and capacity need combined coverage because retries can hide each one in isolation.
- A stale session connected event moves a stopped machine back online.
- Failure loses stage and retryability by collapsing every error into idle.
- A fix assigns state directly and bypasses guards and cleanup actions.
Prove that it works with evidence
Do not stop verification when the final action succeeds. Count side effects, measure wait time, inspect privacy, and prove the next run begins from a clean baseline.
- Generate every state-event pair and assert illegal transitions do not mutate state.
- Randomize timeout, approval, rejection, close, and reconnect events; final state must be explainable.
- Refresh from every transient state and allow restoration only through defined recovery entries.
The release bar is clear: users understand the current state, failures stop or recover, resources stay bounded, and operators can identify the phase from minimum necessary evidence.