# Article Builder | BRIX Templates

A dynamic, multi-agent workflow system for creating comprehensive, SEO-optimized articles for Webflow and Framer platforms.

## 🚀 Features

- **10-Step Workflow**: From user input to final article generation with optional structure refinement
- **Dynamic Prompt Loading**: Prompts loaded from `.md` files in real-time
- **Smart Placeholder Replacement**: User inputs automatically inserted into prompts
- **Local Storage Persistence**: Your work is saved automatically
- **Copy to Clipboard**: One-click prompt copying for use with AI assistants
- **Optional Article Structure Step**: AI-powered first principles explanations and structure refinement
- **Responsive Design**: Works on desktop and mobile devices

## 📁 Project Structure

```
article-v2-builder/
├── assets/
│   └── favicon.svg              # Application icon
├── prompts/
│   ├── article-focus.md         # Step 1: Validate article direction
│   ├── research-topic.md        # Step 2: Gather technical facts
│   ├── community-intelligence.md # Step 3: Find user questions
│   ├── find-seo-questions.md    # Step 4: Identify SEO opportunities
│   ├── generate-article.md      # Step 6: Write final article
│   ├── diagram-designer.md      # Step 7: Create visual diagrams
│   └── featured-image.md        # Step 8: Generate featured image prompts
├── SIMPLIFICATION-EXAMPLES.md   # Step 5: Article structure planner (optional)
├── index.html                   # Main application interface
├── style.css                    # Comprehensive styling with CSS variables
├── prompts-config.js            # Step configuration and mappings
├── app.js                       # Core application logic
└── README.md                    # This file
```

## 🛠️ How It Works

### Architecture

The application uses a **3-layer architecture**:

1. **Configuration Layer** (`prompts-config.js`)
   - Defines all workflow steps
   - Maps prompts to their `.md` files
   - Specifies input dependencies and placeholders

2. **Application Layer** (`app.js`)
   - Handles tab navigation
   - Loads prompts dynamically via `fetch()`
   - Manages user input state
   - Replaces placeholders with actual data
   - Provides clipboard functionality

3. **Presentation Layer** (`index.html` + `style.css`)
   - Clean, accessible UI
   - Semantic HTML with ARIA labels
   - CSS custom properties for theming
   - Responsive grid system

### Placeholder System

Prompts use a simple placeholder format that gets replaced with user inputs:

```markdown
Article Topic: [INSERT_TOPIC]
Context: [INSERT_CONTEXT]
```

These are defined in `prompts-config.js`:

```javascript
placeholders: {
    '[INSERT_TOPIC]': 'articleTitle',
    '[INSERT_CONTEXT]': 'articleContext'
}
```

### Workflow Steps

**Step 0: User Input**
- Collect article title and optional context
- Data stored in localStorage for persistence

**Step 1: Article Focus**
- Validates article direction
- Checks for platform updates
- Identifies critical context

**Step 2: Research Topic**
- Gathers technical requirements
- Finds best practices
- Collects code examples

**Step 3: Community Intelligence**
- Searches Reddit, forums, Twitter
- Extracts real user pain points
- Identifies common questions

**Step 4: SEO Questions**
- Finds 40-50 search queries
- Classifies by search intent
- Identifies FAQ opportunities

**Step 5: Article Structure (Optional)**
- Generates technical explanations from first principles
- Creates detailed article structure with justifications
- Provides 10 suggestions for refinement
- Outputs refined prompt for article generation
- **This step is optional** - can be skipped

**Step 6: Generate Article**
- Writes comprehensive tutorial
- Integrates all research
- Optimizes for SEO
- Automatically includes Step 5 structure if provided

**Step 7: Diagram Designer**
- Creates concept-first diagrams
- Uses specific visual patterns
- Generates prompts for Claude Code and Sora

**Step 8: Featured Image**
- Generates AI image prompts
- Optimized for blog featured images
- Based on article content

**Step 9: SEO Meta Data**
- Generates optimized SEO metadata
- Meta title, description, and tags
- Based on article content

## 🚦 Getting Started

### Prerequisites

- A modern web browser (Chrome, Firefox, Safari, Edge)
- A local web server (see options below)

### Running Locally

**Option 1: Python Simple Server**
```bash
# Python 3
python -m http.server 8000

# Python 2
python -m SimpleHTTPServer 8000
```

**Option 2: Node.js http-server**
```bash
npx http-server -p 8000
```

**Option 3: PHP Built-in Server**
```bash
php -S localhost:8000
```

**Option 4: VS Code Live Server**
- Install "Live Server" extension
- Right-click `index.html` → "Open with Live Server"

Then open: `http://localhost:8000`

### Why a Web Server?

Modern browsers block `file://` protocol from loading external files (CORS policy). A web server is required to:
- Fetch `.md` prompt files dynamically
- Enable localStorage functionality
- Allow clipboard API access

## 🎨 Customization

### Adding New Steps

1. **Create prompt file**: `prompts/new-step.md`

2. **Update configuration**:
```javascript
// prompts-config.js
7: {
    id: 'new-step',
    title: 'New Step',
    icon: 'bi-star',
    description: 'Description here',
    hasPrompt: true,
    promptFile: 'prompts/new-step.md',
    dependencies: ['articleTitle'],
    placeholders: {
        '[INSERT_TOPIC]': 'articleTitle'
    }
}
```

3. **Add HTML section**: Follow existing step pattern in `index.html`

### Customizing Styles

All styles use CSS custom properties (variables) defined in `style.css`:

```css
:root {
    --color-primary-dark: #1a1a1a;
    --font-primary: 'Figtree', sans-serif;
    --spacing-base: 12px;
    /* Change these to customize appearance */
}
```

## 🔧 Technical Details

### Browser Compatibility

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

### JavaScript Features Used

- ES6+ Classes
- Async/Await
- Fetch API
- LocalStorage API
- Clipboard API
- Template Literals
- Destructuring

### Performance

- Prompts cached after first load
- Minimal DOM manipulation
- Efficient event delegation
- Debounced input handlers

## 📝 Usage Tips

1. **Fill Step 0 first**: All other steps depend on user input
2. **Save your work**: Data persists in localStorage automatically
3. **Copy prompts**: Use with ChatGPT, Claude, or other AI assistants
4. **Sequential workflow**: Follow steps 0-9 in order for best results
5. **Step 5 is optional**: You can skip Article Structure and go directly to Generate Article
6. **Context matters**: Provide detailed context in Step 0 for better prompts

## 🐛 Troubleshooting

**Prompts not loading?**
- Ensure you're running a web server (not `file://`)
- Check browser console for errors
- Verify `.md` files exist in `prompts/` folder

**Inputs not saving?**
- Check if localStorage is enabled
- Try clearing browser cache
- Check for browser extensions blocking storage

**Copy button not working?**
- Ensure site is served over HTTPS or localhost
- Check clipboard permissions
- Try the fallback selection method

## 📄 License

MIT License - Created by [@maurosicard](https://twitter.com/maurosicard)

## 🙏 Credits

- Built for BRIX Templates
- Designed for Webflow and Framer content creation
- Uses [Bootstrap Icons](https://icons.getbootstrap.com/)
- Font: [Figtree](https://fonts.google.com/specimen/Figtree) by Google Fonts

---

**Version**: 2.0
**Last Updated**: November 2024
**Author**: Mauro Sicard
