README

"navtitle": "recipe_onboarding" "shortdesc": "Complete Recipe Management Framework for Drupal Builders" "source": "Last updated: 2025-08-07"

"outputclass": "concept"

Recipe Onboarding - Complete Recipe Management Framework

What it actually does: A comprehensive Drupal recipe builder and onboarding system that transforms recipe development into an intuitive, AI-powered experience with visual composition, unified CLI/UI wizard, and Tour module integration.

✨ Key Features

🎯 Recipe Discovery Dashboard

AI-powered search with natural language queries ("describe what you want to build")
Smart categorization with real-time filtering (Starter Kits, Features, Integrations, Migrations)
Multi-source discovery from Drupal.org, GitHub, local files, and custom sources
Recipe preview with dependency analysis before installation
AI recommendations based on automated site analysis

🛠️ Visual Recipe Builder

Drag-and-drop interface for composing recipes from modules, config, and content
Real-time validation with dependency checking and conflict detection
AI assistance for suggesting components and generating content
Multiple export formats (YAML, ZIP, Composer package)
Auto-save with progress tracking and session management

🧙‍♂️ Unified Onboarding Wizard (CLI + UI + Tour)

Tour module integration for interactive guided experiences
CLI support (drush recipe:wizard) with full ASCII interface
Real-time progress via WebSocket for live updates
Smart rollback capabilities on failure
Automatic tour generation from applied recipes

🤖 AI Integration Points

Smart recipe suggestions based on site configuration analysis
Natural language search for finding relevant recipes
Automated content generation for default content
Intelligent dependency resolution and conflict detection
Context-aware help system with troubleshooting

🔗 Smart Integrations

Recipe Generator: Visual recipe composition
Drupal AI: Intelligent suggestions and content generation
ECA Workflows: Event-driven recipe automation
ECK Entities: Custom entity management in recipes
Tour Module: Interactive onboarding experiences

🚀 Usage Examples

CLI Mode

# Interactive wizard with AI assistance
drush recipe:wizard --ai

# Apply specific recipe with tour creation
drush recipe:wizard --recipe=blog_starter --tour

# Non-interactive batch mode
drush recipe:wizard --recipe=ecommerce --non-interactive

UI Mode

Discovery: Visit /recipe-onboarding/dashboard
Builder: Use /recipe-onboarding/builder
Wizard: Start at /recipe-onboarding/wizard
Tours: Add ?tour=1 to any page

Build Process

This module uses modern JavaScript tooling for asset compilation and E2E testing:

Prerequisites

Node.js 18+
npm or yarn
DDEV (for local development)
Playwright browsers (for E2E testing)

Installation

# Install dependencies
npm install

# Install Playwright browsers
npm run install:browsers

Development

# Watch and compile assets during development
npm run watch

# Build for production
npm run build

# Run linting
npm run lint

# Fix code style issues
npm run lint:fix

# Run tests
npm run test

# E2E testing
npm run test:e2e

Testing

The module includes comprehensive testing:

# Unit tests (Jest)
npm run test:unit

# Integration tests
npm run test:integration

# E2E tests (Playwright)
npm run test:e2e

# Visual regression tests
npm run test:visual

# Accessibility tests
npm run test:a11y

Architecture

Core Services

recipe_onboarding.discovery: Advanced recipe discovery with multiple sources
recipe_onboarding.wizard: Unified wizard orchestration (CLI/UI/Tour)
recipe_onboarding.builder: Visual recipe composition engine
recipe_onboarding.ai_assistant: AI-powered recommendations and assistance
recipe_onboarding.tour_integration: Tour module integration service

Custom Entities

OnboardingSession: Tracks user progress through recipe workflows
Recipe: Enhanced recipe metadata with AI analysis
RecipeStep: Individual workflow steps with tour integration

API Endpoints

POST /recipe-onboarding/api/search-recipes - AI-updated recipe search
POST /recipe-onboarding/api/validate - Recipe validation
GET /recipe-onboarding/api/progress/{session} - Real-time progress tracking
POST /recipe-onboarding/api/save-draft - Auto-save functionality
POST /recipe-onboarding/api/export - Recipe export in multiple formats

JavaScript Components

RecipeBuilder: Drag-and-drop recipe composition with AI assistance
RecipeWizard: Unified wizard with CLI/UI/Tour integration
RecipeDiscovery: AI-powered search and filtering
TourIntegration: Direct Tour module integration

