bluefly/alternative_services

Discover, configure, and monitor external services and containers from Drupal

dev-feature/integrate-configuration-service 2025-08-11 16:26 UTC

README

Drupal 10 PHP 8.2+ License: MIT

What it actually does: A comprehensive service discovery and orchestration platform centered around the DDEV Addon Browser system. It transforms container management into an intuitive, AI-powered experience with visual composition, unified CLI/UI wizard, and Tour module integration across Docker, Kubernetes, and DDEV environments.

πŸ“‹ Table of Contents

🎯 Overview

The Alternative Services module is the central hub for service discovery and orchestration in the LLM Platform ecosystem. It provides a comprehensive DDEV Addon Browser that allows developers to discover, install, and manage development environment addons through both web interfaces and CLI commands.

Key Capabilities

  • πŸ” Service Discovery: Automatic detection of services across Docker, Kubernetes, and DDEV environments
  • πŸ“¦ DDEV Addon Management: Browse, install, and configure DDEV addons with Node.js enhancements
  • 🎨 Visual Orchestration: Drag-and-drop interface for composing service workflows
  • πŸ€– AI Integration: Smart recommendations and automated configuration generation
  • πŸ”§ CLI Tools: Comprehensive Drush command suite with Tour integration
  • πŸ“Š Health Monitoring: Real-time service status and performance tracking

✨ Core Features

🎯 DDEV Addon Browser

  • Comprehensive addon registry with search, filtering, and categorization
  • One-click installation with dependency resolution and validation
  • Node.js enhancements for CLI tools with interactive interfaces
  • Real-time status monitoring and health checks for installed addons
  • Bulk operations for managing multiple addons simultaneously
  • Integration testing to verify addon compatibility and functionality

πŸ› οΈ Service Discovery Dashboard

  • AI-powered environment detection with automatic service discovery across Docker, Kubernetes, and DDEV
  • Smart categorization with real-time filtering (Web Services, Databases, Caching, Monitoring)
  • Multi-environment discovery from local containers, Kubernetes clusters, and DDEV projects
  • Service health monitoring with dependency analysis and real-time status updates
  • AI recommendations based on automated infrastructure analysis

🎨 Visual Orchestration Builder

  • Drag-and-drop interface for composing service workflows from containers, configs, and networking
  • Real-time validation with dependency checking and conflict detection
  • AI assistance for suggesting optimal service configurations and connections
  • Multiple export formats (Docker Compose, Kubernetes YAML, DDEV Config, Terraform)
  • Auto-save with progress tracking and session management

πŸ§™β€β™‚οΈ Unified Setup Wizard (CLI + UI + Tour)

  • Tour module integration for interactive guided service deployment experiences
  • CLI support (drush service:wizard) with full ASCII interface and interactive prompts
  • Real-time progress via WebSocket for live updates during service deployment
  • Smart rollback capabilities on deployment failure
  • Automatic tour generation from deployed service configurations

πŸ€– AI Integration Points

  • Smart service suggestions based on infrastructure configuration analysis
  • Natural language search for finding relevant services ("I need a web app with database")
  • Automated configuration generation for optimal service settings
  • Intelligent dependency resolution and conflict detection
  • Context-aware help system with troubleshooting for container environments

πŸ”— Smart Integrations

  • Docker Engine: Native container discovery and management
  • Kubernetes: Cluster service orchestration and deployment
  • DDEV: Local development environment integration with addon management
  • SSL Certificate Manager: Automated certificate generation and management
  • Tour Module: Interactive onboarding experiences

πŸ”§ DDEV Addon Browser

The DDEV Addon Browser is the cornerstone feature of the Alternative Services module, providing a comprehensive interface for discovering, installing, and managing DDEV addons within the Drupal environment.

πŸ“¦ Addon Management Features

Browser Interface

  • Visual addon gallery with detailed descriptions, screenshots, and feature lists
  • Search and filtering by category, functionality, and installation status
  • Dependency visualization showing addon relationships and requirements
  • Installation progress tracking with real-time status updates
  • Bulk operations for installing, updating, or removing multiple addons

Available Addons Registry

The system includes support for these core DDEV addons:

