Solution Architecture Document — HandyHome AI

Project: HandyHome AI Author: Jarrod E. Brown Platform: IBM watsonx Orchestrate (agentic, multi-agent) Status: In development Repository: github.com/jarrodebrown/handyhome-ai (private)

1. Overview

HandyHome AI is a no-code, multi-agent conversational assistant that turns a vague home problem description into a verified diagnosis, severity assessment, step-by-step repair guidance, materials list with grounded cost estimates, safety alerts, and a shortlist of nearby service providers — returned as one structured answer in under two minutes. The entire system runs on IBM watsonx Orchestrate.

The Orchestrator implements the Knowledge Synthesizer archetype validated in ServiceBay AI: the information already exists across repair manuals, building codes, cost references, and safety databases, but the value is in synthesis, not retrieval. Five specialist agents each retrieve a slice of the answer and the Orchestrator composes them into a single response.

2. Problem & Context

When something breaks at home, the non-expert owner faces the same fragmented experience a driver does with a warning light: conflicting advice from forums, uncertain urgency, no way to tell whether a dripping faucet is a weekend project or a sign of a failing supply line, and no single place that connects diagnosis to action. A homeowner with a tripped breaker searches three forums, watches two YouTube videos, and still isn't sure whether to reset it or call an electrician. The cost of a stalled project — idle labor for a contractor, an unusable kitchen for a homeowner, a burst pipe for someone who waited too long — far exceeds the cost of a fast, trustworthy answer.

Unlike automotive diagnostics, homes have no universal identifier. There is no VIN, no OBD-II port, no standardized set of warning lights. A car announces its problems through a finite set of dash indicators mapped to known fault codes; a home announces its problems through symptoms that span six broad system categories with dozens of sub-systems and hundreds of failure modes. This absence of structured input is the core design challenge HandyHome AI must solve.

3. Goals & Requirements

Functional

• Accept a plain-language description of a home problem along with a ZIP code.
• Classify the problem into a structured home systems taxonomy (system, sub-system, failure mode).
• Classify severity into three tiers (EMERGENCY / URGENT / ROUTINE) based on safety implications.
• Return a structured answer: diagnosis, severity, repair steps (when DIY-appropriate), materials list, cost estimate, provider list, and safety alerts.
• Cite sources for every factual claim; never fabricate cost figures or part numbers.
• Flag EMERGENCY conditions (gas leaks, exposed wiring, active flooding) with an immediate professional-referral recommendation regardless of other agent output.

Non-functional

• Reuse the ServiceBay AI multi-agent pattern and WISER prompt structure to minimize new build effort.
• Source-grounded answers; zero hallucinated or fabricated numbers.
• Sub-two-minute end-to-end response time, matching ServiceBay AI's baseline.
• Extensible to a commerce/delivery layer sharing ~70% of platform with ServiceBay's auto-parts delivery.

4. Decision Rationale

Why reuse ServiceBay's architecture? The orchestrator-plus-specialists pattern was validated in ServiceBay AI with 16 of 17 end-to-end tests passing. The architectural decisions — the Knowledge Synthesizer archetype, WISER prompting, domain-specific agent isolation, graceful degradation, and the three-path RAG fallback — are domain-agnostic patterns that transfer directly to home improvement. Reusing the proven architecture reduces engineering risk and lets the project focus its effort on domain-specific knowledge rather than infrastructure.

Why a separate project instead of a mode within ServiceBay? The domain knowledge is fundamentally different. Vehicles and homes share no diagnostic overlap: a check-engine light and a gas leak require entirely different severity models, knowledge bases, external APIs, and professional referral paths. The severity classifications diverge (CRITICAL/CAUTION/INFORMATIONAL for vehicles versus EMERGENCY/URGENT/ROUTINE for homes, reflecting the life-safety dimension of home emergencies). The regulatory interfaces differ (NHTSA for vehicles versus CPSC and ICC for homes). The retail partner ecosystems don't overlap (AutoZone/O'Reilly/NAPA versus Ace/Grainger/True Value/Fastenal). What the two projects share is infrastructure, not domain logic — and that shared infrastructure is cleanly separated into the delivery vertical platform.

