README

An enterprise-grade Drupal recipe for building AI-powered applications with full LLM platform integration.

Overview

The LLM Platform Recipe is a comprehensive Drupal 11 recipe that provides a complete foundation for building AI-powered applications. It integrates with the entire ecosystem and provides advanced project intelligence capabilities through innovative UI components.

Key Features

Core Platform

Drupal 11 Foundation: Modern CMS with recipe-based architecture
AI Integration: LLM providers, MCP protocol support, API normalization
Security Framework: Comprehensive security modules and compliance
Testing Infrastructure: TDD methodology with 100% test coverage
Vector Database: Multi-provider vector storage for embeddings and semantic search

Interactive UI Components

Real-time Dashboard System

Advanced dashboard with live updates and performance monitoring:

WebSocket Integration: Real-time status updates with automatic fallback
Connection Health: Visual indicators for system connectivity
Live Notifications: Instant alerts for status changes and system events
Performance Metrics: Real-time display of system health data

Progressive Assessment Workflow

Guided multi-step assessment process:

Multi-step Wizard: Structured assessment with validation
Pause/Resume: Save progress and continue assessments later
Progress Tracking: Visual indicators showing completion status
Dynamic Forms: Context-aware form fields based on selections

AI Site Score Field

Intelligent content quality measurement:

AI-powered Scoring: Automatic quality assessment of content
Trend Tracking: Monitor improvement or regression over time
Explanations: Detailed insights on score factors
Custom Frequency: Configure automatic calculation intervals
Performance Metrics: Detailed breakdown of quality components

Vector Search Integration

Advanced semantic search capabilities:

Multi-Provider Support: PGVector, Qdrant, Chroma, Pinecone, Weaviate
Embeddings Generation: Create and manage embeddings for any content
Semantic Search: Find content by meaning rather than keywords
Hybrid Search: Combine vector and keyword search for optimal results
RAG Support: Retrieval-augmented generation for AI applications

🚀 Quick Start: One-Command Install

The LLM Platform Recipe now supports a fully automated install process. Just run:

composer create-project bluefly/llm_platform_recipe DEMO
cd DEMO

That's it! The following will happen automatically:

DDEV will be configured (if not already)
Drupal will be installed (admin/admin)
The LLM Platform Recipe will be enabled and applied
The onboarding experience will be enabled
Your browser will launch to the site

Site URL: https://llm-platform.ddev.site
Admin login: admin / admin

What to Expect

After install, you will be redirected to the onboarding experience on first login.
All required modules and configuration are applied automatically.

Troubleshooting

If you see errors about DDEV, make sure it is installed and in your PATH: https://ddev.readthedocs.io/en/stable/#installation
If Composer fails due to network or dependency issues, try again or check your PHP version (>=8.2 required).
If Drush is missing, the setup script will install it for you.
If you need to re-run onboarding: log in as admin/admin and visit /admin/llm-platform/onboarding.

Advanced/Manual Steps (if needed)

If you want to run the setup manually:

chmod +x setup-ddev.sh
./setup-ddev.sh

For more details, see the full documentation below.

Troubleshooting Dependencies

If you encounter Composer dependency issues during installation, we've provided comprehensive fixes:

Read the documentation:
- COMPOSER_REPOSITORY_FIX.md - Details of fixes applied
- Dependency Troubleshooting Guide - Step-by-step resolution
Key fixes implemented:
- Fixed incorrect package names (e.g., drupal/chaos_tool_suite → drupal/ctools)
- Relaxed version constraints for problematic packages
- Improved minimum stability settings
- Removed circular references
- Added guidance for setting up private repositories
Using the updated setup script:
- The setup-ddev.sh script now handles these issues automatically
- Creates a minimal working installation with essential modules
- Uses a symlink approach for local development

Installation in Production

Using Composer

composer create-project drupal/llm_platform_recipe my-ai-platform
cd my-ai-platform
drush recipe:apply llm_platform
drush llm:setup-wizard --environment=production

Using Drush

If you have an existing Drupal site, you can add this recipe:

composer require drupal/llm_platform_recipe
drush recipe:apply llm_platform

Vector Database Integration

To enable the vector database integration:

# Apply the vector database recipe
drush recipe:apply llm_platform_vector

# Configure vector database settings
drush config:set llm_platform_recipe.vector_database default_provider pgvector
drush config:set llm_platform_recipe.vector_database embedding_model text-embedding-3-small

# Create a vector database connection (PGVector example)
drush vector:create-connection pgvector_local pgvector --host=localhost --port=5432 --database=drupal --username=postgres --password=postgres

Configuration

# Configure AI providers
drush config:set llm_platform_recipe.providers openai_api_key "your-key"

# Set up health monitoring
drush config:set llm_platform_recipe.health_monitor interval 30

# Enable real-time features
drush config:set llm_platform_recipe.realtime websocket_enabled true

Testing

All features are built using strict TDD methodology:

# Run tests in DDEV
ddev run-tests

# Or run specific test suites
ddev run-tests Unit
ddev run-tests Kernel
ddev run-tests Functional

