# STORE.md

Documentation for the Drupal Commerce store and VibeChat site provisioning system.

## Overview

The store is a Drupal 11 e-commerce platform using Commerce 3 that sells VibeChat subscriptions. When a customer purchases a VibeChat plan (Bronze/Silver/Gold), the system automatically provisions a WordPress site and chatbot application for them.

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         Customer Checkout Flow                           │
│                                                                          │
│  Add to Cart → Checkout → Site Configuration → Payment → Order Complete │
│                              (slug/name)                                 │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      OrderPaidSubscriber                                 │
│                                                                          │
│  • Detects VibeChat product in order                                    │
│  • Reads custom slug/site_name from order item data                     │
│  • Creates ProvisioningJob entity                                       │
│  • Queues job in AdvancedQueue                                          │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      AdvancedQueue Processing                            │
│                                                                          │
│  • Cron or manual: drush advancedqueue:queue:process provisioning       │
│  • ProvisionSite job type executes Builder                              │
│  • Updates job status: queued → running → completed/failed              │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         Builder Backend                                  │
│                                                                          │
│  python run_build.py -c configs/create-site-production.json             │
│    --slug mysite                                                        │
│    --wp-domain mysite.turmansolutions.ai                                │
│    --cb-domain chat-mysite.turmansolutions.ai                           │
│    --site-name "My Awesome Site"                                        │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         Provisioned Sites                                │
│                                                                          │
│  WordPress:  https://mysite.turmansolutions.ai                          │
│  Chatbot:    https://chat-mysite.turmansolutions.ai                     │
└─────────────────────────────────────────────────────────────────────────┘
```

## Checkout Flow

### Site Configuration Pane

During checkout, customers see a "Site Configuration" pane where they choose:

1. **Site URL (required)** - The slug for their domain (e.g., `mysite` → `mysite.turmansolutions.ai`)
   - 3-20 characters
   - Lowercase letters and numbers only
   - Validated against existing provisioning jobs and the API

2. **Site Name (optional)** - A friendly name for the site
   - Defaults to the slug if not provided
   - Used as the WordPress site title

The pane only appears for orders containing VibeChat products.

### Validation

Slugs are validated in real-time:
- **Format validation**: Length 3-20, lowercase alphanumeric only
- **Local database check**: Ensures no existing provisioning job has this slug
- **API check**: Calls `GET /api/v1/site/slug-available/{slug}` to check existing sites

## Key Components

### Module: tsai_provisioning

Location: `web/modules/custom/tsai_provisioning/`

| Component | Purpose |
|-----------|---------|
| `ProvisioningJob` entity | Tracks each provisioning request |
| `OrderPaidSubscriber` | Creates jobs when orders are paid |
| `SlugGenerator` | Auto-generates slugs from username (fallback) |
| `SlugValidator` | Validates slug format and availability |
| `SiteConfiguration` pane | Checkout UI for slug/name input |
| `ProvisionSite` job type | Executes Builder to create sites |
| `/user/provisioning` | Customer status page |
| `/api/provisioning/status` | JSON API for polling |

### ProvisioningJob Entity Fields

| Field | Description |
|-------|-------------|
| `user_id` | Customer who placed the order |
| `order_id` | Commerce order reference |
| `status` | queued, running, completed, failed |
| `slug` | Unique site identifier |
| `site_name` | Friendly site name |
| `wp_domain` | WordPress domain (e.g., `mysite.turmansolutions.ai`) |
| `cb_domain` | Chatbot domain (e.g., `chat-mysite.turmansolutions.ai`) |
| `plan` | bronze, silver, gold |
| `result_message` | Success or error message |
| `build_log` | Full builder output |
| `created` | Job creation timestamp |
| `completed` | Job completion timestamp |

### Job Status Flow

```
queued → running → completed
                 ↘ failed (after 2 retries)
```

## Configuration

### settings.php

```php
// Path to the builder backend
$settings['tsai_builder_path'] = '/tsai/john/builder/backend';