AddonDescriptionFeaturesNode.js Enhanced
ddev-llmcliLLM Platform CLIService monitoring, Gateway management, Model operationsβœ…
ddev-tddaiAI-Enhanced TDDStandards checking, Automated fixing, Policy validationβœ…
ddev-git-toolsGit Workflow ToolsSafe commit workflows, Branch managementβœ…
ddev-platform-toolsPlatform ManagementEnvironment orchestration, Service coordinationβœ…
ddev-qdrantVector DatabaseQdrant management, Vector operationsβœ…
ddev-monitoringSystem MonitoringPrometheus metrics, Health dashboardsπŸ”§
ddev-ai-toolsAI Development ToolsModel testing, Training workflowsπŸ”§

Node.js Enhancements

  • Interactive CLI interfaces with rich ASCII art and progress indicators
  • Real-time command feedback with colored output and status updates
  • Command autocompletion and contextual help systems
  • Configuration wizards for complex setup procedures
  • Integration testing suites for validating addon functionality

πŸš€ Installation Methods

Web Interface Installation

  1. Navigate to Configuration > Services > Alternative Services > DDEV Addons
  2. Browse available addons or use search/filter
  3. Click "Install" on desired addon
  4. Monitor installation progress in real-time
  5. Verify installation success and test functionality

CLI Installation

# List available addons
drush alternative-services:addon-list

# Install specific addon
drush as:addon-install ddev-llmcli

# Install multiple addons
drush as:addon-install ddev-llmcli,ddev-tddai,ddev-git-tools

# Install all recommended addons
drush as:addon-install-all

# Install with dependency resolution
drush as:addon-install ddev-platform-tools --with-deps

Bulk Installation

# Install from configuration file
drush as:addon-install --from-config=addon-config.json

# Install development addon suite
drush as:addon-install --suite=development

# Install AI development stack
drush as:addon-install --suite=ai-development

πŸ” Addon Discovery and Search

Smart Search Features

  • Semantic search: Find addons by functionality ("monitoring tools", "git workflow")
  • Tag-based filtering: Filter by categories like "ai", "development", "monitoring"
  • Status filtering: Show installed, available, or updatable addons
  • Dependency search: Find addons that depend on or enhance existing installations

Discovery Mechanisms

# Discover addons from filesystem
drush as:addon-discover

# Refresh addon registry
drush as:addon-refresh

# Scan for new addon versions
drush as:addon-check-updates

# Validate addon installations
drush as:addon-validate

βš™οΈ Configuration Management

Addon Configuration

# Configuration for individual addons
ddev_addons:
  ddev-llmcli:
    enabled: true
    auto_update: false
    config:
      gateway_endpoint: "http://localhost:4000"
      debug_mode: true
  ddev-tddai:
    enabled: true
    auto_update: true
    config:
      standards_level: "strict"
      auto_fix: true

Global Settings

# Global addon system settings
addon_browser:
  auto_install_dependencies: true
  parallel_installations: 3
  health_check_interval: 300
  registry_cache_ttl: 3600
  enable_notifications: true

πŸ“Š Monitoring and Health Checks

Real-time Status Monitoring

  • Installation status: Track progress of addon installations
  • Health monitoring: Continuous monitoring of addon functionality
  • Dependency tracking: Monitor addon interdependencies and conflicts
  • Performance metrics: Track resource usage and performance impact

Health Check Commands

# Check all addon health
drush as:addon-health

# Check specific addon
drush as:addon-health ddev-llmcli

# Run comprehensive addon validation
drush as:addon-validate --comprehensive

# Generate health report
drush as:addon-health-report --output=json

πŸ”§ Advanced Features

Custom Addon Development

  • Addon scaffolding: Generate boilerplate code for new addons
  • Template system: Use predefined templates for common addon types
  • Testing framework: Built-in testing tools for addon validation
  • Documentation generation: Automatic documentation from addon metadata

Integration Points

  • Tour module integration: Interactive tutorials for addon usage
  • GraphQL API: Query addon status and metadata via GraphQL
  • WebSocket updates: Real-time notifications for addon events
  • Event system: Hook into addon lifecycle events

πŸ› οΈ Legacy Features

Discovery Dashboard

  • Real-time service discovery across multiple environments
  • Health monitoring and status tracking
  • SSL certificate management integration
  • AI-powered recommendations
  • Export/import configuration capabilities

Orchestration Builder

  • Visual workflow designer with drag-and-drop interface
  • Node-based service configuration
  • Real-time validation with error reporting
  • Template system for common configurations
  • AI suggestions for optimization

