Xstate Architecture Review

XState Architecture Review

Entities

Review the following XState v5 concepts:

• State machines / State charts
• Actor models (fromPromise, fromCallback)
• States / Parallel states / Sub states
• Events / Transitions
• Actions (assign, emit)
• Guards (basic and parameterized)
• Selectors (basic and derived)
• ActorContext (React integration)

XState Conventions

Apply XState conventions:

• Naming conventions (States, Events, Actions, Guards)
• Machine definition pattern (setup + createMachine)
• Actor implementation patterns (fromPromise, fromCallback)
• Guard definition patterns (basic and parameterized)
• Actor communication patterns (emit, actor.on)
• Parallel states
• Global event handling
• Type definition rules and export policy
• State definition order (idle first, error last)
• Test strategy

React Binding Conventions

Apply React binding conventions:

• Directory structure and file naming
• ActorContext pattern and Provider placement
• Selector pattern (basic and derived)
• Facade hook pattern
• Component 1:1 lifecycle pattern (useActor + provide)
• Event subscription pattern

States

Implementation under review

Analyze the provided XState implementation against conventions.

Review feedback

Provide structured feedback:

1. Summary: Brief overview of the implementation quality
2. Violations: List convention violations with severity (error/warning/info)
   • Reference the specific convention rule
   • Show the problematic code
   • Provide corrected example
3. Recommendations: Suggestions for improvement beyond conventions
4. Positive aspects: Highlight well-implemented patterns

Actions

Provide feedback based on official XState references. Before making a framework-bound claim, read the official source map and cite the specific documentation section or source-code location that supports it. Treat the bundled convention files as team policy unless the source map identifies a corresponding official XState requirement.

Evaluate against:

• XState conventions for general XState patterns
• React binding conventions for React integration patterns

Constraints

• Always cite official XState documentation and source code as evidence for feedback
• Never evaluate anything unrelated to XState architectural design
• Focus on XState v5 patterns (not v4)
• Reference the appropriate convention file based on review scope