Skip to content

Dynamic Wizard Engine Architecture

To appraise items ranging from smart jewelry to sports cars, Cashy-Hub decouples the deal creation interface from hardcoded forms through a three-layer JSON schema engine.

Schema Hierarchy

classDiagram
    class WizardSchema {
        +string id
        +string name
        +string itemCategoryId
        +string shopId
        +boolean isActive
        +StepSchema[] steps
    }

    class StepSchema {
        +string id
        +string title
        +number order
        +boolean isFixed
        +boolean isVisible
        +string checkpointId
        +FieldSchema[] fields
    }

    class FieldSchema {
        +string id
        +string label
        +string fieldType
        +number order
        +boolean required
        +string helpText
        +Record config
    }

    WizardSchema "1" *-- "many" StepSchema : contains
    StepSchema "1" *-- "many" FieldSchema : contains

How the Engine Renders at Runtime

sequenceDiagram
    participant User as Store Desk Agent
    participant Wizard as DealWizardExtended (UI)
    participant Engine as Dynamic Wizard Engine
    participant API as /api/deal-wizard

    User->>Wizard: Select Item Category (e.g. "Smartphones")
    Wizard->>API: GET /api/deal-wizard/builders/by-category/{catId}/{shopId}
    API-->>Wizard: Return WizardSchema JSON
    Wizard->>Engine: Parse steps and field definitions
    Engine->>Wizard: Inject Dynamic Steps between "Basic Info" and "Storage"
    User->>Wizard: Enters answers in generated controls
    Wizard->>API: POST /api/deal-wizard/step-data (Auto-Save)
  1. Category Selection: When an operator selects an item category in Step 1, Cashy-Hub checks if a custom WizardSchema exists for that category and store branch.
  2. Dynamic Step Injection: The engine injects the schema's custom steps (e.g. Physical Condition, Battery Health, Accessories) into the navigation stepper.
  3. Two-Way Transformer:
  4. In the administrative builder: flattens stored schemas into draggable canvas components.
  5. On save: validates constraints and packages the definition into the central template registry.
  6. Auto-Save Resilience: Customer responses are automatically validated against configured field rules and saved securely to the central system as the operator completes each step.