How We Lost 9 Months to Invisible Architecture Decay (And Fixed It in 3)

The Problem Nobody Names Six months into the medical CRM calendar project, I opened a PR and spent twenty minutes just figuring out which slice owned the appointment state. The code wasn't broken. It wasn't even obviously wrong. It had just quietly become something else. We kept calling it "technical debt" — but that wasn't quite right either. Technical debt implies a conscious trade-off: ship now, fix later. What we had was different. Nobody made a bad call. Every decision was defensible. But stack twelve defensible decisions on top of each other, and you end up somewhere nobody intended to go. ship now, fix later. We started calling it Architecture Decision Degradation (ADD): the gradual erosion of architectural quality through accumulated compromises. No dramatic breaking point. Just a slow creep — invisible until sprint velocity fell off a cliff. Architecture Decision Degradation (ADD) This is the story of how it happened on a medical CRM calendar planner, with 18 months of real metrics, real code, and a refactor that got us back. What Is Architecture Decision Degradation? ADD is different from "technical debt." Technical debt is a conscious trade-off: ship now, fix later. ADD is unintended erosion — architecture degrading even when teams make "correct" decisions at every step. The scary part? Nobody made a "bad" decision. Each step felt correct in isolation. But stack them up over six months, and the architecture becomes barely recognizable. ship now, fix later. unintended erosion ADD follows a predictable lifecycle: Phase Timeline What's happening Complexity Creep Months 1–9 Slice proliferation, inconsistent patterns Race Conditions Months 10–14 Real-time updates collide with optimistic state Velocity Collapse Months 15+ 40%+ bugs from state, rewrites discussed Phase Timeline What's happening Complexity Creep Months 1–9 Slice proliferation, inconsistent patterns Race Conditions Months 10–14 Real-time updates collide with optimistic state Velocity Collapse Months 15+ 40%+ bugs from state, rewrites discussed Phase Timeline What's happening Phase Phase Timeline Timeline What's happening What's happening Complexity Creep Months 1–9 Slice proliferation, inconsistent patterns Complexity Creep Complexity Creep Complexity Creep Months 1–9 Months 1–9 Slice proliferation, inconsistent patterns Slice proliferation, inconsistent patterns Race Conditions Months 10–14 Real-time updates collide with optimistic state Race Conditions Race Conditions Race Conditions Months 10–14 Months 10–14 Real-time updates collide with optimistic state Real-time updates collide with optimistic state Velocity Collapse Months 15+ 40%+ bugs from state, rewrites discussed Velocity Collapse Velocity Collapse Velocity Collapse Months 15+ Months 15+ 40%+ bugs from state, rewrites discussed 40%+ bugs from state, rewrites discussed In our case, we didn't see it until Month 16. By then, we were looking at a full 3-month refactor. We Started So Well Building a drag-and-drop calendar for scheduling doctor appointments seemed straightforward. The team made all the "right" decisions upfront: Colocated state in Redux-Toolkit (no prop drilling) createSelector for memoization createAsyncThunk for async handling Optimistic updates for drag-and-drop Colocated state in Redux-Toolkit (no prop drilling) createSelector for memoization createSelector createAsyncThunk for async handling createAsyncThunk Optimistic updates for drag-and-drop Month 1 — clean architecture: Month 1 — clean architecture: // store/slices/appointmentsSlice.ts const appointmentsSlice = createSlice({ name: 'appointments', initialState: [] as Appointment[], reducers: { addAppointment: (state, action) => { state.push(action.payload); }, updateAppointment: (state, action) => { const index = state.findIndex(a => a.id === action.payload.id); state[index] = action.payload; } } }); export const selectAppointments = (state: RootState) => state.appointments; // store/slices/appointmentsSlice.ts const appointmentsSlice = createSlice({ name: 'appointments', initialState: [] as Appointment[], reducers: { addAppointment: (state, action) => { state.push(action.payload); }, updateAppointment: (state, action) => { const index = state.findIndex(a => a.id === action.payload.id); state[index] = action.payload; } } }); export const selectAppointments = (state: RootState) => state.appointments; Team velocity was high. The architecture felt solid — and that feeling of "man, this is clean" was the first warning sign we completely missed. Phase 1: Complexity Creep (Months 3–9) New requirements arrived one by one: Real-time backend updates via WebSocket Proactive conflict detection during drag Filters by doctor, specialty, date range Team grew: 2 → 5 developers, each adding their own slices Real-time backend updates via WebSocket Proactive conflict detection during drag Filters by doctor, specialty, date range Team grew: 2 → 5 developers, each adding their own slices What started as 3 slices became 10: // Month 3: appointmentsSlice, doctorsSlice, timeSlotsSlice // Month 9: 10 slices and counting... // store/slices/appointmentsSlice.ts — 600+ lines // store/slices/appointmentsCacheSlice.ts — 200 lines // store/slices/conflictsSlice.ts — 180 lines // store/slices/dragDropSlice.ts — 250 lines // store/slices/filtersSlice.ts — 150 lines // store/slices/filtersPersistenceSlice.ts — 80 lines // store/slices/validationSlice.ts — 200 lines // store/slices/uiSlice.ts — 180 lines // store/slices/notificationsSlice.ts — 140 lines // store/slices/websocketSlice.ts — 200 lines // Month 3: appointmentsSlice, doctorsSlice, timeSlotsSlice // Month 9: 10 slices and counting... // store/slices/appointmentsSlice.ts — 600+ lines // store/slices/appointmentsCacheSlice.ts — 200 lines // store/slices/conflictsSlice.ts — 180 lines // store/slices/dragDropSlice.ts — 250 lines // store/slices/filtersSlice.ts — 150 lines // store/slices/filtersPersistenceSlice.ts — 80 lines // store/slices/validationSlice.ts — 200 lines // store/slices/uiSlice.ts — 180 lines // store/slices/notificationsSlice.ts — 140 lines // store/slices/websocketSlice.ts — 200 lines The selector chain that followed: export const selectFilteredAppointmentsWithConflicts = createSelector( [ selectAppointments, selectConflicts, selectActiveFilters, selectDragPreview, selectValidationStatus ], (appointments, conflicts, filters, preview, validation) => { // 80+ lines of transformation logic return appointments .filter(apt => matchesFilters(apt, filters)) .map(apt => ({ ...apt, hasConflict: checkConflict(apt, conflicts, preview), isValid: checkValidation(apt, validation), isDragging: preview?.appointmentId === apt.id })); } ); // Changing ONE slice breaks ALL selectors. // No clear ownership. Re-renders cascade through the entire app. export const selectFilteredAppointmentsWithConflicts = createSelector( [ selectAppointments, selectConflicts, selectActiveFilters, selectDragPreview, selectValidationStatus ], (appointments, conflicts, filters, preview, validation) => { // 80+ lines of transformation logic return appointments .filter(apt => matchesFilters(apt, filters)) .map(apt => ({ ...apt, hasConflict: checkConflict(apt, conflicts, preview), isValid: checkValidation(apt, validation), isDragging: preview?.appointmentId === apt.id })); } ); // Changing ONE slice breaks ALL selectors. // No clear ownership. Re-renders cascade through the entire app. Metrics at Month 9: Metrics at Month 9: PR review time: 30 min → 2+ hours Onboarding new developers: 1 day → 3–5 days "Where is this state updated?" asked daily State-related bugs: 15% → 25% of all issues PR review time: 30 min → 2+ hours Onboarding new developers: 1 day → 3–5 days "Where is this state updated?" asked daily State-related bugs: 15% → 25% of all issues Phase 2: Race Condition Nightmare (Months 10–14) WebSocket + Optimistic Updates + Drag-and-Drop. In isolation, each decision made sense. Together, they created something we didn't have a name for at the time: // Scenario: user drags appointment to new time slot // 1. Optimistic update fires immediately dispatch(updateAppointmentOptimistic({ id: apt.id, newTimeSlot: newSlot })); // 2. WebSocket update arrives from backend onWebSocketMessage((msg) => { dispatch(updateAppointmentFromBackend(msg.data)); // Arrives BEFORE optimistic update settles → UI flickers, appointment jumps back }); // 3. API response arrives — may already be stale dispatch(updateAppointmentFulfilled(response)); // 4. Conflict check runs on stale state → false positives dispatch(checkAppointmentConflict(apt)); // Symptoms: // - Drag preview "snaps back" randomly // - Conflicts flash then disappear // - Appointment appears in TWO slots for 200ms // - Click handlers fire on wrong appointment // Scenario: user drags appointment to new time slot // 1. Optimistic update fires immediately dispatch(updateAppointmentOptimistic({ id: apt.id, newTimeSlot: newSlot })); // 2. WebSocket update arrives from backend onWebSocketMessage((msg) => { dispatch(updateAppointmentFromBackend(msg.data)); // Arrives BEFORE optimistic update settles → UI flickers, appointment jumps back }); // 3. API response arrives — may already be stale dispatch(updateAppointmentFulfilled(response)); // 4. Conflict check runs on stale state → false positives dispatch(checkAppointmentConflict(apt)); // Symptoms: // - Drag preview "snaps back" randomly // - Conflicts flash then disappear // - Appointment appears in TWO slots for 200ms // - Click handlers fire on wrong appointment The team responded with band-aids: // "Fix" #1: Debounce to mask the race condition const debouncedUpdate = useCallback( debounce((apt) => dispatch(updateAppointment(apt)), 300), [] ); // "Fix" #2: Version checking for stale updates if (response.version > state.version) { dispatch(updateFromBackend(response)); } // "Fix" #3: Pause WebSocket during drag useEffect(() => { if (isDragging) websocket.pause(); }, [isDragging]); // "Fix" #1: Debounce to mask the race condition const debouncedUpdate = useCallback( debounce((apt) => dispatch(updateAppointment(apt)), 300), [] ); // "Fix" #2: Version checking for stale updates if (response.version > state.version) { dispatch(updateFromBackend(response)); } // "Fix" #3: Pause WebSocket during drag useEffect(() => { if (isDragging) websocket.pause(); }, [isDragging]); I remember merging the WebSocket pause on a Thursday and thinking: finally, that's done. It wasn't done. We'd just moved the problem somewhere less visible. That's the trap with ADD — you're always debugging the last thing that broke, not the thing that's breaking everything. finally, that's done. The Breaking Point (Month 16) A developer spent 3 days debugging why appointments disappeared during drag-and-drop — but only when: WebSocket was active, another user was editing the same doctor, a filter was applied, and the browser tab was in the background (throttling). and Root cause: a selector chain reading from 7 slices with nondeterministic update order due to Redux batch timing. State of the codebase at Month 16: State of the codebase at Month 16: 10 slices, 3 with circular dependencies 20+ selectors reading from 3+ slices each 40% of all bugs related to state synchronization Velocity: 12 → 7 story points/sprint (−42%) New features taking 2× longer than Month 3 10 slices, 3 with circular dependencies 20+ selectors reading from 3+ slices each 40% of all bugs related to state synchronization Velocity: 12 → 7 story points/sprint (−42%) New features taking 2× longer than Month 3 Two options: keep patching and slow down further, or stop everything and restructure. The Fix: Three Architectural Principles The refactor took 3 months and was built on three principles. Principle 1: Consolidated Domain Slices 10 slices → 3, organized by domain responsibility: // store/slices/entitiesSlice.ts — all data const entitiesSlice = createSlice({ name: 'entities', initialState: { appointments: byId (), doctors: byId (), timeSlots: byId () }, reducers: { upsertEntity: (state, action) => { const { entityType, id, data } = action.payload; state[entityType][id] = { ...state[entityType][id], ...data }; } } }); // store/slices/uiSlice.ts — UI-only state const uiSlice = createSlice({ name: 'ui', initialState: { dragPreview: null, activeFilters: {}, openModals: [], validationErrors: {} }, reducers: { setDragPreview: (state, action) => { state.dragPreview = action.payload; } } }); // store/slices/sessionSlice.ts — session state const sessionSlice = createSlice({ name: 'session', initialState: { currentUser: null, websocketStatus: 'disconnected', pendingTransactions: {} }, reducers: { setWebsocketStatus: (state, action) => { state.websocketStatus = action.payload; } } }); // store/slices/entitiesSlice.ts — all data const entitiesSlice = createSlice({ name: 'entities', initialState: { appointments: byId (), doctors: byId (), timeSlots: byId () }, reducers: { upsertEntity: (state, action) => { const { entityType, id, data } = action.payload; state[entityType][id] = { ...state[entityType][id], ...data }; } } }); // store/slices/uiSlice.ts — UI-only state const uiSlice = createSlice({ name: 'ui', initialState: { dragPreview: null, activeFilters: {}, openModals: [], validationErrors: {} }, reducers: { setDragPreview: (state, action) => { state.dragPreview = action.payload; } } }); // store/slices/sessionSlice.ts — session state const sessionSlice = createSlice({ name: 'session', initialState: { currentUser: null, websocketStatus: 'disconnected', pendingTransactions: {} }, reducers: { setWebsocketStatus: (state, action) => { state.websocketStatus = action.payload; } } }); Principle 2: Transaction Middleware — Solving Race Conditions Properly The core idea: wrap every optimistic update in an explicit transaction with a commit and rollback. A Redux middleware intercepts actions tagged with meta.transaction, saves a snapshot of the state before the optimistic update, and discards any conflicting WebSocket updates that arrive while the transaction is still pending. If the API call fails — it rolls back to the snapshot. meta.transaction Instead of masking race conditions with debounce, the team built explicit transaction boundaries: // middleware/transactionMiddleware.ts const transactionMiddleware: Middleware = store => next => action => { if (!action.meta?.transaction) return next(action); const { id, phase } = action.meta.transaction; if (phase === 'optimistic') { store.dispatch({ type: 'transaction/begin', payload: { id, originalState: cloneDeep(store.getState()) } }); } // WebSocket update arrives during active transaction — discard it if (action.meta?.fromWebSocket) { const activeTransaction = selectActiveTransaction(store.getState(), id); if (activeTransaction) return; // Let optimistic update win } if (phase === 'commit') { store.dispatch({ type: 'transaction/commit', payload: { id } }); } if (phase === 'rollback') { store.dispatch({ type: 'transaction/rollback', payload: { id, originalState: action.payload.originalState } }); } return next(action); }; // middleware/transactionMiddleware.ts const transactionMiddleware: Middleware = store => next => action => { if (!action.meta?.transaction) return next(action); const { id, phase } = action.meta.transaction; if (phase === 'optimistic') { store.dispatch({ type: 'transaction/begin', payload: { id, originalState: cloneDeep(store.getState()) } }); } // WebSocket update arrives during active transaction — discard it if (action.meta?.fromWebSocket) { const activeTransaction = selectActiveTransaction(store.getState(), id); if (activeTransaction) return; // Let optimistic update win } if (phase === 'commit') { store.dispatch({ type: 'transaction/commit', payload: { id } }); } if (phase === 'rollback') { store.dispatch({ type: 'transaction/rollback', payload: { id, originalState: action.payload.originalState } }); } return next(action); }; Usage — drag-and-drop now bulletproof: const handleDragEnd = useCallback(async (result) => { const transactionId = uuid(); // 1. Optimistic update dispatch(moveAppointmentOptimistic({ appointmentId: result.draggableId, newTimeSlot: result.droppableId, meta: { transaction: { id: transactionId, phase: 'optimistic' } } })); try { // 2. API call await api.moveAppointment(result.draggableId, result.droppableId); // 3. Commit dispatch(moveAppointmentFulfilled({ meta: { transaction: { id: transactionId, phase: 'commit' } } })); } catch { // 4. Rollback on error dispatch(moveAppointmentRejected({ meta: { transaction: { id: transactionId, phase: 'rollback' } } })); } }, [dispatch]); const handleDragEnd = useCallback(async (result) => { const transactionId = uuid(); // 1. Optimistic update dispatch(moveAppointmentOptimistic({ appointmentId: result.draggableId, newTimeSlot: result.droppableId, meta: { transaction: { id: transactionId, phase: 'optimistic' } } })); try { // 2. API call await api.moveAppointment(result.draggableId, result.droppableId); // 3. Commit dispatch(moveAppointmentFulfilled({ meta: { transaction: { id: transactionId, phase: 'commit' } } })); } catch { // 4. Rollback on error dispatch(moveAppointmentRejected({ meta: { transaction: { id: transactionId, phase: 'rollback' } } })); } }, [dispatch]); Principle 3: Colocated Selectors with Single-Slice Ownership // selectors/appointments.ts — all appointment selectors in ONE file export const selectAppointmentById = (id: string) => (state: RootState) => state.entities.appointments[id]; export const selectAppointmentsByDoctor = (doctorId: string) => createSelector( [(state: RootState) => Object.values(state.entities.appointments)], (appointments) => appointments.filter(apt => apt.doctorId === doctorId) ); export const selectAppointmentsWithConflictStatus = createSelector( [ selectAppointmentsByDoctor(doctorId), (state: RootState) => state.entities.timeSlots ], (appointments, timeSlots) => appointments.map(apt => ({ ...apt, hasConflict: checkConflictWithTimeSlots(apt, timeSlots) })) ); // Each selector reads from ONE slice. No cross-slice chains. // selectors/appointments.ts — all appointment selectors in ONE file export const selectAppointmentById = (id: string) => (state: RootState) => state.entities.appointments[id]; export const selectAppointmentsByDoctor = (doctorId: string) => createSelector( [(state: RootState) => Object.values(state.entities.appointments)], (appointments) => appointments.filter(apt => apt.doctorId === doctorId) ); export const selectAppointmentsWithConflictStatus = createSelector( [ selectAppointmentsByDoctor(doctorId), (state: RootState) => state.entities.timeSlots ], (appointments, timeSlots) => appointments.map(apt => ({ ...apt, hasConflict: checkConflictWithTimeSlots(apt, timeSlots) })) ); // Each selector reads from ONE slice. No cross-slice chains. Results Before (Month 16) → After (Month 20): Before (Month 16) → After (Month 20): Metric Before After Δ Story points/sprint 7 11 ~+55% Total bugs/sprint 15–20 8–10 −50% State-related bugs 40% of total 15% of total −75% PR review time 2+ hours 45 min −62% Onboarding (state) 3–5 days 4 hours −80% Redux slices 10 (3 circular) 3 (clear domains) −70% Avg selector dependencies 3.5 slices 1.2 slices −66% Metric Before After Δ Story points/sprint 7 11 ~+55% Total bugs/sprint 15–20 8–10 −50% State-related bugs 40% of total 15% of total −75% PR review time 2+ hours 45 min −62% Onboarding (state) 3–5 days 4 hours −80% Redux slices 10 (3 circular) 3 (clear domains) −70% Avg selector dependencies 3.5 slices 1.2 slices −66% Metric Before After Δ Metric Metric Before Before After After Δ Δ Story points/sprint 7 11 ~+55% Story points/sprint Story points/sprint 7 7 11 11 ~+55% ~+55% Total bugs/sprint 15–20 8–10 −50% Total bugs/sprint Total bugs/sprint 15–20 15–20 8–10 8–10 −50% −50% State-related bugs 40% of total 15% of total −75% State-related bugs State-related bugs 40% of total 40% of total 15% of total 15% of total −75% −75% PR review time 2+ hours 45 min −62% PR review time PR review time 2+ hours 2+ hours 45 min 45 min −62% −62% Onboarding (state) 3–5 days 4 hours −80% Onboarding (state) Onboarding (state) 3–5 days 3–5 days 4 hours 4 hours −80% −80% Redux slices 10 (3 circular) 3 (clear domains) −70% Redux slices Redux slices 10 (3 circular) 10 (3 circular) 3 (clear domains) 3 (clear domains) −70% −70% Avg selector dependencies 3.5 slices 1.2 slices −66% Avg selector dependencies Avg selector dependencies 3.5 slices 3.5 slices 1.2 slices 1.2 slices −66% −66% Code reviews started focusing on business logic instead of state plumbing. Adding new features stopped feeling like defusing a bomb. ADD Is Not Just a Redux Problem Redux is where we felt it first — but it wasn't the only place. Around month 12, a backend developer mentioned in passing that they were up to 14 microservices for what started as 3. "We're not sure who owns user notifications anymore," he said. At the time I filed it away as a backend problem. It wasn't. It was the same pattern: every service added for a good reason, ownership dissolving gradually, circular dependencies appearing only after the fact. CI/CD does it too — config drift, duplicated deployment logic, the classic "works on staging, breaks on prod" that nobody can explain. Database schemas accumulate it in missed indexes and migrations that made sense in the moment. The stack doesn't matter. What matters is whether someone is actively watching the seams — because ADD doesn't announce itself. How to Recognize ADD Before It Kills Velocity Watch closely — act within 2–3 sprints: Watch closely — act within 2–3 sprints: 6+ slices with unclear domain boundaries Selectors regularly reading from 2+ slices State-related bugs exceed 25% of total New developers need more than 2 days to understand state flow 6+ slices with unclear domain boundaries Selectors regularly reading from 2+ slices State-related bugs exceed 25% of total New developers need more than 2 days to understand state flow Act immediately: Act immediately: 9+ slices and growing Circular dependencies between slices Race conditions appearing in production Velocity down 30%+ vs baseline over 3+ months 9+ slices and growing Circular dependencies between slices Race conditions appearing in production Velocity down 30%+ vs baseline over 3+ months Prevention template for new projects: Prevention template for new projects: store/ ├── slices/ │ ├── entitiesSlice.ts ← all data entities │ ├── uiSlice.ts ← UI-only state │ └── sessionSlice.ts ← session state ├── selectors/ │ ├── appointments.ts ← colocated with domain │ └── conflicts.ts ├── middleware/ │ └── transactionMiddleware.ts └── types/ └── index.ts Rules: 1. Max 3–4 domain-driven slices 2. Each slice = single responsibility 3. Selectors read from ONE slice only 4. All async actions use transaction boundaries 5. Create a new slice only after 3+ confirmed use cases store/ ├── slices/ │ ├── entitiesSlice.ts ← all data entities │ ├── uiSlice.ts ← UI-only state │ └── sessionSlice.ts ← session state ├── selectors/ │ ├── appointments.ts ← colocated with domain │ └── conflicts.ts ├── middleware/ │ └── transactionMiddleware.ts └── types/ └── index.ts Rules: 1. Max 3–4 domain-driven slices 2. Each slice = single responsibility 3. Selectors read from ONE slice only 4. All async actions use transaction boundaries 5. Create a new slice only after 3+ confirmed use cases Conclusion Architecture Decision Degradation isn't random. In nearly every project I've seen, it follows the same trajectory: clean start, complexity creep, race conditions, velocity collapse. No Redux architecture stays clean on its own. Slice proliferation is the first signal. Race conditions are the second. By the time 40% of sprint time goes to state bugs, ADD has already won. None of the three principles we applied are revolutionary. The hard part was recognizing ADD early — before velocity collapsed and we'd already burned three sprints on state bugs. Consolidated domain slices, explicit transaction boundaries, and single-slice selector ownership turned a 7-point sprint into an 11-point sprint and cut state-related bugs by more than half. We lost 9 months to gradual degradation, then spent 3 months refactoring. Total: a year of pain. But velocity came back, and so did confidence in the codebase. Solve race conditions properly, don't debounce them away. Your architecture will still degrade — but now you'll see it coming. Solve race conditions properly, don't debounce them away. Your architecture will still degrade — but now you'll see it coming.