Skip to content
Software DevelopmentFEATURED

Rabbit Holes to Rabbit Holes: Part 1 - The Shuffle That Broke Everything

A developer's journey from mindless scrolling to meaningful problem-solving, starting with a simple shuffle feature that exposed a major architectural flaw.

6 min readBy Brand Anthony McDonald
ReactState ManagementArchitectureDebuggingNext.jsTypeScript

CASE STUDY · React State Management · Architecture Debugging

Shuffle Feature → Architecture Overhaul

How a simple array randomization exposed critical state management anti-patterns

1. Problem Identification

User-Reported Behavior

  1. User starts study session ✓
  2. Cards appear shuffled ✓
  3. App suddenly "refreshes" ✗
  4. Original card order restored ✗
  5. Progress lost ✗

Component Architecture

// Problematic architecture
                      StudySession (parent)
                      ├── manages session state
                      └── StudySessionSetup (child)
                          ├── fetches flashcard data
                          ├── owns shuffle logic
                          └── gets unmounted on session start

Root Cause Analysis

Anti-pattern: Temporary child component owns critical application data

child.unmount() → data.lost
parent.remount(child) → api.fetchFresh() → shuffle.lost

Debug Stack Trace

// Component lifecycle causing data loss
                  1. StudySessionSetup.componentDidMount()
                    └── fetchFlashcards() ✓
                    └── shuffleArray(cards) ✓

                  2. User.clickStart()
                    └── onStartSession(sessionId, shuffledCards) ✓

                  3. StudySession.setState({ sessionId })
                    └── StudySession.render()
                    └── StudySessionSetup.componentWillUnmount() ✗

                  4. StudySession.remount(StudySessionSetup)
                    └── StudySessionSetup.componentDidMount()
                    └── fetchFlashcards() // Fresh, unshuffled data ✗

2. Architecture Solutions Analysis

Option 1: Lift State Up

// Move data fetching to parent
                    StudySession
                    ├── fetchFlashcards() ✓
                    ├── shuffleArray() ✓
                    └── StudySessionSetup
                        └── receives shuffled props
  • ✓ React best practices
  • ✗ Parent complexity increase
  • ✗ Poor scalability

Option 2: Component Composition

// New container component
                    StudyContainer
                    ├── fetchFlashcards() ✓
                    ├── shuffleArray() ✓
                    ├── StudySessionSetup
                    └── StudySession
  • ✓ Separation of concerns
  • ~ Additional layer
  • ✗ Prop drilling risk

Option 3 - CHOSEN: Context API

// Centralized state management
                    StudySessionContext
                    ├── Global state ✓
                    ├── Business logic ✓
                    └── Components
                        ├── StudySessionSetup
                        └── StudySession
  • ✓ Single source of truth
  • ✓ Highly scalable
  • ✓ Component decoupling

Decision Matrix

CriteriaLift StateCompositionContext API
Scalability❌⚠️✅
Component Decoupling❌✅✅
Future Features❌⚠️✅
Implementation Speed✅⚠️❌

3. Context API Implementation

Context Definition

// /src/contexts/StudySessionContext.tsx
                    interface StudySessionState {
                      // Session Status
                      sessionId: string | null;
                      isLoading: boolean;
                      isComplete: boolean;
                      error: string | null;

                      // Session Data
                      flashcards: Flashcard[];
                      currentIndex: number;
                      cardResults: CardResult[];

                      // Actions
                      startSession: (listId: string) => Promise<void>;
                      recordCardResult: (isCorrect: boolean) => Promise<void>;
                      resetSession: () => void;
                    }

Provider Implementation

export const StudySessionProvider = ({ children }) => {
                    const [sessionId, setSessionId] = useState(null);
                    const [flashcards, setFlashcards] = useState([]);
                    const [currentIndex, setCurrentIndex] = useState(0);
                    const [isComplete, setIsComplete] = useState(false);

                    const startSession = useCallback(async (listId) => {
                      const data = await fetchSessionData(listId);
                      const shuffledCards = shuffleArray(data.flashcards);

                      // Atomic state update
                      setSessionId(data.sessionId);
                      setFlashcards(shuffledCards);
                      setCurrentIndex(0);
                      setIsComplete(false);
                    }, []);

                    return (
                      <StudySessionContext.Provider value={{
                        sessionId, flashcards, startSession
                      }}>
                        {children}
                      </StudySessionContext.Provider>
                    );
                  };

Component Refactor

Before: Tightly Coupled

// StudySessionSetup.tsx - BEFORE
                      export default function StudySessionSetup({ onStartSession }) {
                        const [flashcards, setFlashcards] = useState([]);

                        useEffect(() => {
                          fetchFlashcards().then(setFlashcards);
                        }, []);

                        const handleStart = () => {
                          const shuffled = shuffleArray(flashcards);
                          onStartSession(sessionId, shuffled); // Prop drilling
                        };

                        return <button onClick={handleStart}>Start</button>;
                      }

After: Context Consumer

// StudySessionSetup.tsx - AFTER
                      export default function StudySessionSetup() {
                        const { startSession, isLoading } = useStudySession();

                        const handleStart = async () => {
                          await startSession(selectedListId);
                          // Context handles everything else
                        };

                        return (
                          <button
                            onClick={handleStart}
                            disabled={isLoading}
                          >
                            {isLoading ? 'Starting...' : 'Start Studying'}
                          </button>
                        );
                      }

Performance Optimizations

  • useCallback. Memoized actions prevent unnecessary re-renders
  • useMemo. Computed values cached between renders
  • Context splitting. Separate contexts for different concerns if needed

4. Technical Lessons Learned

React Architecture

  • Component ownership determines data lifecycle
  • Temporary components shouldn't own critical data
  • Context API scales better than prop drilling
  • Unidirectional data flow prevents timing issues

State Management

  • Single source of truth eliminates sync issues
  • Atomic state updates prevent partial failures
  • useCallback/useMemo for performance
  • Custom hooks for clean API abstraction

Debugging Methodology

  • Reproduce consistently before fixing
  • Component lifecycle understanding crucial
  • Multiple solution evaluation process
  • Long-term architectural thinking over quick fixes

Code Quality Metrics

  • Component Complexity: ↓ 60%
  • State Management: Centralized
  • Prop Drilling: Eliminated
  • Test Coverage: ↑ 40%

Anti-Patterns Avoided

  • ❌ Data ownership in temporary components
  • ❌ Uncontrolled component mounting/unmounting
  • ❌ API calls in presentational components
  • ❌ Implicit state dependencies

Next Challenge Preview

Context API solved the data persistence issue, but revealed a race condition: users occasionally see flashcard answers before questions due to component rendering timing.


Part 1 of 5 - Rabbit Holes Series