Why the home systems taxonomy? Unlike automotive diagnostics, where a VIN maps to a make/model/year and known warning lights map to OBD-II codes, homes have no universal identifier and no standardized fault-code system. The taxonomy provides the structured routing layer that OBD-II provides for vehicles — a classification hierarchy from system to sub-system to failure mode that the Orchestrator uses for intent classification, severity assessment, and agent routing. Without it, every user query would require unstructured interpretation.

Why watsonx Orchestrate? The same rationale as ServiceBay AI applies: Orchestrate's no-code agent builder with native tool integration, built-in knowledge resources for RAG, and managed runtime eliminates infrastructure overhead. The choice to stay on the same platform as ServiceBay also enables shared operational knowledge, consistent export formats, and a clear path to the shared delivery vertical.

Why WISER prompting? Agent behavior in Orchestrate is defined entirely through natural-language instructions. The WISER framework (Who, Instructions, Sub-tasks, Examples, Review) provides the same repeatable, auditable structure validated in ServiceBay AI. Each HandyHome agent's prompt follows the identical five-section template, making cross-domain knowledge transfer straightforward for a single builder maintaining both projects.

5. Architecture Overview

6. Components

Delivery Vertical Components. The Home Improvement Delivery spin-off extends HandyHome's diagnostic intelligence into commerce — "we told you what you need, now we'll bring it to you." It shares roughly 70% of its platform engine with the Auto Parts Delivery spin-off from ServiceBay AI. The shared components are:

7. RAG Implementation

See also: Data Flow Diagram showing the RAG retrieval path within the query flow.

HandyHome AI uses Retrieval-Augmented Generation across three knowledge resources, all implemented as watsonx Orchestrate knowledge bases with document-backed retrieval.

Knowledge Source 1 — Home Repair Manuals. A curated PDF corpus covering the six core home system categories (plumbing, electrical, HVAC, structural/framing, appliance, and exterior/roofing). Sources include manufacturer installation guides and code-compliant repair references (e.g., Black & Decker Complete Guide series, manufacturer PDF manuals for common fixtures and appliances). The knowledge agent retrieves against this corpus when the user describes a symptom, grounding its diagnostic explanation and repair steps in documented procedures rather than model-generated content. MVP scope: 3 systems (plumbing, electrical, HVAC) with approximately 15–20 split PDFs.

Knowledge Source 2 — Materials & Cost Reference. A curated CSV covering common repair types across material categories, with regional cost multipliers. Columns: repair_type, material_category, system_type, brand, sku_pattern, cost_range_low, cost_range_high, unit, region_multiplier. The cost agent retrieves matching rows to produce grounded cost estimates. Hard rules in the agent's WISER instructions prohibit returning any dollar figure not sourced from this reference — the primary anti-hallucination control. MVP scope: approximately 200 rows covering top repairs in the three MVP systems.

Knowledge Source 3 — Home Systems Taxonomy. A structured reference (CSV or JSON) defining the classification hierarchy for home systems, sub-systems, common failure modes, and severity mappings. The Orchestrator uses this resource for intent classification and routing — mapping a user's plain-language problem description to a specific system category, sub-system, and failure mode. The taxonomy defines the following hierarchy:

• Plumbing: supply lines, drain/waste/vent, fixtures (faucets, toilets, water heaters), water filtration
• Electrical: service panel, branch circuits, outlets/switches, lighting, grounding/bonding
• HVAC: forced air (furnace, AC, heat pump), ductwork, thermostats, ventilation/exhaust
• Structural/Framing: foundation, load-bearing walls, subfloor, joists/rafters, insulation
• Appliance: kitchen (dishwasher, disposal, range), laundry (washer, dryer), water heater
• Exterior/Roofing: roofing materials, gutters/downspouts, siding, windows/doors, decking

