Building XpertConnect — An AI-First DIY Guidance Platform

The Problem Worth Solving

Home repair content on the internet is everywhere. That’s actually the problem 🤣 - simple right?

There’s no structure, no safety awareness, no personalization, and no clear stopping point. A homeowner with a bad capacitor gets the same search results as one with a refrigerant leak — and only one of those is a safe DIY fix. The other requires an EPA-certified tech and should never be attempted without one.

The existing options are broken in different ways:

• YouTube / Google: Unstructured, no safety filtering, no escalation path
• Angi / HomeAdvisor: Skips straight to “hire someone” — no DIY empowerment
• Manufacturer docs: Technical, dry, and written for service techs

XpertConnect sits in the gap between “you can do this yourself” and “please stop, call a pro.”

The Safety System — Four Levels, Hard Guardrails

Safety is the most important design decision in the entire platform. I’m not trying to engineer a liability nightmare 🤣. Every repair task in the system is tagged with a safety level, and those levels have hard behavioral rules.

When a user hits a Level 3 step mid-flow, the platform stops and routes them to the escalation marketplace. No exceptions. The condition engine evaluates this at runtime — not as a UI decision, but as a domain rule enforced in the orchestrator.

This isn’t just “be careful.” It’s a first-class domain concept modeled explicitly in the schema and the guidance flow.

The Domain Model — Core Entities

The heart of XpertConnect is the GuidanceSession. A session tracks one homeowner attempting to resolve one problem — with a full history of steps taken, AI recommendations, conditions evaluated, and the outcome.

Key Entities

GuidanceDomain — The top-level repair category (HVAC, Plumbing, Electrical, etc.)

RepairTask — A specific problem within a domain (e.g., “AC not cooling”). Has a SafetyLevel, an associated GuidanceFlow, and metadata for the AI copilot.

GuidanceFlow + GuidanceStep — The structured troubleshooting tree. Each step has a type (Diagnostic, Fix, Safety, Escalation), an ActionType (Inspect, Test, Replace, Call), a SafetyLevel, and an ordered list of instructions.

GuidanceSession — The runtime record of a homeowner’s troubleshooting attempt. Tracks current step, step history, SessionStatus (Active, Completed, Escalated, Abandoned), and the final outcome.

SessionStepHistory — A JSONB-backed log of every step the user took: step ID, action taken, copilot recommendation used (true/false), timestamp, and any notes.

GuidanceCondition — Named conditions evaluated at runtime to determine flow branching (e.g., "CapacitorFailed", "RefrigerantLeak", "FilterClogged"). Stored with their evaluation logic and the steps that trigger them.

EscalationRequest — Created when a session hits Level 3 or the user explicitly requests expert help. Captures domain, task, session context, and connects to the Xpert marketplace.

The Guidance Orchestrator — The Brain of the Platform

The GuidanceOrchestrator is the Application layer service that drives sessions forward. It sits between the API and the domain, coordinating step navigation, condition evaluation, AI copilot calls, and safety enforcement.

Core Operations

// Start a new guidance session for a repair task
Task<GuidanceSessionDto> StartSessionAsync(Guid repairTaskId, Guid userId);

// Advance to the next step, given the user's action/answer
Task<GuidanceStepDto> AdvanceStepAsync(Guid sessionId, StepActionRequest request);

// Evaluate a named condition against the current session context
Task<ConditionResult> EvaluateConditionAsync(Guid sessionId, string conditionName);

// Route to escalation marketplace
Task<EscalationDto> EscalateSessionAsync(Guid sessionId, EscalationReason reason);

The orchestrator calls the Condition Engine before advancing each step. If a condition resolves to a Level 3 step, AdvanceStepAsync reroutes to EscalateSessionAsync — no UI toggle, no feature flag. It’s a domain rule.

The Condition Engine — Runtime Flow Branching

Each GuidanceStep can have one or more associated GuidanceCondition records. These conditions are evaluated at runtime to determine what the next step should be.

Example: The “AC Not Cooling” Flow Branch

When the user reports the outdoor unit isn’t running:

1. Condition evaluated: OutdoorUnitNotRunning → true
2. Next evaluation: Is the capacitor bulging or burned? → if yes → CapacitorFailed
3. CapacitorFailed = true → Next step: “Replace run capacitor” (Safety Level 1 — DIY with caution)
4. Condition evaluated: Does the unit still not cool after capacitor replacement? → PersistentNoCooling
5. PersistentNoCooling = true → Next step: “Check refrigerant level” (Safety Level 3 — blocked)
6. Safety Level 3 hit → Orchestrator triggers EscalateSessionAsync — session status → Escalated

This is the power of the condition engine. The branching logic lives in the database and domain layer, not scattered across controller actions.

The AI Copilot — IStepGuidanceCopilot

The AI copilot is an Application layer interface with a single, focused responsibility: given a step and the current session context, return a structured recommendation.

public interface IStepGuidanceCopilot
{
    Task<CopilotRecommendation> GetRecommendationAsync(
        GuidanceStep step,
        GuidanceSession session,
        CancellationToken cancellationToken = default
    );
}

What CopilotRecommendation Contains

public record CopilotRecommendation(
    string Summary,           // 1-2 sentence plain-English next action
    string DetailedGuidance,  // Step-by-step detail (markdown)
    bool   ShouldEscalate,    // Override: true if AI detects unsafe scope creep
    string? SafetyWarning,    // Non-null if level ≥ 1
    string? EscalationReason  // Non-null if ShouldEscalate = true
);

