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: Seamless 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

bluefly / recipe_onboarding

Maintainers

Details