Setup Wizard

  • Multi-step configuration process
  • Environment detection and selection
  • Service discovery and configuration
  • SSL certificate setup
  • Tour mode for guided learning

CLI Integration

  • Interactive Drush commands with ASCII art interfaces
  • Tour-guided CLI workflows
  • Health monitoring and management
  • SSL certificate operations
  • Configuration export/import

πŸ“₯ Installation

System Requirements

  • Drupal: 10.1+
  • PHP: 8.2+
  • DDEV: 1.22+ (recommended)
  • Docker: 20.10+ or compatible container runtime
  • Node.js: 18+ (for enhanced CLI features)
  • Composer: 2.0+

Installation Methods

Standard Installation

  1. Enable the module:

    # Via Drush
    drush en alternative_services -y
       
    # Or via Drupal Admin UI
    # Navigate to Extend > Alternative Services > Install
    
  2. Install dependencies:

    # Install Node.js dependencies for enhanced features
    cd web/modules/custom/alternative_services
    npm install
       
    # Or use the automated installer
    drush alternative-services:install-deps
    
  3. Run initial setup:

    # Interactive setup wizard
    drush alternative-services:setup
       
    # Quick setup with defaults
    drush alternative-services:setup --quick
       
    # Tour-guided setup for first-time users
    drush alternative-services:setup --tour
    

Development Installation

# Clone or ensure module is in custom modules directory
cd web/modules/custom/alternative_services

# Install development dependencies
npm install --dev
composer install --dev

# Run development setup
drush alternative-services:setup --environment=development

# Enable debug mode
drush config:set alternative_services.settings debug_mode true

Production Installation

# Production-optimized installation
drush alternative-services:setup --environment=production

# Configure caching and performance
drush config:set alternative_services.settings cache_enabled true
drush config:set alternative_services.settings parallel_discovery true

# Set up monitoring
drush alternative-services:monitoring:enable

Post-Installation Configuration

Environment Variables

# Add to .env or settings.php
export LLM_PLATFORM_ROOT="/var/www/html"
export ALTERNATIVE_SERVICES_CONFIG_DIR="/var/www/html/config/alternative_services"
export ALTERNATIVE_SERVICES_WS_HOST="localhost"
export ALTERNATIVE_SERVICES_WS_PORT="8080"

Directory Permissions

# Ensure proper permissions for addon management
chmod -R 755 infrastructure/ddev-addons/
chown -R www-data:www-data web/modules/custom/alternative_services/ssl/

πŸš€ Quick Start

Getting Started in 5 Minutes

1. Access the DDEV Addon Browser

# Navigate to addon browser
drush alternative-services:addon-browser

# Or via web interface
# Go to: /admin/config/services/alternative-services/ddev-addons

2. Install Essential Addons

# Install core development stack
drush as:addon-install ddev-llmcli,ddev-tddai

# Or install via web interface
# Click "Install All Recommended" in the addon browser

3. Verify Installation

# Check addon status
drush as:addon-health

# Test installed addons
ddev llm health
ddev tddai check

4. Explore Features

# Launch service discovery
drush alternative-services:discovery --tour

# Try the orchestration builder
drush alternative-services:orchestrate --template=basic

# Access web dashboard
# Navigate to: /admin/config/services/alternative-services

First-Time Setup Wizard

The setup wizard provides an interactive experience for configuring the system:

# Start the comprehensive setup wizard
drush alternative-services:setup --interactive

# The wizard will guide you through:
# 1. Environment detection
# 2. Service discovery configuration  
# 3. DDEV addon selection
# 4. SSL certificate setup
# 5. Integration testing

Common First Tasks

Browse and Install Addons

# List all available addons
drush as:addon-list --format=table

# Search for specific functionality
drush as:addon-search "monitoring"

# Install addon with dependencies
drush as:addon-install ddev-monitoring --with-deps

Configure Service Discovery

# Discover services in current environment
drush as:discover --environment=auto

# Configure custom service endpoints
drush as:service-add --name="Custom API" --endpoint="http://api.local"

# Export discovered configuration
drush as:export --output=services.json

Health Monitoring Setup

# Enable health monitoring
drush as:health-monitoring:enable

# Configure monitoring intervals
drush config:set alternative_services.settings health_check_interval 300