The prompt structure enforces structured JSON output using the OpenAI response format API. The system prompt injects the step’s SafetyLevel, ActionType, domain context, and session history summary. The AI can never recommend continuing a Level 3 task — the prompt explicitly prohibits it, and the domain layer enforces it independently anyway.

Defense in depth. The AI doesn’t own safety. The domain does.

The Golden Path — HVAC “AC Not Cooling”

The v1 launch scope is a single domain (HVAC), a single repair task (“AC not cooling”), and the complete end-to-end flow from user report to resolution or escalation. This is the golden path.

Entry: User opens app, selects “HVAC → AC not cooling”

Session starts: GuidanceOrchestrator.StartSessionAsync() → creates GuidanceSession, loads GuidanceFlow for the task, returns Step 1.

Step 1 — Initial Check (Level 0)

“Is the thermostat set to COOL and the temperature set below current room temp?” Actions: Verify, Adjust if needed → advance

Step 2 — Power Check (Level 0)

“Is the circuit breaker for the AC unit tripped?” Condition: BreakerTripped → if true, guide to reset → if repeatedly trips → escalate (Level 3 — electrical)

Step 3 — Airflow Check (Level 0)

“When did you last change the air filter?” Condition: FilterClogged → guide to replace → if no improvement, advance

Step 4 — Outdoor Unit Check (Level 1)

“Is the outdoor condenser unit running?” Condition: OutdoorUnitNotRunning → evaluate capacitor, contactor

Step 5 — Capacitor Check (Level 1)

“Visually inspect the run capacitor. Is it bulging, burned, or leaking?” Condition: CapacitorFailed → guide replacement (DIY-safe with correct capacitor rating)

Step 6 — Post-Fix Verification (Level 0)

“Run the system for 15 minutes. Is cool air coming from the vents?” Condition: PersistentNoCooling → refrigerant check → Level 3 → Escalate

Resolution: SessionStatus → Completed or SessionStatus → Escalated with full context handed to the Xpert marketplace.

The Database — PostgreSQL with JSONB

The schema uses relational tables for structured domain data and JSONB columns for dynamic, variable content — primarily step instructions and session history.

Key design decisions:

• guidance_steps.instructions → JSONB[] — each instruction is { order, text, type }; avoids an instructions junction table for content that never needs to be queried independently
• session_step_histories.step_data → JSONB — full snapshot of the step as it was when the user took it; immutable audit log, not normalized
• guidance_conditions.evaluation_logic → JSONB — stores the condition rule (field path, operator, expected value) for runtime evaluation without hardcoded branching in application code
• repair_tasks.ai_context → JSONB — domain-specific hints injected into the AI copilot prompt (tool requirements, common failure points, seasonal notes)

All tables have created_at / updated_at timestamps and soft-delete support via deleted_at.

The Transactional Outbox

Any domain event that triggers cross-cutting side effects (escalation created, session completed, expert notification) goes through the transactional outbox pattern. The event is written to the outbox_messages table in the same database transaction as the domain change — guaranteed delivery without distributed transaction complexity.

A background OutboxPublisher service polls for unprocessed messages and dispatches them to handlers (email, webhook, future event bus). If the publisher crashes mid-delivery, the message stays Pending and retries on next poll.

No lost domain events. No dual-write bugs.

What’s Next

The design is done. Now it’s time to build.

Milestone 1 (Current): Scaffold the .NET 9 solution, EF Core migrations, seed the HVAC golden path data
Milestone 2: Build the GuidanceOrchestrator + ConditionEngine + API endpoints
Milestone 3: Integrate IStepGuidanceCopilot with OpenAI GPT-4o
Milestone 4: Frontend — React or Astro-based UI for the guided troubleshooting flow
Milestone 5: Xpert marketplace MVP — expert profiles, escalation routing, booking

I’ll be building this in public and posting updates here. If you’re a .NET developer, a DDD nerd, or someone who’s ever rage-Googled “why is our AC not cooling,” follow along.

Read Next: Building & Architecture

• From Employee to Builder: Stop Waiting for Permission — How to transition from employment to building your own projects and products. Includes navigating scams, bad-faith employers, and the reality of indie entrepreneurship.

• Data Pipeline Guide: From Raw Events to Intelligence — Architectural patterns for building reliable ETL pipelines, with real examples from CryptoQT’s behavioral finance system and XpertConnect’s data flow.

• 24 Years in .NET: A Career Journey — From Visual Basic 6 to .NET 9, lessons learned navigating frameworks, architecture decisions, and the evolution of the platform that powers XpertConnect.

• Building CryptoQT: A Behavioral Finance Platform — Domain-driven design and AI integration patterns applied to real-time crypto intelligence, using similar architectural principles as XpertConnect.

• Why I Chose Astro for This Site — Static site generation, content collections, and deployment architecture decisions. Understanding your tech stack is as important as designing your domain model.

Related Reading

• XpertConnect Dev Update #1
• YouWerks uCoin: Monetization Platform
• Data Pipeline Architecture Guide
• DDD & CQRS Patterns — Microsoft Architecture Guide
• OpenAI API Documentation
• Domain-Driven Design — Martin Fowler