# Story 3.4: Boilerplate Site Pages - CREATED

**Status**: Specification Complete, Ready for Implementation  
**Date Created**: October 21, 2025

---

## Summary

Story 3.4 has been created to address the broken navigation menu links introduced in Story 3.3.

### The Problem

In Story 3.3, we added navigation menus to all HTML templates:
```html
<nav>
  <ul>
    <li><a href="/index.html">Home</a></li>
    <li><a href="about.html">About</a></li>
    <li><a href="privacy.html">Privacy</a></li>
    <li><a href="contact.html">Contact</a></li>
  </ul>
</nav>
```

However, we never created the `about.html`, `contact.html`, or `privacy.html` pages, resulting in broken links.

### The Solution

Story 3.4 will automatically generate these boilerplate pages for each site during batch generation.

---

## What Will Be Delivered

### 1. Three Boilerplate Pages Per Site (Heading Only)
- **About Page** (`about.html`) - `<h1>About Us</h1>` + template/navigation
- **Contact Page** (`contact.html`) - `<h1>Contact</h1>` + template/navigation
- **Privacy Policy** (`privacy.html`) - `<h1>Privacy Policy</h1>` + template/navigation

All pages have just a heading wrapped in the template structure. No other content text. User can add content manually later if desired.

### 2. Database Storage
New `site_pages` table stores pages separately from articles:
```sql
CREATE TABLE site_pages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    site_deployment_id INTEGER NOT NULL,
    page_type VARCHAR(20) NOT NULL,  -- about, contact, privacy
    content TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (site_deployment_id) REFERENCES site_deployments(id),
    UNIQUE (site_deployment_id, page_type)
);
```

### 3. Template Integration
- Pages use the same template as articles on the same site
- Professional, visually consistent with article content
- Navigation menu included (which links to these same pages)

### 4. Smart Generation
- Generated ONLY when new sites are created (not for existing sites)
- One-time backfill script for all existing imported sites
- Integrated into site creation workflow (not batch generation)

---

## Implementation Scope

### Effort Estimate
**15 story points** (reduced from 20, approximately 1.5-2 days of development)

Simplified due to empty pages - no complex content generation needed.

### Key Components

1. **Database Schema** (2 points)
   - New `SitePage` model
   - Migration script
   - Repository layer

2. **Page Content Templates** (1 point - simplified)
   - Heading-only page content
   - Returns `<h1>About Us</h1>`, `<h1>Contact</h1>`, `<h1>Privacy Policy</h1>`
   - No complex content generation

3. **Generation Logic** (2 points - simplified)
   - Generate heading-only pages for each site
   - Wrap heading in HTML template
   - Store in database

4. **Site Creation Integration** (2 points)
   - Hook into `site_provisioning.py`
   - Generate pages when new sites are created
   - Handle errors gracefully

5. **Backfill Script** (2 points)
   - CLI script to generate pages for all existing sites
   - Dry-run mode for safety
   - Progress reporting and error handling

6. **Testing** (3 points - simplified)
   - Unit tests for heading-only page generation
   - Integration tests with site creation
   - Backfill script testing
   - Template application tests

**Total: 15 story points** (reduced from 20)

---

## Integration Point

Story 3.4 hooks into site creation, not batch generation:

### One-Time Setup (Existing Sites)
```bash
# Backfill all existing imported sites (hundreds of sites)
uv run python scripts/backfill_site_pages.py \
  --username admin \
  --password yourpass \
  --template basic

# Output: Generated pages for 423 sites
```

### Ongoing (New Sites Only)
```
When creating new sites:
1. Create Storage Zone (bunny.net)
2. Create Pull Zone (bunny.net)
3. Save to database
4. ✨ Generate boilerplate pages (Story 3.4) ← NEW
5. Return site ready to use

Triggered by:
- provision-site CLI command
- auto_create_sites in job config
- create_sites_for_keywords in job config
```

