agentic-wordpress-app-builder

# 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.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://python.org)
[![Docker](https://img.shields.io/badge/Docker-Compose-blue.svg)](https://docs.docker.com/compose/)

---

## 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](https://openrouter.ai) (free tier available)

### 1. Clone & Configure

```bash
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

```bash
# 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, DigitalOcea

[truncated…]