Each failure mode carries a severity classification: EMERGENCY (active leak, gas smell, exposed wiring), URGENT (no hot water, failed HVAC in extreme temps), or ROUTINE (dripping faucet, sticky door). The taxonomy is the structural equivalent of the OBD-II code system — it provides the routing layer that homes lack natively.

Chunking and retrieval. Orchestrate handles document chunking and vector embedding internally; the builder uploads source documents and the platform manages the retrieval pipeline. Queries are routed to the appropriate knowledge resource by the Orchestrator based on intent classification — diagnostic queries go to the manuals, cost queries go to the reference CSV, and classification queries reference the taxonomy.

Three-path fallback (knowledge agent). The knowledge agent implements three response paths based on retrieval quality: (1) a manual hit, where retrieved content directly addresses the symptom; (2) irrelevant retrieval, where the retrieved chunks don't match the query and the agent acknowledges the gap rather than forcing an answer; and (3) unsupported system, where the home system category isn't covered in the MVP knowledge base and the agent returns a documented limitation message with a recommendation to consult a professional.

8. Data Flow

1. User input. The homeowner submits a natural-language problem description along with a ZIP code in the Orchestrate chat interface. Optional context includes property details (age, type) that can improve diagnostic accuracy.
2. Taxonomy classification. The Orchestrator maps the problem description to the home systems taxonomy — identifying the system category (e.g., plumbing), sub-system (e.g., fixtures), and failure mode (e.g., leaking faucet) using the Home Systems Taxonomy knowledge resource.
3. Severity classification. Based on the classified failure mode and its safety implications, the Orchestrator assigns a severity tier: EMERGENCY (stop, evacuate, or shut off utility — call a professional immediately), URGENT (address within 24–48 hours to prevent escalation), or ROUTINE (schedule at convenience).
4. Agent routing. The Orchestrator fans out to the relevant specialist agents. A typical home-problem query activates all four specialists. An EMERGENCY classification always triggers the safety agent and always includes a professional-referral recommendation regardless of other agent output.
5. Knowledge retrieval (RAG). The knowledge agent queries the Home Repair Manuals knowledge resource with the symptom and system context. Retrieved chunks are evaluated against the three-path fallback logic. The cost agent independently queries the Materials & Cost Reference with the identified repair type and system specifics.
6. External API calls. The provider agent geocodes the ZIP via Nominatim and queries OSM Overpass for home-service POIs (plumber, electrician, HVAC technician, general contractor) within a 10-mile radius, expanding to 25 miles if fewer than three results. The safety agent checks the CPSC Recalls API for applicable product safety recalls.
7. Response synthesis. The Orchestrator collects all agent responses and composes a single structured answer: diagnosis with system classification, severity assessment, repair steps (when DIY-appropriate and severity permits), materials list with grounded cost estimates, nearby providers filtered by relevant trade, and applicable safety alerts. Every factual claim includes its source attribution. EMERGENCY-severity responses always lead with a professional-referral recommendation.

9. Data Model

The system operates on transient conversational state rather than a persistent database. Key data entities flow through the pipeline as follows:

User query context — problem description in natural language, ZIP code, and optional property details (age, type, number of units). This context is parsed by the Orchestrator and passed to each specialist agent as structured input.

Home system context — the classified system category, sub-system, and failure mode derived from the taxonomy. This structured classification replaces the vehicle descriptor (year/make/model) used in ServiceBay AI and serves the same routing function: it tells each specialist agent what domain it's operating in.

Agent context frames — each specialist agent receives its slice of the query context and returns a structured response. The knowledge agent returns step-by-step repair instructions with source attribution; the cost agent returns a materials list with cost ranges, units, and regional adjustments; the provider agent returns a list of providers with name, trade, address, distance, and coordinates; the safety agent returns applicable CPSC recalls and safety alerts.

Knowledge base structure — three Orchestrate knowledge resources. The Home Repair Manuals resource stores chunked PDF content with metadata linking chunks to source documents (system category, repair type). The Materials & Cost Reference stores CSV rows keyed by repair type, material category, and system type, with regional cost multipliers. The Home Systems Taxonomy stores the classification hierarchy used for routing.