# Set up alerts
drush as:alerts:configure --email=admin@example.com

πŸ“– Usage Guide

Web Interface Navigation

Navigate to Configuration > Services > Alternative Services to access:

  • DDEV Addon Browser: /admin/config/services/alternative-services/ddev-addons
  • Discovery Dashboard: /admin/config/services/alternative-services/discovery
  • Orchestration Builder: /admin/config/services/alternative-services/orchestration
  • Setup Wizard: /admin/config/services/alternative-services/setup
  • Health Monitoring: /admin/config/services/alternative-services/health

Core Workflows

1. Managing DDEV Addons

Browse Available Addons:

  • Visit the DDEV Addon Browser at /admin/config/services/alternative-services/ddev-addons
  • Use search and filters to find relevant addons
  • View detailed addon information, dependencies, and screenshots
  • Check compatibility and system requirements

Install Addons:

  • Click "Install" on any addon card
  • Monitor real-time installation progress
  • Verify successful installation with automatic health checks
  • Access newly installed addon commands via ddev [addon-name]

Manage Installed Addons:

  • View installation status and health indicators
  • Update addons to latest versions
  • Configure addon-specific settings
  • Uninstall unused addons with dependency cleanup

2. Service Discovery and Health Monitoring

Automatic Discovery:

  • Navigate to Discovery Dashboard
  • Click "Start Discovery" to scan environments
  • Review discovered services and their health status
  • Add custom services not automatically detected

Health Monitoring:

  • Access real-time health dashboards
  • Set up monitoring alerts and notifications
  • View historical health data and trends
  • Export health reports for analysis

3. Visual Service Orchestration

Using the Orchestration Builder:

  • Open the Visual Orchestration Builder
  • Drag and drop services to create workflows
  • Configure service connections and dependencies
  • Validate configuration in real-time
  • Export to Docker Compose, Kubernetes YAML, or other formats

Drush Commands

Service Discovery

# Interactive discovery dashboard
drush alternative-services:discovery

# Discover services in specific environment
drush as:discover --environment=ddev

# Export discovered services
drush as:discover --export=/path/config.json

# Start with interactive tour
drush as:discover --tour

Orchestration Builder

# Interactive orchestration builder
drush alternative-services:orchestrate

# Load pre-built template
drush as:orchestrate --load-template=basic

# Validate configuration only
drush as:orchestrate --validate-only

# Tour-guided orchestration
drush as:orchestrate --tour

Setup Wizard

# Full interactive setup
drush alternative-services:setup

# Quick setup with defaults
drush as:setup --quick

# Setup for specific environment
drush as:setup --environment=ddev

# Tour-guided setup
drush as:setup --tour

Health Monitoring

# Check all services health
drush alternative-services:health

# Continuous monitoring
drush as:health --watch

# Check specific service
drush as:health --service=ollama

SSL Management

# Generate SSL certificates
drush alternative-services:ssl generate

# Check certificate status
drush as:ssl status

# Renew certificates
drush as:ssl renew

Tour Generation

# Generate tour from current configuration
drush alternative-services:generate-tour

# Export tour configuration
drush as:tour-gen --output=tour.json

Configuration

Environment Variables

The module supports the following environment variables:

# LLM Platform root directory
export LLM_PLATFORM_ROOT="$HOME$LLM_WORKSPACE_PATH"

# Alternative Services configuration
export ALTERNATIVE_SERVICES_CONFIG_DIR="$HOME/.alternative-services"

# WebSocket configuration
export ALTERNATIVE_SERVICES_WS_HOST="localhost"
export ALTERNATIVE_SERVICES_WS_PORT="8080"

Service Configuration

Configure services via the web interface or by editing configuration files:

# Example service configuration
services:
  ollama:
    name: "Ollama AI Service"
    type: "AI"
    endpoint: "http://localhost:11434"
    enabled: true
    health_check_interval: 30
    ssl_enabled: false
    
  qdrant:
    name: "Qdrant Vector Database"  
    type: "DATABASE"
    endpoint: "http://localhost:6333"
    enabled: true
    health_check_interval: 60
    ssl_enabled: true

SSL Configuration

SSL certificates are managed automatically or can be configured manually:

ssl:
  mode: "auto"  # auto, manual, none
  domain: "local.bluefly.io"
  wildcard: true
  auto_renewal: true
  certificates_path: "/path/to/certificates"

