Fixing The Undo-Move Interaction Bug An Architectural Solution

Aug 2, 2025 by JurnalWarga.com 63 views

Architecture Fix Undo-Move Interaction Bug - API Should Return Complete Game State

Hey guys! We've got a pretty crucial issue on our hands regarding the undo functionality in our game. After digging deep, it turns out it's more than just a simple bug; it’s an architectural problem that needs a solid fix. Let's break it down and see how we're going to tackle it!

Bug Report Moves Don't Execute After Undo Operation

The main issue? After you hit that undo button, the game board just… stops working. Players can't make any moves, even though the game state correctly transitions to the 'rolled' state. Imagine the frustration! This basically makes the undo feature completely unusable, which isn't cool. We need to ensure our game provides a seamless user experience, and this bug is a major roadblock.

Problem Description

So, here’s the deal. After using the undo functionality, the game board becomes non-interactive. Players can't make moves, even when the game correctly transitions to the 'rolled' state. This is a major buzzkill for the user experience, making the undo feature a no-go. This issue affects the user experience and makes the undo feature unusable, which is a critical problem we need to address promptly.

Root Cause Analysis

This isn’t just a simple coding oopsie; it's an architectural problem lurking beneath the surface. The current game design awkwardly juggles assembling the complete game state on the client-side, which is causing all sorts of headaches. Let's dive into why this is happening.

Current Broken Flow

Here's the messy sequence of events that leads to the bug:

User clicks undo → API processes undo → API returns partial state → Client orchestrates fetchPossibleMoves → Race conditions and failures