// API URL for slug availability checks
$settings['tsai_api_url'] = 'http://127.0.0.1:8000';
```

### Checkout Flow Configuration

1. Go to `/admin/commerce/config/checkout-flows/default`
2. Find "Site Configuration" pane
3. Drag to "Order information" step
4. Save

## Services

Defined in `tsai_provisioning.services.yml`:

```yaml
services:
  tsai_provisioning.order_paid_subscriber:
    # Listens for ORDER_PAID events

  tsai_provisioning.slug_generator:
    # Generates unique slugs from usernames

  tsai_provisioning.slug_validator:
    # Validates slug format and availability
```

## Builder Integration

The `ProvisionSite` job type executes the builder with these arguments:

```bash
python run_build.py \
  -c configs/create-site-production.json \
  --slug {slug} \
  --wp-domain {slug}.turmansolutions.ai \
  --cb-domain chat-{slug}.turmansolutions.ai \
  --site-name "{site_name}"
```

### What the Builder Does

1. Creates MySQL database `wp_{slug}`
2. Downloads and installs WordPress
3. Installs JWT auth plugin and tsai-plugin
4. Creates web symlinks
5. Issues SSL certificate via acme.sh
6. Configures Apache vhost
7. Sets up WordPress (permalinks, categories, welcome post)
8. Registers site with FastAPI backend
9. Creates Drupal user for CMS access

## Common Commands

```bash
# Clear cache after changes
./vendor/bin/drush cr

# Run database updates
./vendor/bin/drush updb

# Process provisioning queue manually
./vendor/bin/drush advancedqueue:queue:process provisioning

# Check queue status
./vendor/bin/drush advancedqueue:queue:list

# View provisioning logs
./vendor/bin/drush watchdog:show --filter=tsai_provisioning
```

## User-Facing Pages

### /user/provisioning

Customer status page showing their provisioning jobs:
- **Queued**: "Your site is being created..."
- **Running**: Spinning indicator, "Provisioning in progress..."
- **Completed**: Links to WordPress site and Chatbot editor
- **Failed**: Error message and support contact

The page auto-polls `/api/provisioning/status` every 5 seconds.

### /admin/content/provisioning-jobs

Admin view of all provisioning jobs with full details including build logs.

## Troubleshooting

### Job stuck in "queued"

Check if cron is running or process manually:
```bash
./vendor/bin/drush advancedqueue:queue:process provisioning
```

### Job stuck in "running"

Check builder logs at `/tsai/john/builder/backend/logs/`

### "Provisioning queue missing" error

Reinstall the module or check queue config:
```bash
./vendor/bin/drush en advancedqueue
./vendor/bin/drush cim  # Import config
```

### Slug validation fails silently

Check API connectivity:
```bash
curl http://127.0.0.1:8000/api/v1/site/slug-available/testslug
```

### SSL certificate fails

- Verify DNS points to server
- Check acme.sh installation at `/root/.acme.sh/`
- Review Apache config

### Database already exists

Slug collision - check for existing `wp_{slug}` database in MySQL.

## Testing the Full Flow

1. **Add VibeChat product to cart**
2. **Proceed to checkout** - Site Configuration pane should appear
3. **Enter slug** - Validation should show green check for valid slug
4. **Complete payment** - Order marked as paid
5. **Check /user/provisioning** - Job should appear as "queued"
6. **Process queue**: `drush advancedqueue:queue:process provisioning`
7. **Verify sites** - Visit WordPress and Chatbot URLs

## Development vs Production

| Setting | Development | Production |
|---------|-------------|------------|
| `tsai_builder_path` | Local path | `/tsai/john/builder/backend` |
| `tsai_api_url` | `http://127.0.0.1:8000` | `http://127.0.0.1:8000` |
| Payment gateway | Manual/Test | Stripe |
| Queue processing | Manual drush | Cron |

## Related Documentation

- [CLAUDE.md](/CLAUDE.md) - Project overview and architecture
- [Builder configs](/builder/backend/configs/) - Build configuration files
- [tsai-plugin](/sites/tsai2/wp-content/plugins/tsai-plugin/) - WordPress plugin