πŸ”Œ API Reference

The Alternative Services module provides comprehensive APIs for programmatic access to all functionality. See docs/api-reference.md for complete documentation.

REST API Overview

DDEV Addon Management

# Addon discovery and management
GET    /api/v1/ddev-addons                    # List available addons
POST   /api/v1/ddev-addons/{id}/install      # Install specific addon
DELETE /api/v1/ddev-addons/{id}/uninstall    # Uninstall addon
GET    /api/v1/ddev-addons/{id}/health        # Check addon health
POST   /api/v1/ddev-addons/install-all       # Bulk install addons

Service Discovery

# Service discovery and monitoring
GET    /api/v1/services                      # List discovered services
POST   /api/v1/services/discover             # Trigger service discovery
GET    /api/v1/services/{id}/health          # Check service health
POST   /api/v1/services/{id}/start           # Start service
POST   /api/v1/services/{id}/stop            # Stop service

Orchestration

# Service orchestration
POST   /api/v1/orchestration/deploy          # Deploy service stack
GET    /api/v1/orchestration/templates       # List available templates
POST   /api/v1/orchestration/validate        # Validate configuration
GET    /api/v1/orchestration/status          # Get deployment status

GraphQL API Overview

type Query {
  # DDEV Addon queries
  ddevAddons: [DdevAddon]
  ddevAddon(id: String!): DdevAddon
  addonHealth(id: String!): AddonHealth
  
  # Service queries
  alternativeServices: [AlternativeService]
  alternativeService(id: String!): AlternativeService
  serviceHealth(id: String!): ServiceHealth
  discoverServices(environment: String!): [DiscoveredService]
}

type Mutation {
  # Addon management
  installAddon(id: String!, config: AddonConfigInput): AddonInstallResult
  uninstallAddon(id: String!): Boolean
  
  # Service management
  createAlternativeService(input: AlternativeServiceInput!): AlternativeService
  updateAlternativeService(id: String!, input: AlternativeServiceInput!): AlternativeService
  deleteAlternativeService(id: String!): Boolean
  executeWorkflow(input: WorkflowInput!): WorkflowResult
}

WebSocket Events

Real-time updates are provided via WebSocket connections:

// Addon installation events
{
  "type": "addon_install_progress",
  "addon_id": "ddev-llmcli",
  "progress": 75,
  "status": "installing_dependencies"
}

// Health monitoring events
{
  "type": "health_update",
  "service_id": "ollama",
  "status": "healthy",
  "metrics": { "cpu": 12.5, "memory": "512MB" }
}

// Discovery events
{
  "type": "service_discovered",
  "service": {
    "id": "new-api-service",
    "name": "Custom API",
    "endpoint": "http://api.local:3000"
  }
}

πŸ—οΈ Architecture

The Alternative Services module follows a layered service-oriented architecture designed for scalability and extensibility.

System Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                     Presentation Layer                         β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚  Web UI (Twig)    β”‚  REST API        β”‚  GraphQL API β”‚  CLI Tools β”‚
β”‚  - Addon Browser  β”‚  - JSON responses β”‚  - Schema    β”‚  - Drush   β”‚
β”‚  - Dashboards     β”‚  - OpenAPI docs   β”‚  - Mutations β”‚  - Tour    β”‚
β”‚  - Wizards        β”‚  - Rate limiting  β”‚  - Queries   β”‚  - ASCII   β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚                     Business Logic Layer                       β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚  Controllers           β”‚  Services                β”‚  Managers   β”‚
β”‚  - DdevAddonController β”‚  - AddonRegistryService  β”‚  - Health   β”‚
β”‚  - ApiController       β”‚  - AddonSearchService    β”‚  - Config   β”‚
β”‚  - DashboardController β”‚  - HealthMonitor         β”‚  - SSL      β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚                     Integration Layer                          β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚  Adapters                β”‚  External APIs      β”‚  Event System β”‚
β”‚  - DdevAdapter          β”‚  - Docker Engine    β”‚  - Hooks       β”‚
β”‚  - OrbStackAdapter      β”‚  - Kubernetes API   β”‚  - WebSockets  β”‚
β”‚  - ContainerRuntime     β”‚  - LLM Gateway      β”‚  - Queue Jobs  β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚                     Data Access Layer                          β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚  Entities              β”‚  Storage           β”‚  Cache Layer    β”‚
β”‚  - DdevAddon           β”‚  - Config system   β”‚  - Redis/Memcacheβ”‚
β”‚  - AlternativeService  β”‚  - State API       β”‚  - File cache    β”‚
β”‚  - ServiceHealth       β”‚  - JSON storage    β”‚  - Database cacheβ”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Core Components

