Big-Link-Man/STORY_3.1_QUICKSTART.md

# Story 3.1 Quick Start Guide

## Implementation Complete!

All features for Story 3.1 have been implemented and tested. 44 tests passing.

## What You Need to Do

### 1. Run Database Migration (Dev Environment)

```sql
-- Connect to your MySQL database and run:
ALTER TABLE site_deployments MODIFY COLUMN custom_hostname VARCHAR(255) NULL;
ALTER TABLE site_deployments ADD CONSTRAINT uq_pull_zone_bcdn_hostname UNIQUE (pull_zone_bcdn_hostname);
```

Or run: `mysql -u your_user -p your_database < scripts/migrate_story_3.1.sql`

### 2. Import Existing Bunny.net Sites

Now you can import your 400+ existing bunny.net buckets (with or without custom domains):

```bash
# Dry run first to see what will be imported
uv run python main.py sync-sites --admin-user your_admin --dry-run

# Actually import
uv run python main.py sync-sites --admin-user your_admin
```

This will now import ALL bunny.net sites, including those without custom domains.

### 3. Run Tests

```bash
# Run all Story 3.1 tests
uv run pytest tests/unit/test_url_generator.py \
               tests/unit/test_site_provisioning.py \
               tests/unit/test_site_assignment.py \
               tests/unit/test_job_config_extensions.py \
               tests/integration/test_story_3_1_integration.py \
               -v
```

Expected: 44 tests passing

### 4. Use New Features

#### Example Job Config

Create a job config file using the new features:

```json
{
  "jobs": [{
    "project_id": 1,
    "tiers": {
      "tier1": {"count": 10},
      "tier2": {"count": 50}
    },
    "deployment_targets": ["www.primary.com"],
    "tier1_preferred_sites": [
      "www.premium-site.com",
      "site123.b-cdn.net"
    ],
    "auto_create_sites": true,
    "create_sites_for_keywords": [
      {"keyword": "engine repair", "count": 3}
    ]
  }]
}
```

#### In Your Code

```python
from src.generation.site_assignment import assign_sites_to_batch
from src.generation.url_generator import generate_urls_for_batch

# After content generation
assign_sites_to_batch(
    content_records=batch_articles,
    job=job,
    site_repo=site_repo,
    bunny_client=bunny_client,
    project_keyword=project.main_keyword,
    region="DE"
)

# Generate URLs
url_mappings = generate_urls_for_batch(
    content_records=batch_articles,
    site_repo=site_repo
)

# Use the URLs
for url_info in url_mappings:
    print(f"{url_info['title']}: {url_info['url']}")
```

## New Features Available

### 1. Sites Without Custom Domains
- Import and use bunny.net sites that only have `.b-cdn.net` hostnames
- No custom domain required
- Perfect for your 400+ existing buckets

### 2. Auto-Creation of Sites
- Set `auto_create_sites: true` in job config
- System creates sites automatically when pool is insufficient
- Uses project keyword in site names

### 3. Keyword-Based Site Creation
- Pre-create sites for specific keywords
- Example: `{"keyword": "engine repair", "count": 3}`
- Creates 3 sites with "engine-repair" in the name

### 4. Tier1 Preferred Sites
- Specify premium sites for tier1 articles
- Example: `"tier1_preferred_sites": ["www.premium.com"]`
- Tier1 articles assigned to these first

### 5. Smart Site Assignment
**Tier1 Priority:**
1. Preferred sites (if specified)
2. Keyword-matching sites
3. Random from pool

**Tier2+ Priority:**
1. Keyword-matching sites
2. Random from pool

### 6. URL Generation
- Automatic slug generation from titles
- Works with custom domains OR bcdn hostnames
- Format: `https://domain.com/article-slug.html`

## File Changes Summary

### Modified (6 core files):
- `src/database/models.py` - Nullable custom_hostname
- `src/database/interfaces.py` - Optional custom_hostname in interface
- `src/database/repositories.py` - New get_by_bcdn_hostname() method
- `src/templating/service.py` - Handles both hostname types
- `src/cli/commands.py` - sync-sites imports all sites
- `src/generation/job_config.py` - New config fields

### Created (3 new modules):
- `src/generation/site_provisioning.py` - Creates bunny.net sites
- `src/generation/url_generator.py` - Generates URLs and slugs
- `src/generation/site_assignment.py` - Assigns sites to articles

### Created (5 test files):
- `tests/unit/test_url_generator.py` (14 tests)
- `tests/unit/test_site_provisioning.py` (8 tests)
- `tests/unit/test_site_assignment.py` (9 tests)
- `tests/unit/test_job_config_extensions.py` (8 tests)
- `tests/integration/test_story_3_1_integration.py` (5 tests)

## Production Deployment

When you deploy to production:
1. Model changes automatically apply (SQLAlchemy creates tables correctly)
2. No special migration needed - just deploy the code
3. Run `sync-sites` to import your bunny.net infrastructure
4. Start using the new features

## Support

See `STORY_3.1_IMPLEMENTATION_SUMMARY.md` for detailed documentation.

Example job config: `jobs/example_story_3.1_full_features.json`