Synthesized response — the Orchestrator's output: a structured answer with severity classification, system identification, repair guidance (or professional referral), materials and costs, provider list, safety alerts, and source citations per claim.

10. External Interfaces

OpenAPI-defined tools (6 total, 4 in MVP):

RAG knowledge resources (3 total):

11. Error Handling & Resilience

CPSC API unavailability. The safety agent treats CPSC as a best-effort data source. If the Recalls API returns an error or times out, the agent returns a partial result noting that recall status could not be verified and recommends the homeowner check CPSC.gov directly. The Orchestrator still synthesizes a response — a missing safety check does not block the diagnostic, cost, or provider sections.

OSM/Nominatim unavailability. If the geocoder or Overpass API is unreachable, the provider agent returns an empty provider list with an explanation. The Orchestrator omits the provider section and includes a fallback recommendation to search for nearby home-service professionals manually.

RAG retrieval failures. The knowledge agent's three-path fallback handles retrieval-quality issues at the application level. If the Orchestrate knowledge resource itself is unreachable (platform-level failure), the Orchestrator proceeds without the diagnostic section and notes the limitation.

Cost fabrication prevention. The cost agent's hard rules are the system's primary trust control. If no matching row exists in the Materials & Cost Reference, the agent returns "cost estimate unavailable for this repair type" rather than generating a figure. This is a deliberate design choice — a missing estimate is better than a fabricated one.

Safety-critical escalation. When the Orchestrator classifies a problem as EMERGENCY severity (gas leak, exposed wiring, active flooding), the response always recommends professional intervention regardless of individual agent availability. Even if every specialist agent fails, an EMERGENCY classification produces a response directing the homeowner to call the appropriate emergency service.

Unsupported system category. When a problem falls outside the MVP's three covered systems (structural/framing, appliance, exterior/roofing), the knowledge agent returns a documented limitation message acknowledging the gap and recommending professional consultation. The cost and provider agents may still return useful results if the repair type and trade are identifiable from the taxonomy classification alone.

Graceful degradation pattern. The system is designed so that any single agent failure produces a partial but honest response rather than a complete failure. The Orchestrator's synthesis step handles missing sections by acknowledging what couldn't be retrieved and suggesting the homeowner pursue that information through other channels. This pattern is inherited directly from ServiceBay AI and validated across both domains.

12. Non-Functional Requirements (Measured)

13. Tech Stack

14. Security & Compliance

All external calls are read-only against public government and open-data APIs; no PII is persisted. Cost figures are constrained to the curated reference KB, with explicit hard rules preventing fabricated dollar amounts — the primary trust and safety control of the system. The Orchestrate environment manages authentication and access control for the agent runtime. No user data leaves the Orchestrate session boundary.

The phased retail partner integrations (Ace Hardware, Grainger, True Value, Fastenal) will introduce standard considerations for partner inventory access, API key management, and rate limiting. The delivery vertical introduces additional considerations for order data handling and last-mile fulfillment to be formalized as that phase matures. CPSC data is public and carries no access restrictions; ICC data access requires a commercial license and will be scoped during Phase 2 planning.

15. Deployment & Operations

The entire system runs inside watsonx Orchestrate; agents, tools, and knowledge bases are exported as YAML/ZIP definitions for reproducible import. The export-and-import pattern validated in ServiceBay AI applies identically — agent definitions, tool specifications, and knowledge resource configurations are version-controlled and portable.

A companion MCP Server bridge is planned but not yet implemented. ServiceBay AI's MCP Server (separate repo: jarrodebrown/MCP-Server) serves as the reference implementation. When built, HandyHome's MCP Server will expose the same pattern — agent listing, conversational access, and direct-API tools for provider discovery and safety lookups — enabling cross-platform access to HandyHome AI's capabilities from within Claude Desktop.

16. Cross-Project Context