Configuration

Basic Setup

# Enable module with dependencies
ddev drush en recipe_onboarding ai tour eca eck -y

# Import configuration
ddev drush cim -y

# Clear caches
ddev drush cr

AI Configuration

Set up AI providers in /admin/config/ai:

OpenAI API key for recipe analysis
Anthropic Claude for natural language processing
Local Ollama for on-premise AI (optional)

Tour Module Setup

# Enable tour module
ddev drush en tour -y

# Configure tour settings
ddev drush config:set tour.settings auto_start true

Developer Guidelines

Creating Recipe Templates

// In your custom module
use Drupal\recipe_onboarding\Service\RecipeManager;

$recipeManager = \Drupal::service('recipe_onboarding.recipe_manager');
$recipe = $recipeManager->createTemplate('my_recipe', [
  'name' => 'My Custom Recipe',
  'description' => 'A custom recipe for specific functionality',
  'category' => 'feature',
  'install' => ['views', 'pathauto'],
  'config' => ['system.site', 'views.view.my_view'],
]);

Adding AI Suggestions

// Custom AI suggestion provider
class MyAISuggestionProvider implements AISuggestionProviderInterface {
  public function getSuggestions(array $context): array {
    return [
      [
        'name' => 'Custom Feature',
        'reason' => 'Based on your content types, this would be helpful',
        'confidence' => 0.85,
      ]
    ];
  }
}

Custom Tour Steps

// Add custom tour tips
$tour = \Drupal::entityTypeManager()->getStorage('tour')->create([
  'id' => 'my_recipe_tour',
  'label' => 'My Recipe Tour',
  'routes' => [['route_name' => 'my_module.page']],
  'tips' => [
    [
      'id' => 'welcome',
      'plugin' => 'text',
      'label' => 'Welcome',
      'body' => 'Welcome to your new recipe!',
    ],
  ],
]);
$tour->save();

Troubleshooting

Common Issues

Recipe application fails:

# Check requirements
drush recipe:wizard --validate-only

# View detailed logs
tail -f /var/log/recipe_onboarding.log

AI features not working:

Verify API keys are configured in /admin/config/ai
Check AI module is enabled and configured
Test connection: drush ai:test-connection

Tour not showing:

Ensure Tour module is enabled
Check route permissions
Verify tour is enabled: drush tour:list

Performance Optimization

# Enable caching
ddev drush config:set recipe_onboarding.settings cache.enabled true

# Configure Redis (optional)
ddev drush config:set recipe_onboarding.settings cache.backend redis

Contributing

Code Standards

Follow Drupal coding standards
Use npx @bluefly/tddai for TDD workflow
AI features are optional - provide fallbacks
All new features must include tours

Testing Requirements

Unit tests for all services
Integration tests for workflows
E2E tests for critical paths
Accessibility compliance (WCAG 2.1 AA)

Documentation

Update this README for new features
Add inline code documentation
Create tour guides for complex features
Update API documentation in OpenAPI specs

License

This module is part of the LLM Platform ecosystem and follows the same licensing terms.

Support

Issues: Report bugs and feature requests via the issue tracker
Documentation: Full documentation at /recipe-onboarding/help
API Reference: OpenAPI specs at /recipe-onboarding/api/docs
Community: Join discussions in the LLM Platform community

Enhanced AI Conversation Usage Guide

Overview

The Recipe Onboarding module now provides sophisticated AI conversation capabilities that go far beyond basic chatbots. These conversations provide intelligent, context-aware assistance for recipe installation, configuration, and team collaboration.

Key Features

🤖 Intelligent Conversation Management

Context-Aware Responses: AI understands your environment, experience level, and goals
Multi-Step Guided Flows: Structured workflows with intelligent branching
Real-Time Problem Solving: Instant error analysis and solution recommendations
Collaborative Conversations: Team-based implementations with role-specific guidance

🔄 Advanced Conversation Flows

Smart Branching: Conversations adapt based on user responses and context
Progress Tracking: Real-time progress monitoring with time estimates
Error Recovery: Automatic detection and resolution of installation issues
Performance Analytics: Detailed insights into conversation effectiveness

Basic Usage Examples

1. Creating an Enhanced Onboarding Conversation

<?php
use Drupal\recipe_onboarding\Service\OnboardingConversationManager;
use Drupal\llm\Entity\AiConversation;

