Implement state machine with stepper visualization for API call coordination (YNAB & SettleUp)

[SThor]

Currently, the steps for the API calls to both YNAB and SettleUp run concurrently and are not well coordinated. This lack of a unified approach leads to the messages overwriting each other, which is especially problematic in the event of an error.

Proposal

We should implement a proper state machine to manage and sequence the API calls for both YNAB and SettleUp using XState. This will allow us to:

• Orchestrate requests, sequencing steps and managing parallel work where safe.
• Maintain a clear, global status and preserve user-facing messages across steps.
• Cleanly handle and report errors without losing context, making debugging and UX much better.
• Improve overall reliability for these integrations.

Developer notes

• Plan to use XState for explicit state machine logic. It’s a widely-adopted, robust solution for state orchestration in React.
• For user visualization: use a custom stepper component styled with Tailwind CSS (already used in the app), optionally with Framer Motion for simple animations. No extra UI libraries are needed.
  • The user should see a simple linear visualization showing progress through the key integration steps (e.g., Prepare, Sync YNAB, Sync SettleUp, Success/Error), with immediate feedback if a step fails. Tailwind and Framer Motion can be used to style and animate transitions.
  • Keep the visualization minimal and readable.
• Avoid introducing large UI frameworks; component should be lightweight and reuse existing stack.

Why?

• Current method causes confusing UI/UX as error or success messages often wipe each other due to overlapping calls.
• A state machine ensures a single source of truth about what operations are in progress and what messages should be shown.
• Stepper visualization helps users track “where” they are in the sync process.

Acceptance Criteria

• API steps are coordinated via an XState state machine.
• User messages and errors are not overwritten during concurrent work.
• End-user sees a simple, live, step-wise visualization of the workflow using a custom Tailwind+Framer component (not a new UI library).
• State transitions are clear, logged, and debuggable.

[SThor]

closed by #90