WebPilotAI Module - Comprehensive Documentation

Introduction

Welcome to the WebPilotAI Module documentation! WebPilotAI is a powerful and innovative Laravel module designed to revolutionize the way websites are created. By harnessing the capabilities of advanced Artificial Intelligence models (including OpenAI's GPT series, Anthropic's Claude, and Google's Gemini), users can generate complete, multi-page websites simply by describing their vision.

This module provides a seamless experience, from initial concept to a fully downloadable or deployable website. It features a user-friendly interface for website creation and management, and a comprehensive administrative backend for configuring AI models, content templates, styling presets, and overall module behavior. Whether you're looking to offer AI website generation as a service or empower your users with cutting-edge web design tools, WebPilotAI is your go-to solution.

Key Features

• AI-Powered Multi-Page Website Generation: Go beyond single pages. Generate complex websites with multiple, interconnected pages (e.g., Home, About Us, Services, Contact, Gallery) based on user prompts.
• Flexible AI Model Support: Integrate with leading AI providers:
  • OpenAI (GPT-3.5, GPT-4, etc.)
  • Anthropic (Claude series)
  • Google AI (Gemini models)
• User Asset Management: Users can upload their own images (logos, product photos, etc.) and provide descriptions. These assets are intelligently incorporated by the AI into the website design.
• Advanced AI Templates: Administrators can create sophisticated prompt templates with dynamic placeholders ([USER_PROMPT], [WEBSITE_NAME], [PAGES_LIST], [ASSETS_LIST], [STYLING_GUIDELINES]) to guide the AI for specific website types or structures.
• Comprehensive AI Style Presets: Define reusable styling configurations for colors, fonts, visual themes, and even specific HTML elements. These are presented to the AI in a structured format for consistent styling.
• Intuitive User Interface:
  • Step-by-step website creation form.
  • Clear options for defining pages and uploading assets.
  • Visual selection for AI Templates and Style Presets with previews.
  • Dashboard to view, edit, re-generate, and delete websites.
  • Real-time status updates for generation and deployment processes (via polling).
• Robust Admin Panel:
  • Centralized module settings (API keys, free tier options, defaults).
  • Management of AI Models (add, edit, set premium status).
  • Creation and customization of AI Templates and Style Presets (including preview image uploads).
  • Oversight of all user-generated websites.
• Direct Hosting Deployment:
  • FTP
  • SFTP (Secure FTP)
  • cPanel API (via UAPI Fileman)
• Downloadable Websites: Users can download their complete generated website as a ZIP archive for manual deployment or backup.
• Asynchronous Processing: Website generation and deployment tasks are handled by Laravel Queues (ProcessWebsiteGeneration, DeployWebsiteToHosting jobs), ensuring a non-blocking user experience.
• Subscription & Feature Limiting:
  • Control access to premium AI Models, Templates, and Style Presets based on user subscription plans.
  • Implement usage limits (e.g., maximum number of websites, maximum deployments per period) tied to subscription features.
• Extensible Event System: Dispatches events like WebsiteGenerationSucceeded, WebsiteGenerationFailed, WebsiteDeploymentSucceeded, WebsiteDeploymentFailed for custom integrations.

Installation

Installing the WebPilotAI module is straightforward, especially if your main Laravel application supports module installation via ZIP upload.

Prerequisites

• Laravel Framework: Version 9.x, 10.x, or 11.x (as per your module's compatibility).
• PHP: Version 8.1 or higher (check composer.json for specifics).
• Composer: For managing package dependencies.
• Database: A configured database (MySQL, PostgreSQL, SQLite, SQL Server).
• Queue Driver: A configured queue driver (e.g., database, Redis, Beanstalkd). The database driver is often simplest for initial setup. Ensure a queue worker is running.
• Storage Link: The public storage disk must be linked. If not already done, run:

  php artisan storage:link

• Writable Directories: Ensure storage and bootstrap/cache directories are writable by the web server.

Installation Steps

The WebPilotAI module is designed to be installed by uploading its ZIP package through your Laravel application's admin panel (assuming it has a module management or extension installation feature).

1. Obtain the Module ZIP: Download the WebPilotAI module ZIP file (e.g., WebPilotAI-v1.x.x.zip).
2. Navigate to Admin Module Installation: Log in to your Laravel application's admin panel and find the section for installing new modules or extensions. This is typically labeled "Modules," "Extensions," or "Add-ons."
3. Upload the ZIP File: Use the "Upload Module" or "Install from ZIP" functionality and select the WebPilotAI ZIP file you downloaded.
4. Automatic Installation: The system should handle:
   • Extracting the module files to the correct Modules/ directory.
   • Running any necessary Composer commands (composer dump-autoload).
   • Publishing assets (if any are defined for auto-publishing).
   • Discovering and registering the module's service provider.
5. Run Database Migrations: After the module is recognized by the system, you'll need to run its database migrations. This is usually done via a button in the admin panel for the specific module, or you might need to run it manually via SSH if instructed:

   php artisan module:migrate WebPilotAI

   Or, if your system runs all pending migrations:

   php artisan migrate

6. Configure Queue Worker: Ensure your Laravel queue worker is running to process website generation and deployment jobs. Example for a simple setup:

   php artisan queue:work --tries=3

   For production, it's highly recommended to use a process manager like Supervisor to keep your queue worker running.
7. Initial Configuration: Proceed to the Module Settings section in the admin panel to configure API keys and other essential parameters.

php artisan optimize:clear

Admin Guide For Administrators

This section guides administrators through configuring and managing the WebPilotAI module from the admin panel.

Dashboard Overview

The WebPilotAI admin dashboard (typically found under "WebPilot AI Builder" in the admin menu) provides a central hub for managing all aspects of the module. It usually offers quick stats and links to various management sections.

Module Settings

Navigate to "Module Settings" within the WebPilotAI admin section. Here, you'll configure essential parameters for the module to function correctly.

AI Model Configuration

This section ("AI Model Configuration") allows you to define the specific AI models users can choose from.

Creating/Editing an AI Model:

• Name: A user-friendly name for the model (e.g., "OpenAI GPT-4 Turbo," "Claude 3 Sonnet," "Gemini 1.5 Pro").
• Identifier: The exact model identifier required by the AI provider's API (e.g., gpt-4-turbo-preview, claude-3-sonnet-20240229, gemini-1.5-pro-latest).
• Provider: Select the AI provider (OpenAI, Anthropic, GoogleAI).
• Is Active: Check to make the model available for selection.
• Is Premium: Check if this model should be considered a premium offering. Access to premium models can be controlled by the webpilotai_premium_items_access feature in subscription plans.
• Description (Optional): Briefly describe the model's capabilities or best use cases.

AI Template Management

AI Templates ("AI Templates" section) help guide the AI in generating websites with specific structures or focuses.

Creating/Editing an AI Template:

• Name: A descriptive name for the template (e.g., "Modern Business Portfolio," "E-commerce Product Showcase").
• Description: Explain what the template is for and how it helps.
• Prompt Modifications (JSON): This is the core of the template. It's a JSON object that modifies the final prompt sent to the AI.

  {
    "full_prompt_template": "Optional: A complete prompt string. Use placeholders like [USER_PROMPT], [WEBSITE_NAME], [PAGES_LIST], [ASSETS_LIST], [STYLING_GUIDELINES]. If provided, this overrides prefix/suffix.",
    "prefix": "Optional: Text added BEFORE the user's main prompt and other generated sections.",
    "suffix": "Optional: Text added AFTER the user's main prompt and other generated sections."
  }

  Placeholders:
  • [USER_PROMPT]: The user's detailed website description.
  • [WEBSITE_NAME]: The name of the website.
  • [PAGES_LIST]: A formatted list of pages the user wants (e.g., "Home, About Us, Services").
  • [ASSETS_LIST]: A formatted list of user-uploaded assets and their descriptions.
  • [STYLING_GUIDELINES]: Structured styling instructions derived from selected AI Style Presets.
• Is Active: Make the template available for users.
• Is Premium: Mark as a premium template, controllable via subscription plans.
• Sort Order: Control the display order in the user's selection list.
• Preview Image: Upload an image to visually represent the template.

AI Style Preset Management

AI Style Presets ("AI Style Presets" section) allow users to apply pre-defined visual styles to their websites.

Creating/Editing an AI Style Preset:

• Name: A clear name for the style (e.g., "Dark Mode Elegance," "Pastel Colors - Playful").
• Description: Briefly explain the style.
• Type: Categorize the preset (e.g., color_palette, font_scheme, visual_theme, element_specific_styles, direct_instruction). This helps organize presets for users and for AI processing.
• Configuration (JSON): The specific styling rules in JSON format. Examples:
  • color_palette: {"primary": "#007bff", "secondary": "#6c757d", "background": "#f8f9fa", "text": "#212529"}
  • font_scheme: {"headings": {"family": "Roboto, sans-serif", "weight": "700"}, "body": {"family": "Open Sans, sans-serif"}}
  • visual_theme: {"keywords": ["minimalist", "modern"], "mood": "professional", "corner_style": "slightly-rounded"}
  • element_specific_styles: {"buttons": {"shape": "pill", "hover_effect": "glow"}, "cards": {"shadow": "medium"}}
  • direct_instruction: {"instructions": ["Ensure high contrast for accessibility.", "Use a grid layout for gallery items."]}
• Is Active: Make the preset available.
• Is Premium: Mark as a premium style, controllable via subscription plans.
• Sort Order: Control display order.
• Preview Image: Upload an image (e.g., a color swatch, font example) to represent the style.

Managing User Websites

In the "User Websites" section, administrators can view and manage all websites created by users. This is useful for support, moderation, or analytics.

• View website details (prompt, selected model/template/styles, status).
• Check generation logs or error messages.
• Potentially re-trigger generation or delete websites if necessary.
• Download the generated ZIP for a user.

Subscription Integration

WebPilotAI integrates with your application's subscription system by defining "features" in its module.json file. When you create or edit subscription plans in your main application, you can associate these WebPilotAI features with those plans.

• webpilotai_generate_website: (Limitable) Max AI Websites a user can create.
• webpilotai_deploy_hosting: (Limitable) Max deployments per period.
• webpilotai_premium_items_access: (Not limitable, boolean access) Grants access to AI Models, Templates, and Style Presets marked as "premium."
• Other features like webpilotai_select_ai_model, webpilotai_template_library can also be tied to plans, effectively controlling access to different tiers of AI models or the richness of the template/style library.

Ensure your subscription plan management interface correctly lists and allows selection of these features from the WebPilotAI module.json.

User Guide For End-Users

This guide helps you, the user, to create, manage, and deploy stunning AI-generated websites with WebPilotAI.

Creating a New AI Website

1. Navigate: Go to "My AI Websites" from your user menu and click "Create New AI Website" or a similar button.
2. Website Name (Optional): Give your website a name (e.g., "My Photography Portfolio"). If you leave it blank, the AI might suggest one based on your description.
3. Describe Your Website (The Prompt): This is the most crucial step! Be as detailed as possible. Consider:
   • Purpose: What is the website for (e.g., business, blog, portfolio, event)?
   • Target Audience: Who are you trying to reach?
   • Key Information/Content: What must be included (e.g., services offered, product details, bio, contact info)?
   • Desired Style/Tone: (e.g., modern, minimalist, playful, professional, elegant, rustic). Mention colors, fonts, or general aesthetics if you have preferences.
   • Specific Sections/Features: (e.g., "a gallery for my photos," "a contact form with a map," "a section for customer testimonials").
   Example: "I need a sleek, modern website for my new coffee shop 'The Daily Grind.' It should feature our menu (espresso, pastries, sandwiches), our story, location with a map, and contact details. I want a warm, inviting feel with earthy tones like browns and greens. Include high-quality images of coffee and our shop interior."
4. Choose an AI Template (Optional): Templates can help structure the AI's output. Browse the available templates (they might have preview images) and select one that aligns with your website type. You can also choose "No Specific Template."
5. Choose AI Style Presets (Optional): Select one or more style presets to influence the visual design (colors, fonts, themes). Presets are often grouped by type.
6. Define Your Website Pages:
   • Click "+ Add Page" to add input fields for each page you want (e.g., "Home," "About Us," "Services," "Blog," "Contact").
   • If you leave this empty, default pages (e.g., Home, About, Contact) will usually be created.
7. Upload Website Assets (Images - Optional):
   • Click the file input to select images (JPG, PNG, GIF, WEBP) from your computer. You can select multiple files.
   • These images (e.g., your logo, product photos, portfolio pieces) will be available to the AI to use in the website design.
   • Later, in the edit screen, you can add descriptions to these assets to give the AI more context.
8. Choose AI Generation Model: Select an AI model from the dropdown. Some models might be marked as "[Premium]" or "[Free Tier]" depending on your subscription plan and module configuration.
9. Start Generation: Click "Start AI Website Generation." The system will now process your request in the background.

Managing Your Websites

From the "My AI Websites" dashboard, you can see a list of all your websites.

• View Status: Each website will show its current status (e.g., "Pending Generation," "Generating," "Completed," "Failed," "Deploying"). The status often updates automatically.
• View Details (Show): Click on a website's name or a "View" button to see its full details, including the prompt used, selected options, and any generated content or error messages.
• Download ZIP: Once a website's status is "Completed," a "Download ZIP" button will appear. Click this to download all your website files (HTML, CSS, JS, images) in a single archive.
• Edit: You can edit the details of your website (name, prompt, selected AI model, template, styles, pages, assets).
  • When editing assets, you can upload new ones, remove existing ones, and add/update descriptions for each asset to help the AI understand its context.
  • After making changes, you can choose to "Update Details" or "Update and Re-generate" if you want the AI to create a new version based on your updated inputs.
• Re-generate: If a generation failed or you want to try again with the same settings (or after minor tweaks in the edit screen), use the "Re-generate" option.
• Delete: Remove a website permanently. This will also delete associated generated files and uploaded assets.

Deploying Your Website

Once your website is "Completed," you can deploy it directly to your hosting provider.

1. Access Deploy Form: On the website's detail page or from the website list, find the "Deploy" option.
2. Choose Deployment Type:
   • FTP: Standard File Transfer Protocol.
   • SFTP (Recommended): Secure File Transfer Protocol. More secure than FTP.
   • cPanel API: Deploys using cPanel's UAPI. Requires your cPanel server hostname, username, password, and the cPanel domain.
3. Enter Hosting Credentials:
   • Host / Server Address: Your server's address (e.g., ftp.yourdomain.com, sftp.yourdomain.com, or your cPanel server's hostname like server123.hostprovider.com).
   • Username: Your FTP, SFTP, or cPanel username.
   • Password: Your corresponding password. This is sent securely and typically encrypted for the deployment job.
   • Port (Optional): Usually 21 for FTP, 22 for SFTP. Leave blank for default. For cPanel, this is usually the cPanel port (e.g., 2083 for SSL, but the API often works over standard web ports depending on server config).
   • Remote Path (Optional): The directory on your server where files should be uploaded (e.g., public_html, httpdocs, www, or a subdirectory like public_html/my-new-site).
     • For cPanel, this is often public_html for the main domain or a subfolder within it for addon domains.
     • For FTP/SFTP, use / for the root directory you log into, or specify a path like /var/www/html.
   • cPanel Domain (cPanel Only): The primary domain of your cPanel account, or the specific domain if deploying to an addon domain's root.
4. Start Deployment: Click "Start Deployment." The process will run in the background. You can monitor its status on the website detail page.

Core Concepts Technical Details

This section delves into some of the underlying mechanics of WebPilotAI.

AI Prompt Engineering

The quality of the generated website heavily depends on the final prompt sent to the AI. WebPilotAI constructs this prompt by intelligently combining several pieces of information:

1. Base Instructions: Core instructions telling the AI its role (e.g., "You are an expert web developer creating a multi-page HTML, CSS, and JavaScript website...").
2. User's Description Prompt: The primary input from the user detailing their vision.
3. Website Name: If provided by the user.
4. Pages Structure: A list of requested pages (e.g., "Home (index.html), About Us (about.html), Contact (contact.html)").
5. Asset Information: A list of user-uploaded assets, including their filenames and any descriptions provided by the user (e.g., "logo.png: Main company logo", "hero-image.jpg: A welcoming image for the homepage").
6. AI Template Modifications: If an AI Template is selected, its prefix, suffix, or full_prompt_template (with placeholders filled) is integrated.
7. AI Style Preset Guidelines: Selected style presets are processed into a structured "Styling Guidelines" section, detailing color palettes, font schemes, theme keywords, and specific element styles.
8. Output Format Instructions: Instructions on how the AI should format its response (e.g., providing separate HTML for each page, a main CSS file, and a JS file, often in a specific JSON structure for easier parsing).

This comprehensive prompt aims to give the AI all necessary context to generate a relevant, structured, and well-styled website.

Background Processing (Queues)

Two main background jobs handle intensive tasks:

• Modules\WebPilotAI\Jobs\ProcessWebsiteGeneration:
  • Triggered when a user creates or re-generates a website.
  • Constructs the final AI prompt.
  • Communicates with the selected AI provider's API.
  • Parses the AI's response.
  • Prepares user-uploaded assets.
  • Creates the website structure (HTML, CSS, JS files, asset folders).
  • Packages everything into a ZIP archive.
  • Updates the website's status and dispatches success/failure events.
• Modules\WebPilotAI\Jobs\DeployWebsiteToHosting:
  • Triggered when a user initiates deployment.
  • Retrieves the generated website ZIP.
  • Connects to the specified hosting server (FTP, SFTP, cPanel).
  • Uploads/extracts website files to the remote path.
  • Updates the website's deployment status and dispatches events.

Using queues ensures that these potentially long-running tasks don't freeze the user interface and can be retried in case of temporary failures.

Event System

WebPilotAI dispatches several events that can be listened to by your main Laravel application or other modules for custom integrations:

• Modules\WebPilotAI\Events\WebsiteGenerationSucceeded
• Modules\WebPilotAI\Events\WebsiteGenerationFailed
• Modules\WebPilotAI\Events\WebsiteDeploymentSucceeded
• Modules\WebPilotAI\Events\WebsiteDeploymentFailed

These events carry the relevant Website model instance, allowing you to perform actions like sending notifications, updating analytics, or triggering other workflows.

Troubleshooting

• Website Stuck in "Generating" or "Deploying":
  • Ensure your Laravel queue worker is running: php artisan queue:work. For production, use Supervisor or a similar tool.
  • Check the failed_jobs table in your database for any errors.
  • Review Laravel logs (storage/logs/laravel.log) for more detailed error messages.
• API Key Errors:
  • Double-check that the correct API keys are entered in the Module Settings for the respective AI providers.
  • Ensure your AI provider account is active and has sufficient credits/quota.
• File Permission Issues (Deployment/Asset Upload):
  • Ensure the storage/app/public and module-specific asset/upload directories are writable by the web server and queue worker user.
  • For deployment, ensure the remote FTP/SFTP/cPanel user has write permissions to the target directory.
• cPanel Deployment Fails:
  • Verify cPanel hostname, username, password, and domain are correct.
  • Ensure the cPanel API is enabled for the account and not blocked by firewalls.
  • Check the cPanel server's error logs if possible.
• "Trait PathNamespace not found":
  • This usually indicates an issue with Composer's autoloader. Run composer dump-autoload in your project root.

Upcoming Features & Roadmap

WebPilotAI is continuously evolving. Here are some features planned or under consideration for future releases (many of these are already defined as potential subscription features in module.json):

• AI-Assisted Visual Editor: An intuitive drag-and-drop or point-and-click editor to fine-tune the AI-generated design, with AI suggestions for layout and element changes.
• AI Content Writer for Sections: Tools to help users generate or refine text content (headlines, paragraphs, product descriptions) for specific website sections using AI.
• AI Image Studio & Stock Library Integration: Allow users to generate unique images with AI (e.g., DALL-E, Stable Diffusion integration) or select from a curated stock photo library.
• AI SEO Assistant: Provide AI-driven recommendations for meta tags, keywords, content structure, and image alt-text to improve search engine visibility.
• Website Version History & Rollback: Allow users to save multiple versions of their generated websites and easily revert to a previous state.
• More Advanced AI Template & Style Options: Greater control and flexibility in defining templates and styles, potentially with conditional logic.
• Deeper E-commerce Integration: Specific features for generating e-commerce sites, perhaps with basic product management or cart functionality stubs.
• Analytics & Reporting: Admin reports on module usage, popular models/templates, generation success rates, etc.

Support & Contact

If you encounter issues not covered in this documentation, or if you have suggestions for improvement, please refer to the support channels provided with your module purchase or your organization's internal support system.

For developers looking to extend the module, the codebase is structured following standard Laravel and nwidart/laravel-modules conventions. Key areas for extension include creating new AI provider integrations, adding custom event listeners, or developing new style preset types.