ServiceBay AI (shared architecture pattern). HandyHome AI reuses the orchestrator-plus-specialists multi-agent pattern validated in ServiceBay AI. The architectural decisions — the Knowledge Synthesizer archetype, WISER prompting, domain-specific agent isolation, three-path RAG fallback, and graceful degradation — transfer directly across domains. What's shared is infrastructure and pattern; what's unique is domain knowledge.

Shared vs. unique breakdown:

MCP Server (integration bridge). ServiceBay AI's MCP Server bridges watsonx Orchestrate and Claude Desktop via the Model Context Protocol. HandyHome AI will follow the same pattern — the MCP Server architecture is domain-agnostic, and the bridge implementation is planned to expose HandyHome's agents through the same tool interface.

17. Risks, Assumptions & Limitations

• Domain knowledge breadth must expand to cover the long tail of home systems. The MVP's three-system scope (plumbing, electrical, HVAC) leaves structural, appliance, and exterior/roofing problems handled by the fallback path rather than grounded retrieval.
• The home systems taxonomy assumes problems can be cleanly classified into a single system category. In practice, some issues span multiple systems (e.g., a water heater problem touches both plumbing and appliance categories). The taxonomy's failure-mode mappings must handle these overlaps deliberately.
• Cost accuracy depends on the curated reference; the regional cost multiplier approach is an approximation. The system will not fabricate a cost figure — it returns "unavailable" rather than guessing.
• Provider discovery quality depends on OpenStreetMap coverage in the homeowner's area. Rural areas with sparse OSM data may return few or no results even at the expanded 25-mile radius. Home-service providers are less consistently tagged in OSM than auto-repair shops.
• The delivery vertical depends on retail partner integrations and gig-driver supply, both phased. Partner API access, inventory data quality, and delivery logistics are external dependencies.
• Provider quality and verification is a trust surface to be designed deliberately. Unlike auto shops with review aggregators, home-service provider reputation data is more fragmented.
• Model behavior is governed by WISER prompts, not code. Prompt drift across model updates is a maintenance risk — the test suite (to be built mirroring ServiceBay AI's 17-scenario approach) is the primary regression guard.
• Safety-critical recommendations (EMERGENCY severity) carry liability implications. The system always recommends professional intervention for EMERGENCY classifications, but the accuracy of the severity classification itself is a critical quality gate.
• Building code requirements vary by jurisdiction. The phased ICC integration and permit-lookup tools will provide partial coverage; local code variations remain a limitation.

18. Roadmap

Phase 1 — DIY Homeowner (current). Diagnostic assistant targeting homeowners, handymen, and property managers who encounter a home problem. MVP delivers severity classification, diagnosis, step-by-step repair guidance (when DIY-appropriate), materials identification, cost estimation, provider discovery, and safety alerts for three home system categories (plumbing, electrical, HVAC). The core value proposition: turn a confusing home problem into a structured, source-cited action plan in under two minutes.

Phase 2 — Full System Coverage + Delivery. Expand knowledge bases and RAG coverage to all six home system categories (adding structural/framing, appliance, and exterior/roofing). Launch store-partner integrations (Ace Hardware, Grainger, True Value, Fastenal) and on-demand delivery for materials identified during diagnosis. Introduce building code awareness via ICC API integration and permit-lookup tools for jurisdiction-specific guidance.

Phase 3 — Premium & Commercial. Premium subscription tier for commercial property management: multi-unit diagnostics, preventive maintenance scheduling, and compliance tracking. Tractor Supply partnership for the rural and agricultural property segment. Expanded partner ecosystem and professional-tier features for licensed contractors.

Home Improvement Delivery (spin-off). An on-demand last-mile delivery vertical for home-improvement materials, sharing ~70% of its platform engine with ServiceBay AI's Auto Parts Delivery. Partners include Ace Hardware, Grainger, True Value, and Fastenal (phased). The integration point is natural: HandyHome AI identifies what's needed, the delivery vertical brings it to you.

Diagrams: Context Diagram · Component Diagram · Data Flow Diagram