# Run tests with PHPUnit directly
./vendor/bin/phpunit -c phpunit.ddev.xml tests/src/Unit/

Test Coverage

Unit Tests: Core logic and service functionality
Kernel Tests: Service integration and dependency injection
Functional Tests: UI interactions and form handling
JavaScript Tests: Client-side functionality and AJAX operations

Development

Local Development Setup

# Clone and install with DDEV (recommended)
git clone [repository-url]
cd llm_platform_recipe
./setup-ddev.sh

# Alternative manual approach (requires dependency configuration)
git clone [repository-url]
cd llm_platform_recipe
composer install

Directory Structure

This repository follows the standardized Drupal recipe structure:

llm_platform_recipe/
├── recipe/                  # Main recipe definitions
│   └── llm_platform_recipe.yml  # Main recipe file
├── recipe.yml               # Symlink to recipe/llm_platform_recipe.yml
├── config/                  # Configuration files and templates
│   ├── install/             # Default configurations
│   ├── schema/              # Configuration schemas
│   └── recipes/             # Organized sub-recipes by category
│       ├── base/            # Core foundation recipes
│       ├── components/      # Component recipes
│       ├── llm_platform/    # LLM Platform-specific recipes
│       ├── environments/    # Environment-specific recipes
│       ├── onboarding/      # Onboarding experience recipes
│       ├── agents/          # Agent configuration recipes
│       ├── recommended/     # Optional enhancement recipes
│       └── advanced/        # Advanced optimization recipes
├── docs/                    # Documentation
│   └── core/                # Core documentation files
├── llm_platform_recipe.info.yml  # Module information
├── llm_platform_recipe.install   # Installation hooks
├── llm_platform_recipe.module    # Module hooks
├── llm_platform_recipe.services.yml # Service definitions
├── phpunit.xml              # Test configuration
├── README.md                # Main readme
├── src/                     # PHP source code
│   ├── Service/             # Service implementations
│   ├── Plugin/              # Plugins
│   ├── Form/                # Forms
│   └── Controller/          # Controllers
├── templates/               # Twig templates
├── tests/                   # Tests directory
│   ├── src/                 # Test implementations
│   ├── fixtures/            # Test fixtures
│   └── recipes/             # Test recipes
└── vendor/                  # Composer dependencies (gitignored)

For more detailed information about the directory structure, see DIRECTORY_STRUCTURE.md.

Adding New Features

All new features must follow TDD methodology:

RED: Write failing tests defining expected behavior
GREEN: Implement minimal code to pass tests
REFACTOR: Optimize code while maintaining test coverage

Documentation

This project uses a consolidated documentation approach with key information centralized in the docs directory and inline documentation in source files.

Main Documentation Sources

docs/: Central documentation directory for all markdown documentation
Source code files: Contains inline documentation and implementation notes
README.md: Primary documentation source (this file)
recipe.yml: Recipe configuration and metadata

Reference Documentation

Note: Additional documentation is being consolidated into this README and source files to reduce the number of separate markdown files. Check the Development TODOs section above for current tasks.

Security

Comprehensive security framework with:

Input Validation: Strict validation for all user inputs
API Security: Rate limiting, authentication, and encryption
Compliance: Security standards and audit logging
Monitoring: Real-time security event detection

Maintenance Scripts

This recipe includes maintenance scripts to help with development and cleanup:

cleanup.sh: Script for cleaning up the directory to ensure proper recipe structure
validate-recipe.sh: Validates the recipe structure after cleanup

# Clean up recipe structure
./cleanup.sh

# Validate recipe structure
./validate-recipe.sh

Development TODOs

The following TODOs are tracked directly in this repository to maintain a clear roadmap:

CI/CD Pipeline TODOs

Check .gitlab-ci.yml for detailed TODO comments on implementing revolutionary CI features
Key areas include self-healing capabilities, AI-powered testing, and automated optimization

API Integration TODOs

LLM provider integration needs proper authentication setup - see llm_platform_recipe.module
Vector database backends require configuration - see src/Service/VectorDatabaseManager.php
MCP protocol integration is partially implemented - see src/Service/McpIntegrationService.php

Testing TODOs

Add automated tests for real-time dashboard features
Implement performance benchmarks for vector database operations
Add contract tests for external API dependencies

Documentation TODOs

Expand configuration examples for common use cases
Add troubleshooting guide for vector database connection issues
Document custom module extension points with examples

Next Milestone TODOs

Implement federated learning capabilities
Add support for custom embedding models
Integrate with Drupal Migration system for legacy content

Contributing

Fork the repository
Create a feature branch following TDD methodology
Write tests before implementation
Ensure all tests pass
Submit a pull request

License

This project is licensed under the GPL-2.0+ license. See LICENSE for details.

Directory Structure Note

This is a Drupal recipe, not a Drupal site. The directory structure follows Drupal recipe standards:

config/ - Configuration templates
docs/ - Documentation
config/recipes/ - Recipe definitions by category
src/ - PHP source code
templates/ - Twig templates
tests/ - Test implementations

For more information about the structure, see DIRECTORY_STRUCTURE.md.

bluefly / llm_platform_recipe

Maintainers

Details