Skip to content

Hypothetical Scenario

All handbook examples use one shared scenario. This choice improves learning through realistic, repeated examples. Readers can focus on the design idea without reloading domain context on each page.

Why This Scenario Exists

A stable scenario makes complex topics easier to connect. Dependency direction, abstraction boundaries, testing shape, and architecture patterns all appear in one product. That continuity helps teams compare concepts with less friction. It helps new engineers build a stronger mental model of the full system.

Scenario Summary

The scenario models a car intelligence and marketplace platform. The product follows a modern online car discovery and marketplace model, then adds AI-driven capabilities for deeper personalization. Users create an account, fill a profile, set budget limits, and describe lifestyle constraints. The platform ranks vehicle options and explains each recommendation in plain language. The platform includes a marketplace for new and used cars with deal discovery workflows.

Product Capabilities

  • Reliability views from historical incidents and complaint signals
  • Market value estimates and trend snapshots
  • Common repair profiles and projected maintenance events
  • Cost of ownership models across fuel, insurance, depreciation, and service
  • Lifestyle and feature fit scoring for each profile
  • Marketplace search, filtering, and deal comparison for active listings

AI Capabilities in the Scenario

AI modules in this scenario interpret intent and explain tradeoffs. The matching engine reads profile preferences and generates ranked candidates. A recommendation explainer shows why one model fits better than another. A budget assistant projects ownership impact from mileage, city, and family context. A deal evaluator flags listings with strong value signals or unusual risk patterns.

Example User Journey

  1. A user signs up and completes a buyer profile.
  2. An AI interview agent runs a guided conversation to capture deeper needs, such as daily commute, parking limits, family context, risk tolerance, preferred features, and budget constraints.
  3. The system consolidates explicit profile fields and interview answers into one preference model.
  4. Recommendation services score available listings against that model.
  5. Ownership cost services project monthly and yearly cost impact.
  6. The user reviews ranked matches, explanation cards, and marketplace deals.
  7. The user saves candidates, compares options, and requests contact with sellers.

Core Subdomains Used in Examples

  • Identity and Profile: sign-up, profile state, preferences, and budget constraints
  • Recommendation: match score, fit explanation, ranking logic, and candidate curation
  • Ownership Cost: maintenance, fuel, insurance, and depreciation models
  • Market Intelligence: listing ingestion, market value shifts, and complaint trends
  • Marketplace: listing search, filtering, deal quality checks, and transaction preparation

Example Naming Convention

Use these shared names in code samples and diagrams:

  • CarProfile, BuyerProfile, VehicleListing, CarMatchService
  • OwnershipCostService, MarketValueProvider, RecommendationPolicy
  • CarListingRepository, DealNotifier, MarketplaceSearchUseCase

Rule

New examples and revised examples should use this scenario. Historical notes can stay domain neutral when needed for context fidelity.

Written by: Pedro Guzmán