FiXFLOW

• 

• 

• 

• 

Inspiration

A household repair shouldn't become the homeowner's problem again just because the first appointment failed.

Most repair directories help people find contractors, while basic chatbots provide advice or reminders. But what happens when a repair partner misses an appointment, the household calendar changes, or the repair still isn't fixed?

That inspired me to build FixFlow, a simulated Alexa+-inspired household repair resolution agent built around one promise: “The repair doesn't disappear until it's fixed.”

I wanted to explore how a conversational assistant could do more than answer questions—it could maintain context, track commitments, recover from failures, and keep a repair open until the homeowner confirms the problem is resolved.

What it does

FixFlow manages a household repair as a persistent incident rather than a one-off conversation.

The demo follows a recurring washing machine leak. FixFlow retrieves previous repair history, checks simulated warranty information, compares repair partners against the household's budget and brand-authorization preference, and checks appointment availability against a simulated household calendar.

The homeowner reviews a proposed appointment and explicitly approves it before booking. If the repair partner doesn't show up, FixFlow records the missed visit, preserves the appointment history, and finds alternative appointments.

Even when a visit is marked completed, the case remains open until the homeowner confirms the washing machine is fixed. The incident can then be closed while retaining its history.

Users can interact through text, the interface's simulated assistant experience, or optional browser-based speech recognition. The entire core demonstration works locally without requiring a paid AI API or real external services.

How we built it

FixFlow combines a React, TypeScript, and Vite frontend with a Python FastAPI backend and SQLite persistence.

A critical architectural decision was to implement real Model Context Protocol (MCP) communication over Streamable HTTP. The browser uses the official TypeScript MCP client to initialize a session, discover tools, and invoke repair operations on the Python MCP server mounted in the FastAPI application.

The backend separates repair services, state-machine validation, database operations, and MCP tool definitions. SQLite persists incidents, appointments, approvals, conversation history, and timeline events across page reloads and application restarts.

For agent behavior, FixFlow uses deterministic routing for core actions such as vendor selection, appointment proposals, approvals, booking, missed-visit recovery, and resolution. Fireworks AI is an optional component for unfamiliar conversational questions; it is not allowed to authorize bookings or mutate repair state.

All vendors, estimates, warranty details, calendar conflicts, and visit outcomes in the demo are simulated. FixFlow is a local web prototype inspired by Alexa+, not an official Alexa+ application or a connection to Alexa hardware.

Challenges we ran into

One of the biggest challenges was keeping the conversation, frontend state, MCP tool calls, and persistent backend state synchronized. A successful tool response is not enough if the active appointment ID, repair status, or approval record is not correctly saved and reloaded.

Another challenge was enforcing the difference between proposing an action, receiving approval, executing it, and confirming its outcome. Booking an appointment must not count as completing a repair, and a simulated technician visit must not automatically mean the problem is resolved.

We also had to make failure recovery a first-class workflow. A missed appointment should not erase the previous booking or leave the user starting from scratch. FixFlow must retain the timeline and generate a valid replacement proposal.

Finally, we explored where an LLM adds value and where deterministic logic is more reliable. Core state changes require predictable behavior and explicit authorization, so conversational AI remains separate from the workflow's safety-critical decisions.

Accomplishments that we're proud of

We're proud that FixFlow models the entire repair-resolution journey—not just the initial recommendation or appointment booking.

• Persistent repair memory: Incidents, conversations, approvals, appointments, and timeline events are stored in SQLite.
• Real MCP integration: The browser communicates with an actual MCP server over Streamable HTTP rather than presenting ordinary REST calls as MCP.
• Approval before booking: A proposed appointment is tied to a specific approval record, and the backend validates the approval before booking.
• Recovery after failure: A simulated missed visit preserves the failed appointment and enables the homeowner to choose an alternative.
• Resolution requires confirmation: Completing a simulated visit does not automatically close the repair.
• AI is optional: The core demo runs with deterministic routing and does not require a paid model API.
• Reproducible local demo: A resettable washing-machine scenario makes the workflow repeatable for a hackathon presentation.

Most importantly, FixFlow is designed around an outcome rather than a conversation: helping ensure a repair remains visible and actionable until the homeowner says it is fixed.

What we learned

We learned that building a useful agent is not just about choosing the right model. Persistent state, reliable tool interfaces, explicit approvals, clear feedback, and recovery from failures are equally important.

We also learned that not every decision needs an LLM. Deterministic routing and a validated state machine are better suited to actions that must follow strict rules, while an LLM can improve the experience when users ask unfamiliar conversational questions.

Implementing MCP as a real client-server protocol also reinforced the importance of defining clear tool contracts and validating state changes on the server rather than trusting the frontend.

Above all, we learned to design for the entire lifecycle of a task—including what happens when the original plan fails.

What's next for FixFlow

The next step is to move beyond the simulated environment carefully.

Potential improvements include integrating real calendar and warranty services, connecting verified service-provider availability, adding household accounts and stronger access controls, and making notifications and follow-ups more proactive.

I'd also like to explore richer multimodal interactions, including appliance images, improved voice experiences, and more natural ways to report a problem and review repair progress.

Any real-world integration would need appropriate permissions, verified information, and clear user approval before commitments are made.

The long-term vision is for FixFlow to become a household repair agent that doesn't just tell you what to do next—it remembers what matters, follows through when plans change, and keeps the task alive until the outcome is confirmed.## Inspiration

Built With

• fastapi
• http
• mcp
• python
• react
• sqlite
• tailwind/css
• typescript
• vite