// Get the conversation manager service
$conversation_manager = \Drupal::service('recipe_onboarding.conversation_manager');

// Create an onboarding session
$session = \Drupal::entityTypeManager()->getStorage('onboarding_session')->create([
  'type' => 'default',
  'title' => 'LLM Platform Setup',
  'field_session_name' => 'AI-Guided LLM Platform Installation',
  'field_session_status' => 'in_progress',
  'field_selected_recipe' => 'llm_platform',
  'uid' => \Drupal::currentUser()->id(),
]);
$session->save();

// Define user preferences for personalized experience
$user_preferences = [
  'experience_level' => 'intermediate',
  'deployment_target' => 'production',
  'team_size' => 'small',
  'priority' => 'security',
  'time_constraint' => '2_hours',
  'environment' => 'ddev_local',
];

// Create comprehensive AI conversation
$conversation = $conversation_manager->createOnboardingConversation(
  $session,
  'llm_platform',
  $user_preferences
);

// The conversation now includes:
// - Intelligent context understanding
// - Personalized guidance based on experience level
// - Environment-specific recommendations
// - Role-based access controls
// - Progress tracking and analytics

echo "Conversation created with ID: " . $conversation->id();

2. Implementing Multi-Step Guided Flows

<?php
// Generate a complete conversation flow
$conversation_flow = $conversation_manager->createGuidedConversationFlow(
  'llm_platform',
  $user_preferences
);

// The flow includes these intelligent steps:
foreach ($conversation_flow as $step_name => $step_config) {
  echo "Step: {$step_name}\n";
  echo "Type: {$step_config['type']}\n";
  echo "Title: {$step_config['title']}\n";
  
  // Each step has AI-powered capabilities:
  if (isset($step_config['ai_prompt'])) {
    echo "AI Guidance: {$step_config['ai_prompt']}\n";
  }
  
  if (isset($step_config['validation_rules'])) {
    echo "Auto-validation: Available\n";
  }
  
  if (isset($step_config['real_time_monitoring'])) {
    echo "Real-time monitoring: Enabled\n";
  }
  
  echo "---\n";
}

// Example output:
// Step: welcome
// Type: assessment
// Title: Welcome to LLM Platform Setup
// AI Guidance: [Personalized welcome based on experience level]
//
// Step: prerequisites 
// Type: validation
// Title: Prerequisites Verification
// Auto-validation: Available
//
// Step: installation
// Type: execution
// Title: Guided Installation
// Real-time monitoring: Enabled

3. Handling Intelligent Conversation Branching

<?php
// Simulate user interaction with intelligent branching
$user_response = "I'm new to Drupal but experienced with web development. I want to focus on security and scalability.";

$context = [
  'current_step' => 'welcome',
  'current_environment' => 'ddev_local',
  'available_time' => '2_hours',
  'team_involvement' => FALSE,
];

// Handle intelligent branching
$response_data = $conversation_manager->handleIntelligentBranching(
  $conversation,
  $user_response,
  $context
);

// The AI analyzes the response and provides:
echo "AI Response: " . $response_data['ai_response'] . "\n";
echo "Confidence Score: " . $response_data['confidence_score'] . "\n";
echo "Recommended Actions:\n";
foreach ($response_data['recommended_actions'] as $action) {
  echo "- {$action}\n";
}

// Example intelligent response:
// "Since you're experienced with web development but new to Drupal, I'll focus on 
// explaining Drupal-specific concepts while moving quickly through general web dev topics.
// For security and scalability, I'll emphasize best practices and enterprise configurations."

4. Real-Time Problem Solving

<?php
// Handle installation errors with AI-powered problem solving
$error_context = [
  'error_type' => 'module_dependency',
  'error_message' => 'The following modules are missing: llm, ai_provider_openai',
  'error_context' => [
    'current_step' => 'installation',
    'attempted_action' => 'ddev drush en llm_platform',
    'environment' => 'ddev_local',
    'php_version' => '8.3',
    'drupal_version' => '10.5.2',
  ],
];

// Get AI-powered solution
$solution_data = $conversation_manager->handleRealTimeProblemSolving(
  $conversation,
  $error_context
);

// The AI provides comprehensive solutions:
echo "Error Analysis: " . $solution_data['error_analysis']['description'] . "\n";
echo "Primary Solution: " . $solution_data['primary_solution']['title'] . "\n";
echo "Success Probability: " . $solution_data['success_probability'] . "%\n";
echo "Estimated Fix Time: " . $solution_data['estimated_time'] . " minutes\n";

