Project 6: Guided Selling Assistant

Build a decision-driven UI assistant that turns seller intent into valid, policy-compliant configurations.

Quick Reference

Attribute Value
Difficulty Level 2 (Intermediate)
Time Estimate 2 weeks
Main Programming Language TypeScript/React (Alternatives: Vue, Streamlit)
Coolness Level Level 3
Business Potential 3. Service & Support Model
Prerequisites Projects 1-2, UI state management
Key Topics Decision trees, UX explainability, step flow resilience

1. Learning Objectives

  1. Design guided flows that reduce seller cognitive load.
  2. Keep UI state aligned with backend rule outcomes.
  3. Improve completion rates through question ordering and rationale.
  4. Instrument flow analytics for continuous optimization.

2. All Theory Needed (Per-Concept Breakdown)

Concept A: Guided Decisions with Constraint Feedback

Fundamentals Guided selling succeeds when each question reduces uncertainty while staying tied to strict backend validation.

Deep Dive into the concept Use a state machine for flow steps. Persist canonical answer state. Recompute recommendations from canonical state after any backtrack. Show clear “why” text for recommendations.

How this fit on projects Primary here, supports P01-product-catalog-foundation.md and P10-visual-rule-builder.md.

Definitions & key terms

  • Information gain
  • Step state
  • Explainability card

Mental model diagram

User Answer -> State Update -> Rule Re-evaluation -> Recommendation View

How it works

  1. Capture context.
  2. Ask highest-value question.
  3. Validate partial config.
  4. Present recommendation and rationale.

Minimal concrete example

Q: Need SSO?
A: Yes -> system recommends API_ACCESS and shows reason.

Common misconceptions

  • “UI wizard can own logic.” Backend rule system must stay source-of-truth.

Check-your-understanding questions

  1. Why recompute after backtracking?
  2. Why include rationale in recommendation cards?

Check-your-understanding answers

  1. To avoid stale decision artifacts.
  2. To improve seller trust and adoption.

Real-world applications CPQ onboarding, guided procurement forms, insurance quote assistants.

Where you’ll apply it This project and P01-product-catalog-foundation.md.

References

  • UX decision flow literature.
  • Salesforce guided quoting experiences.

Key insights Guided selling is a policy interface problem, not just a UI styling problem.

Summary A robust flow is measurable, explainable, and always rule-aligned.

Homework/Exercises to practice the concept Design a 7-step flow with explicit rationale cards.

Solutions to the homework/exercises Prioritize context-first questions and revalidate on each state change.

3. Project Specification

3.1 What You Will Build

A guided selling web app that asks contextual questions, recommends valid options, and outputs validated configurations.

3.2 Functional Requirements

  1. Multi-step decision flow with saved progress.
  2. Real-time validation feedback from rule API.
  3. Recommendation cards with explanations.
  4. Final configuration summary and export.

3.3 Non-Functional Requirements

  • Performance: step transition < 250ms perceived latency.
  • Reliability: resume from interruptions.
  • Usability: understandable by new sellers.

3.4 Example Usage / Output

Step 1 segment=Enterprise
Step 2 need=Security+Integration
Result recommended: BASE_ENTERPRISE + API_ACCESS + SSO + SECURITY_BUNDLE

3.5 Data Formats / Schemas / Protocols

  • FlowState(sessionId, step, answers, recommendationIds)
  • RecommendationCard(id, reason, impact, action)

3.6 Edge Cases

  • User changes foundational answer late in flow.
  • Session timeout while editing.
  • Rule API temporary unavailability.

3.7 Real World Outcome

3.7.1 How to Run (Copy/Paste)

$ npm run dev
# open http://localhost:3000/guided-selling

3.7.2 Golden Path Demo (Deterministic)

Given same answers and catalog version, recommendation set is identical.

3.7.4 If Web App

  • URL: /guided-selling
  • Key elements: step progress bar, answer pane, recommendation pane, rationale panel
  • States: loading, ready, validation-warning, final-summary

ASCII wireframe:

+--------------------------------------------------+
| Guided Selling (3/7)                             |
|--------------------------------------------------|
| Question: Need compliance package?               |
| [Yes] [No]                                       |
|                                                  |
| Recommendation: Add SECURITY_BUNDLE              |
| Why: Required for selected region + SSO          |
+--------------------------------------------------+

4. Solution Architecture

4.1 High-Level Design

