Agentic WordPress App Builder — AI Website Generator

Build complete WordPress websites from a single sentence. An open-source, agentic AI system that transforms natural language prompts into fully functional WordPress-backed headless sites with Next.js frontends — powered by CrewAI multi-agent orchestration and multiple LLM providers.

---

What It Does

Type a prompt like "Build me a cozy coffee shop website with an online menu and blog" and the system will:

1. Plan the site architecture, color palette, and layout
2. Generate a complete Next.js frontend with Tailwind CSS
3. Provision WordPress content (pages, posts, menus, media)
4. Preview the live site in real-time via WebSocket updates
5. Iterate — modify the site with follow-up natural language instructions

No templates. No drag-and-drop. Just describe what you want.

---

Key Features

| Feature | Description | |---------|-------------| | Multi-Agent AI Pipeline | 6+ specialized CrewAI agents (Planner, Content Strategist, Faust Engineer, Modifier, QA, Imager) | | 8 Layout Archetypes | Gradient Hero, Split Hero, Masonry Stories, Magazine, Sidebar, Centered Minimal, E-commerce Boutique, E-commerce Marketplace | | WordPress Headless CMS | WPGraphQL + Faust.js/Next.js for blazing-fast frontends | | Multi-LLM Support | OpenRouter and DigitalOcean GenAI with automatic fallback between models | | Real-Time Progress | WebSocket-based live updates during generation | | Iterative Modification | Lovable-style natural language edits ("make the header dark blue") | | WooCommerce Support | E-commerce sites with product catalogs, cart, and checkout | | AI Image Generation | Automatic placeholder images uploaded to WordPress Media Library | | SEO Optimization | Auto-generated meta tags, Open Graph, sitemaps, and robots.txt | | Docker Development | Full Docker Compose stack — zero local dependencies | | E2E Testing | Playwright test suite for generated sites |

---

Architecture

User Prompt ("Build me a flower shop website")
        │
        ▼  WebSocket
┌──────────────────────────────────────────────────────┐
│              FastAPI Backend (Python)                 │
│                                                      │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐     │
│  │  Planner   │→ │  Content   │→ │   Faust    │     │
│  │  Agent     │  │  Strategy  │  │  Engineer  │     │
│  │ (analyze)  │  │  (content) │  │  (code)    │     │
│  └────────────┘  └────────────┘  └────────────┘     │
│                                                      │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐     │
│  │  Modifier  │  │  QA Agent  │  │  Imager    │     │
│  │  Agent     │  │  (verify)  │  │  Agent     │     │
│  │ (iterate)  │  │            │  │ (images)   │     │
│  └────────────┘  └────────────┘  └────────────┘     │
│                                                      │
│  WordPress REST API ←→ WPGraphQL ←→ Faust.js/Next.js│
└──────────────────────────────────────────────────────┘
        │
        ▼
┌──────────────────────────────────────────────────────┐
│  Multiple LLM Providers (with automatic fallback)    │
│  • OpenRouter (Grok, Kimi K2, Devstral, Qwen3)      │
│  • DigitalOcean GenAI (GPT-OSS-120B, Qwen3-32B)     │
└──────────────────────────────────────────────────────┘

---

Quick Start

Prerequisites

• Docker & Docker Compose
• An API key from OpenRouter (free tier available)

1. Clone & Configure

git clone https://github.com/YOUR_USERNAME/agentic-wordpress-app-builder.git
cd agentic-wordpress-app-builder

# Create your environment file
cp docker/env.template docker/.env
# Edit docker/.env and add your OPENROUTER_API_KEY

2. Start the Stack

# Boot everything
docker compose -f docker/docker-compose.yml up -d

# Wait ~2 minutes for WordPress to initialize, then open:
# Builder UI:    http://localhost:3000
# WordPress:     http://localhost:8080
# API:           http://localhost:8000
# Site Preview:  http://localhost:3001

3. Build a Website

Open http://localhost:3000 and type a prompt like:

"Create a modern portfolio website for a freelance photographer with a gallery, about page, and contact form"

Watch the agents work in real-time, then preview your generated site.

---

Service Ports

| Service | Port | Purpose | |---------|------|---------| | mysql | 3306 | WordPress database | | wordpress | 8080 | WordPress admin / WPGraphQL | | builder-backend | 8000 | FastAPI + CrewAI orchestrator | | builder-frontend | 3000 | Vue 3 builder UI | | faust-preview | 3001 | Faust.js Next.js preview |

---

How It Works

Generation Pipeline (Current)

1. Planning + Mode Selection — Prompt is parsed into a SiteSpec, then questionnaire answers set one of four runtime modes: headless/non_headless × ecommerce on/off.
2. Parallel Intelligence Stage — Design, content strategy, and component architecture run in parallel; palette and typography tokens are resolved early.
3. Layout + Content Synthesis — Layout orchestrator selects an archetype and style pack, then generates layout-specific business copy and section content.
4. WordPress Provisioning — Pages/posts/media are created first, followed by WooCommerce setup when enabled (products, gateways, cart/checkout pages).
5. Theme Build — WordPress FSE theme files are generated and installed. In headless mode this still drives visual tokens and structure.
6. Template-First Headless Build — Headless mode seeds from canonical Faust templates first, then applies generated overrides and targeted repairs.
7. Deterministic Verification Loop — Real next build verification runs after copy-to-preview; build errors go through retry + deterministic restore + template fallback.
8. Preview Sync + Runtime Guards — Generated output is copied into the mutable preview workdir with stale-file cleanup and canonical runtime file enforcement.