echo "\nStep-by-step resolution:\n";
foreach ($solution_data['resolution_steps'] as $step) {
  echo "- {$step}\n";
}

echo "\nPrevention Tips:\n";
foreach ($solution_data['prevention_tips'] as $tip) {
  echo "- {$tip}\n";
}

5. Collaborative Team Conversations

<?php
// Create team-based collaborative conversation
$team_members = [1, 2, 3]; // User IDs
$roles_mapping = [
  '1' => 'project_lead',
  '2' => 'developer', 
  '3' => 'devops_engineer',
];

$collaborative_conversation = $conversation_manager->createCollaborativeConversation(
  'llm_platform',
  $team_members,
  $roles_mapping
);

// The AI provides role-specific guidance:
// - Project Lead: Timeline management, milestone tracking, risk assessment
// - Developer: Technical implementation, code quality, integration points
// - DevOps: Infrastructure, deployment, monitoring, security

echo "Collaborative conversation created for team of " . count($team_members) . " members\n";
echo "Conversation ID: " . $collaborative_conversation->id() . "\n";

// Each team member gets personalized guidance
foreach ($roles_mapping as $user_id => $role) {
  echo "User {$user_id} ({$role}): Receives {$role}-specific guidance\n";
}

Advanced API Usage

REST API Examples

Start an AI Conversation

curl -X POST /recipe-onboarding/ai-conversation/start \
  -H "Content-Type: application/json" \
  -d '{
    "recipe_id": "llm_platform",
    "user_preferences": {
      "experience_level": "intermediate",
      "deployment_target": "production",
      "team_size": "small",
      "priority": "security"
    }
  }'

Interact with Conversation

curl -X POST /recipe-onboarding/ai-conversation/123/interact \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I encountered an error during module installation",
    "step": "installation",
    "context": {
      "current_environment": "ddev_local",
      "error_message": "Module dependency not found"
    }
  }'

Get Real-Time Problem Solving

curl -X POST /recipe-onboarding/ai-conversation/123/problem-solve \
  -H "Content-Type: application/json" \
  -d '{
    "error_type": "module_dependency", 
    "error_message": "Module xyz is missing",
    "error_context": {
      "current_step": "installation",
      "attempted_action": "drush en recipe_name",
      "environment": "ddev_local"
    }
  }'

Advanced Analytics and Insights

<?php
// Generate conversation analytics
$insights = $conversation_manager->generateConversationInsights($conversation);

echo "Conversation Analytics:\n";
echo "Duration: " . $insights['duration'] . " minutes\n";
echo "Interactions: " . $insights['interaction_count'] . "\n";
echo "Success Rate: " . $insights['success_rate'] . "%\n";
echo "User Satisfaction: " . $insights['user_satisfaction'] . "/10\n";

echo "\nLearning Opportunities:\n";
foreach ($insights['learning_opportunities'] as $opportunity) {
  echo "- {$opportunity}\n";
}

echo "\nImprovement Recommendations:\n";
foreach ($insights['improvement_recommendations'] as $recommendation) {
  echo "- {$recommendation}\n";
}

Key Benefits

🎯 Personalized Experience

Adapts to user experience level (beginner, intermediate, advanced)
Considers deployment context (local, staging, production)
Respects time constraints and priorities

🔧 Intelligent Problem Resolution

Real-time error detection and analysis
Multiple solution strategies with confidence scores
Preventive guidance to avoid future issues

👥 Team Collaboration

Role-based guidance for team members
Coordination workflows and milestone tracking
Conflict resolution and decision support

📊 Continuous Improvement

Detailed analytics and performance metrics
Learning opportunity identification
User satisfaction tracking and optimization

Integration with Your LLM Platform Recipe

To maximize the benefits in your LLM platform recipe:

Enhanced Dependency Management: AI helps resolve complex module dependencies
Security Configuration: Intelligent security recommendations based on deployment context
Performance Optimization: AI-guided performance tuning for your specific setup
Team Onboarding: Collaborative conversations for team-based implementations
Troubleshooting: Real-time problem solving during recipe installation

This enhanced AI conversation system transforms recipe onboarding from a static process into an intelligent, adaptive, and collaborative experience that scales with your team and complexity requirements.

bluefly / recipe_onboarding

Maintainers

Details