### Batch Generation (Unchanged)
```
1. Generate articles (Epic 2)
2. Assign sites (Story 3.1) ← May use existing sites with pages
3. Generate URLs (Story 3.1)
4. Find tiered links (Story 3.2)
5. Inject interlinks (Story 3.3)
6. Apply templates (Story 2.4)
7. Deploy (Epic 4) ← Pages already exist on site
```

---

## Files Created

### Documentation
- `docs/stories/story-3.4-boilerplate-site-pages.md` (full specification)
- `docs/prd/epic-3-pre-deployment.md` (updated to include Story 3.4)
- `STORY_3.4_CREATED.md` (this summary)

### Implementation Files (To Be Created)
- `src/generation/page_templates.py` - Generic page content
- `src/generation/site_page_generator.py` - Page generation logic
- `src/database/models.py` - SitePage model (update)
- `scripts/migrate_add_site_pages.py` - Database migration
- `scripts/backfill_site_pages.py` - One-time backfill script
- `tests/unit/test_site_page_generator.py` - Unit tests
- `tests/integration/test_site_pages_integration.py` - Integration tests
- `tests/unit/test_backfill_script.py` - Backfill script tests

---

## Dependencies

### Requires (Already Complete)
- ✅ Story 3.1: Site assignment (need to know which sites are in use)
- ✅ Story 3.3: Navigation menus (these pages fulfill those links)
- ✅ Story 2.4: Template service (for applying HTML templates)
- ✅ Story 1.6: SiteDeployment table (for site relationships)

### Enables
- Story 4.1: Deployment (pages will be deployed along with articles)
- Complete, professional-looking sites with working navigation

---

## Example Output

### Site Structure After Story 3.4
```
https://example.com/
├── index.html                        (homepage - future/Epic 4)
├── about.html                        ← NEW (Story 3.4)
├── contact.html                      ← NEW (Story 3.4)
├── privacy.html                      ← NEW (Story 3.4)
├── how-to-fix-your-engine.html      (article)
├── engine-maintenance-tips.html     (article)
└── best-engine-oil-brands.html      (article)
```

### About Page Preview (Heading Only)
```html
<!DOCTYPE html>
<html>
<head>
    <title>About Us</title>
    <!-- Same template/styling as articles -->
</head>
<body>
    <nav>
        <ul>
            <li><a href="/index.html">Home</a></li>
            <li><a href="about.html">About</a></li>
            <li><a href="privacy.html">Privacy</a></li>
            <li><a href="contact.html">Contact</a></li>
        </ul>
    </nav>
    
    <main>
        <h1>About Us</h1>
        <!-- No other content - user can add manually later if desired -->
    </main>
</body>
</html>
```

**Why heading-only pages?**
- Fixes broken navigation links (no 404 errors)
- Better UX than completely blank (user sees page title)
- Minimal implementation effort
- User can customize specific sites later if needed
- Deployment ready as-is

---

## Next Steps

### Option 1: Implement Now
- Start implementation of Story 3.4
- Fixes broken navigation links
- Makes sites look complete and professional

### Option 2: Defer to Later
- Add to backlog/technical debt
- Focus on Epic 4 deployment first
- Sites work but have broken nav links temporarily

### Option 3: Minimal Quick Fix
- Create simple placeholder pages without full story implementation
- Just enough to avoid 404 errors
- Come back later for full implementation

---

## Recommendation

**Implement Story 3.4 before Epic 4 deployment** because:

1. Sites look unprofessional with broken nav links
2. Fixes 404 errors on every deployed site
3. Only 15 story points (1.5-2 days) - simplified implementation
4. Empty pages are deployment-ready
5. User can add content to specific pages later if desired

The alternative is to deploy with broken links and fix later, but that creates technical debt and poor user experience.

**Simplified approach:** Pages have heading only (e.g., `<h1>About Us</h1>`), no body content. This makes implementation faster while still fixing the broken link issue and providing better UX than completely blank pages.

---

**Created by**: AI Code Assistant  
**Created on**: October 21, 2025  
**Next**: Decide when to implement Story 3.4 (now vs. later vs. minimal fix)