Service Layer Architecture

  • DdevAddonManager: Core service for addon lifecycle management
  • AddonRegistryService: Manages addon discovery and metadata
  • AddonSearchService: Provides search and filtering capabilities
  • HealthMonitor: Continuous health monitoring and alerting
  • ServiceOrchestrator: Manages service deployment and coordination

Entity System

  • DdevAddon: Represents DDEV addon configuration and state
  • AlternativeService: General service configuration entity
  • ServiceHealth: Health monitoring data and metrics
  • DashboardMetric: Performance and usage metrics

Integration Points

  • Container Runtime Adapters: Support for Docker, OrbStack, Podman
  • GraphQL Schema Extensions: Extensible API schema
  • Event Dispatcher: Hook system for custom extensions
  • Queue Workers: Background processing for long-running operations

Design Patterns

Dependency Injection

public function __construct(
  DdevAddonManager $addon_manager,
  AddonRegistryService $addon_registry,
  AddonSearchService $addon_search,
  HealthMonitor $health_monitor
) {
  // Services injected via Drupal DI container
}

Factory Pattern

// Adapter factory for different container runtimes
class ContainerRuntimeFactory {
  public static function create(string $runtime): ContainerRuntimeInterface {
    return match($runtime) {
      'ddev' => new DdevAdapter(),
      'orbstack' => new OrbStackAdapter(),
      'docker' => new DockerAdapter(),
    };
  }
}

Observer Pattern

// Event-driven health monitoring
class AddonHealthMonitor implements EventSubscriberInterface {
  public static function getSubscribedEvents(): array {
    return [
      'addon.installed' => 'onAddonInstalled',
      'addon.health_check' => 'onHealthCheck',
    ];
  }
}

AI Integration

The module integrates with AI services for:

  • Smart Service Discovery: AI-powered service detection and recommendation
  • Configuration Assistance: Intelligent configuration suggestions
  • Health Prediction: Predictive health monitoring and alerting
  • Workflow Optimization: AI-suggested improvements for orchestration workflows

WebSocket Support

Real-time updates are provided via WebSocket connections:

// Connect to WebSocket for real-time updates
const ws = new WebSocket('ws://localhost:8080/alternative-services');

ws.onmessage = function(event) {
  const data = JSON.parse(event.data);
  
  switch(data.type) {
    case 'service_discovered':
      // Handle new service discovery
      break;
    case 'health_update':
      // Handle health status change
      break;
    case 'configuration_change':
      // Handle configuration update
      break;
  }
};

Tour Integration

The module integrates with Drupal's Tour module to provide guided experiences:

  • Interactive step-by-step tutorials
  • Context-aware help and hints
  • CLI command demonstrations
  • Best practice guidance

Tours can be customized and extended through the configuration interface.

Troubleshooting

Common Issues

Service Discovery Not Working

# Check environment detection
drush as:health

# Verify network connectivity
drush as:discover --environment=manual

# Check logs
drush watchdog:show --filter=alternative_services

SSL Certificate Issues

# Regenerate certificates
drush as:ssl generate --force

# Check certificate status
drush as:ssl status

# Verify domain configuration
drush as:ssl status --domain=your-domain.com

WebSocket Connection Errors

  • Ensure WebSocket server is running
  • Check firewall settings
  • Verify port availability
  • Review browser console for errors

Debug Mode

Enable debug mode for additional logging:

# In settings.local.php
$config['alternative_services.settings']['debug'] = TRUE;

Development

Extending the Module

The module follows Drupal best practices and provides extension points:

  1. Custom Service Types: Add new service types via plugins
  2. Discovery Adapters: Implement custom environment adapters
  3. Orchestration Templates: Create reusable workflow templates
  4. AI Integrations: Add custom AI service providers
  5. Tour Customization: Create custom tour configurations

Testing

Run the test suite:

# Unit tests
phpunit --group alternative_services

# Functional tests  
phpunit --group alternative_services_functional

# JavaScript tests
npm test

Support

For support and documentation:

License

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