UI State Machine -> Recommendation Service -> Rule API -> Rendered Guidance

4.2 Key Components

| Component | Responsibility | Key Decisions | |———–|—————-|—————| | Flow Controller | Step sequencing | state machine model | | Recommendation Adapter | backend query + normalization | canonical answer payload | | Analytics Tracker | completion/abandonment metrics | step-level events |

4.4 Data Structures (No Full Code)

AnswerState { stepId, answerValue, timestamp }
FlowOutcome { validConfig, recommendations, warnings }

4.4 Algorithm Overview

  1. Capture answer.
  2. Recompute recommendations.
  3. Render rationale.
  4. Persist progress.

5. Implementation Guide

5.1 Development Environment Setup

$ npm install
$ npm run dev

5.2 Project Structure

guided-selling-ui/
  src/
    flow/
    components/
    services/

5.3 The Core Question You’re Answering

“Can complex product configuration feel like a guided conversation instead of a policy minefield?”

5.4 Concepts You Must Understand First

  • Decision tree sequencing
  • Canonical state management
  • Rule explanation UX

5.5 Questions to Guide Your Design

  • Which questions should appear earliest?
  • How do you handle late answer changes?

5.6 Thinking Exercise

Identify top three likely abandonment steps and propose fixes.

5.7 The Interview Questions They’ll Ask

  1. How do you design guided workflows for complex products?
  2. How do you keep UI and backend logic consistent?
  3. What metrics show flow quality?

5.8 Hints in Layers

  • Hint 1: context-first questions.
  • Hint 2: single canonical state object.
  • Hint 3: recompute recommendations after every state change.

5.9 Books That Will Help

| Topic | Book | Chapter | |——-|——|———| | Practical UX engineering | “The Pragmatic Programmer” | Ch. 2 | | Change-safe UI evolution | “Refactoring” | Ch. 11 |

5.10 Implementation Phases

  • Phase 1: flow shell.
  • Phase 2: rule-integrated recommendations.
  • Phase 3: analytics and recovery.

5.11 Key Implementation Decisions

| Decision | Options | Recommendation | Rationale | |———-|———|—————-|———–| | State store | local component, global store | global canonical store | consistency across steps | | Validation timing | end-only, per-step | per-step | early error prevention |

6. Testing Strategy

6.1 Test Categories

| Category | Purpose | Examples | |———-|———|———-| | Unit | step logic | branching checks | | Integration | UI + rule API | recommendation updates | | UX | flow completion | abandonment scenarios |

6.2 Critical Test Cases

  1. Backtracking from step 6 to step 2.
  2. Session resume after refresh.
  3. Rule API temporary failure with graceful fallback.

6.3 Test Data

Fixed answer paths and expected recommendation sets.

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

| Pitfall | Symptom | Solution | |———|———|———-| | stale state | contradictory recommendations | recompute from canonical answers | | poor question order | early abandonment | reorder by information gain |

7.2 Debugging Strategies

  • Replay full session event stream.
  • Compare recommendation payloads between steps.

7.3 Performance Traps

Avoid blocking UI on unnecessary full-page recomputations.

8. Extensions & Challenges

8.1 Beginner Extensions

  • Add tooltip explanations.
  • Add quick-start templates by industry.

8.2 Intermediate Extensions

  • Confidence score for recommendations.
  • Role-specific flow variants.

8.3 Advanced Extensions

  • Adaptive question ordering based on prior outcomes.
  • Guided-selling analytics dashboard with cohort segmentation.

9. Real-World Connections

9.1 Industry Applications

  • Sales onboarding assistants.
  • Self-serve enterprise packaging guidance.

9.3 Interview Relevance

Shows ability to translate policy-heavy logic into usable seller experiences.

10. Resources

10.1 Essential Reading

  • Decision flow UX references.
  • Rule explainability patterns.

10.2 Video Resources

  • Advanced multi-step UX architecture talks.

10.3 Tools & Documentation

  • React docs, state machine docs.

11. Self-Assessment Checklist

  • I can explain every recommendation with a clear rationale.
  • Backtracking does not produce stale outputs.
  • I can measure completion and abandonment by step.

12. Submission / Completion Criteria

Minimum Viable Completion:

  • Multi-step guided flow works with backend validation.

Full Completion:

  • Resume behavior and analytics are implemented.
  • Recommendation rationale is clear and accurate.

Excellence (Going Above & Beyond):

  • Adaptive flow optimization based on usage telemetry.