Basically, when a user clicks undo, the API only returns a piece of the game state. Then, the client (that's your web browser or app) has to scramble to fetch the rest, specifically the possible moves. This is where things get dicey, leading to race conditions and failures. It's like trying to bake a cake when the recipe is split between different cookbooks – a recipe for disaster!

Technical Root Causes

Let's break down the core reasons why this flow is broken:

Dual state storage: Possible moves stored in different places depending on game state. This means the client has to hunt for the right info in multiple locations – super inefficient!
Client orchestration: The client is responsible for ensuring the state is complete. This is a big no-no. The server should be the single source of truth, not the client piecing things together.
Race conditions: Multiple async operations with timing dependencies. When the client is juggling multiple tasks at once (like fetching different parts of the state), things can get out of sync, leading to unpredictable results.
Inconsistent API responses: Some endpoints return a complete state, while others don't. This inconsistency makes the client's job way harder and introduces more chances for errors.

Evidence

We're not just guessing here; we've got evidence to back this up:

E2E tests consistently show possibleMovesCount=0 after undo. This means the client isn't getting the possible moves after an undo.
Game state correctly shows stateKind=rolled but the board remains non-interactive. The game knows it's the player's turn, but they can't do anything.
Manual testing confirms a 100% reproduction rate. We can reliably make this bug happen, which means it's a serious issue.
Client logs show fetchPossibleMoves being called but not populating moves. The client is trying to get the moves, but something is failing along the way.

Solution Architecture

Alright, enough about the problem – let's talk solutions! We need a streamlined, reliable process for handling undo. The key is making the API the single source of truth for the entire game state.

Correct Flow

Here's the clean, simple flow we're aiming for:

User clicks undo → API processes undo → API returns complete state → Client displays it

Ah, much better! The API does all the heavy lifting, and the client just displays the result. This eliminates the race conditions and ensures the client always has a consistent view of the game.

Key Principles

To make this work, we're sticking to these core principles:

Single source of truth: The API always returns a complete, consistent state. No more piecing things together on the client-side.
Server responsibility: The API ensures the state is complete before responding. This shifts the complexity from the client to the server, where it belongs.
Client simplicity: The client only displays what the API provides. No more complex logic or orchestration.
No orchestration: No client-side state assembly required. This dramatically simplifies the client code and reduces the chance of bugs.

Implementation Plan

So, how are we going to make this happen? We've broken the solution down into phases to tackle it efficiently.

Phase 1 API Layer Fixes (High Priority)

First up, we need to fix the API to return the complete game state after an undo. This is the most critical step.

[x] Update undo endpoint to call Game.getPossibleMoves() and include the result in the response. (DONE! High five!)
[ ] Audit other endpoints that can result in the 'rolled' state. We need to make sure all endpoints return the complete state when they should.
[ ] Ensure a consistent API response format. Consistency is key for making the client's job easier.

Phase 2 Client Layer Simplification (High Priority)

Now that the API is doing its job, we can simplify the client-side code.

[ ] Remove complex fetchPossibleMoves orchestration from undo handlers. We don't need this anymore!
[ ] Update the game state reducer to handle complete API responses. The reducer is responsible for updating the game state in the client, so it needs to know how to handle the new API responses.
[ ] Simplify WebSocket message handling. WebSockets are used for real-time communication, so we need to make sure they're also handling the complete state correctly.

Phase 3 Testing and Validation (High Priority)

Testing is crucial to make sure our fix works and doesn't introduce new issues.

[ ] Update E2E tests to verify the single-call complete state. End-to-end tests simulate real user interactions, so they're great for catching integration issues.
[ ] Add API integration tests for complete state responses. These tests specifically check that the API is returning the correct data.
[ ] Add regression tests to prevent future architectural drift. Regression tests make sure that existing functionality doesn't break when we make changes.

Phase 4 Long-term Architectural Cleanup (Medium Priority)

This phase is about making the codebase cleaner and more maintainable in the long run.

[ ] Consolidate the dual possible moves storage system. Remember how we said the possible moves are stored in different places? We need to fix that.
[ ] Standardize all API responses to return complete state. This is the ultimate goal – consistency across the board.
[ ] Performance optimizations. Once everything is working correctly, we can look for ways to make it even faster.

Technical Details

For the code-savvy folks, here are the files we're touching:

/packages/api/src/routes/games.ts (undo endpoint) - ✅ COMPLETED (Woohoo!)
/packages/client/src/hooks/useWebSocketGameActions.ts (undo handling)
/packages/client/src/Contexts/Game/gameReducer.ts (state management)
/packages/client/e2e/undo-move-interaction-test.spec.ts (test updates)

Current Status

✅ API fix implemented: The undo endpoint now returns the complete state, including possible moves. We're on our way!
⏳ Client fix needed: We still need to remove the unnecessary fetchPossibleMoves orchestration on the client-side.
⏳ Testing needed: We need to verify that the complete fix works end-to-end.

Benefits of This Approach

This fix isn't just about squashing a bug; it's about making our system more robust and maintainable.

Immediate Benefits

✅ Fixes the undo-move interaction bug. Hallelujah!
✅ Eliminates race conditions and timing dependencies. No more unpredictable behavior!
✅ Simplifies client code and reduces complexity. Less code = fewer bugs.

Long-term Benefits

✅ Prevents similar architectural issues in the future. We're building a solid foundation.
✅ Makes the codebase more maintainable and predictable. Easier to work with and less prone to errors.
✅ Follows proper separation of concerns (server = authority, client = presentation). This is good software design.
✅ Improves performance by reducing unnecessary API calls. Faster game, happier players!

Acceptance Criteria

How do we know we've succeeded? Here's our checklist:

[ ] Users can make moves immediately after using undo (no delay or failures). Smooth gameplay is the goal.
[ ] Undo operation requires only a single API call (no client orchestration). The API does the work, the client displays it.
[ ] E2E tests pass consistently (no race conditions). Confidence in our fix.
[ ] Client code is simplified (reduced complexity). Cleaner code is better code.
[ ] API responses are complete and consistent. The API is the single source of truth.

Priority High

This is a high-priority issue, guys. It's a critical user experience bug that makes a core feature unusable. Plus, the architectural fix prevents similar issues down the road and improves the overall reliability of our system. Let's get this done!

🤖 Generated with Claude Code

Co-Authored-By Claude [email protected]