Mode Matrix

| Mode | Frontend Runtime | Content/Commerce Backend | Preview URL | |------|------------------|--------------------------|-------------| | headless + non-ecommerce | Faust.js / Next.js | WordPress pages/posts | http://localhost:3001 | | headless + ecommerce | Faust.js / Next.js | WordPress + WooCommerce | http://localhost:3001 | | non_headless + non-ecommerce | WordPress FSE theme | WordPress pages/posts | http://localhost:8080 | | non_headless + ecommerce | WordPress FSE theme | WordPress + WooCommerce | http://localhost:8080 |

Reliability Improvements in the New Pipeline

• Template source vs preview split — immutable faust-template/ and mutable faust-preview-workdir/ prevent template corruption across runs.
• Per-site palette isolation — theme CSS is scoped by site_id in API memory and persisted into each generated site to prevent cross-site leakage.
• Build-fix loop with fallback — compiler-verified retries plus canonical restore improve recovery when generated TSX is invalid.
• Copy-time cleanup — stale pages/components are removed before preview copy to avoid orphaned imports and build drift.

Modification Pipeline (Lovable-style)

After initial generation, modify your site with natural language:

"Make the hero section gradient go from purple to pink"
"Add a testimonials section with 3 cards"
"Change the navigation to a sidebar layout"

The Modifier Agent makes surgical, targeted edits — no full regeneration needed.

---

Tech Stack

| Layer | Technology | |-------|-----------| | AI Orchestration | CrewAI, LiteLLM | | LLM Providers | OpenRouter, DigitalOcean GenAI | | Backend | Python 3.10+, FastAPI, WebSockets | | CMS | WordPress, WPGraphQL, WooCommerce | | Frontend Framework | Faust.js, Next.js, React, TypeScript | | Builder UI | Vue 3, Vite, Tailwind CSS | | Styling | Tailwind CSS (generated sites) | | Database | MySQL 8.0 | | Infrastructure | Docker Compose, Caddy (production) | | Testing | Pytest, Playwright, Vitest |

---

Project Structure

├── backend/                 # Python backend
│   ├── agents/              # CrewAI agent definitions
│   ├── api/                 # FastAPI routes & WebSocket handlers
│   ├── config/              # LLM config, provider factory, settings
│   ├── models/              # Pydantic models
│   ├── prompts/             # Prompt templates & few-shot examples
│   ├── services/            # Image generation, SEO, logging
│   ├── tools/               # CrewAI tool definitions
│   └── utils/               # Helpers (file writing, HTML parsing)
├── builder-frontend/        # Vue 3 builder UI
├── docker/                  # Docker Compose, Dockerfiles, configs
├── docs/                    # Architecture docs, deployment guides
├── e2e/                     # Playwright E2E tests
├── faust-template/          # Next.js/Faust.js site template
├── lib/                     # Shared Python libraries
├── scripts/                 # Setup & deployment scripts
├── tests/                   # Python unit & integration tests
└── main.py                  # FastAPI application entry point

---

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OPENROUTER_API_KEY | Yes | API key from openrouter.ai | | DO_API_KEY | No | DigitalOcean GenAI API key (fallback provider) | | OPENROUTER_MODEL | No | Primary model (default: x-ai/grok-4.1-fast) | | DEAP_AI_IMAGE_KEY | No | DeepAI image generation key | | FAUST_SECRET_KEY | No | Faust.js authentication secret |

Multi-LLM Fallback

The system automatically tries multiple models in order:

1. OpenRouter — Grok 4.1 Fast, Kimi K2, Devstral, Qwen3 Coder
2. DigitalOcean GenAI — GPT-OSS-120B, Qwen3-32B

If one model fails, the next is tried automatically. Configure providers in backend/config/settings.py.

---

Development

Running Tests

# Python unit tests
pip install -r requirements-dev.txt
pytest tests/

# E2E tests (requires running Docker stack)
cd e2e && npx playwright test

# Vue builder tests
cd builder-frontend && npm test

Local Development (without Docker)

# Python backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
echo "OPENROUTER_API_KEY=your_key" > .env
python main.py

# Vue frontend (separate terminal)
cd builder-frontend && npm install && npm run dev

---

Example Prompts

Try these to see the system in action:

• "Build a modern SaaS landing page for a project management tool with pricing tiers"
• "Create a restaurant website with an online menu, reservations, and photo gallery"
• "I have a flower shop. Build me a website with an about page, gallery, and contact form"
• "Build an e-commerce site for handmade jewelry with product categories and a blog"
• "Create a portfolio website for a UX designer with case studies and testimonials"

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Acknowledgments

• CrewAI — Multi-agent AI orchestration framework
• Faust.js — WordPress headless framework for Next.js
• OpenRouter — Unified LLM API gateway
• WPGraphQL — GraphQL API for WordPress
• Tailwind CSS — Utility-first CSS framework