AI Writing App - Template Engine Documentation

# AI Writing App - Template Engine Documentation

## 🎯 Overview

This template engine provides a powerful, extensible system for creating AI-powered writing projects. Each template type (E-Book, Online Course, etc.) has its own configuration that defines inputs, sections, and AI behavior.

## 📚 Table of Contents

1. [Architecture](#architecture)
2. [Implemented Templates](#implemented-templates)
3. [How It Works](#how-it-works)
4. [Adding New Templates](#adding-new-templates)
5. [AI Integration](#ai-integration)
6. [API Reference](#api-reference)
7. [Examples](#examples)

---

## 🏗️ Architecture

### Core Components

```
src/
├── types/templates.ts          # TypeScript definitions
├── config/templates/           # Template configurations
│   ├── index.ts               # Template registry
│   ├── ebook.ts              # E-Book template
│   ├── online-course.ts      # Online Course template
│   ├── how-to-guide.ts       # How-To Guide template
│   ├── story-bestseller.ts   # Story/Bestseller template
│   ├── social-media.ts       # Social Media template
│   ├── newsletter-series.ts  # Newsletter Series template
│   └── advertising.ts        # Advertising template
├── lib/ai/                     # AI integration layer
│   ├── generator.ts          # Main AI generation logic
│   └── template-interpolator.ts # Prompt variable substitution
├── hooks/
│   └── useTemplateProject.ts # Project management hook
└── components/templates/       # Template UI components
    ├── TemplateSelector.tsx   # Template chooser
    ├── DynamicForm.tsx       # Input form generator
    └── TemplateEditor.tsx    # Section-based editor
```

### Data Flow

```
1. User selects template → TemplateSelector
2. Dynamic form generated → DynamicForm (based on template.inputs)
3. Project created → useTemplateProject hook
4. Sections initialized → Based on template.sections
5. User generates content → AI integration layer
6. Content rendered → TemplateEditor
```

---

## 📝 Implemented Templates

### 1. **E-Book Template**

**Template ID**: `ebook`

**Inputs**:
- Subject/Main Topic (text, required)
- Target Audience (text, required)
- Tone & Style (select: professional, conversational, academic, inspiring, practical)
- Number of Chapters (range: 3-20, default: 8)
- Include Introduction (toggle, default: true)
- Include Conclusion (toggle, default: true)

**Structure**:
```
- Introduction (optional)
- Chapters 1-N (repeatable)
  * User defines chapter title and focus
- Conclusion (optional)
```

**Features**:
- Dynamic chapter count
- Each chapter gets individual AI generation
- Progress tracking per chapter
- Word count tracking
- Support for expand/shorten/rewrite operations

**Use Cases**:
- Business books
- Technical guides
- Self-help books
- Educational content
- Non-fiction writing

---

### 2. **Online Course Template**

**Template ID**: `online-course`

**Inputs**:
- Course Topic (text, required)
- Target Audience (text, required)
- Number of Modules (range: 3-12, default: 6)
- Lessons per Module (range: 2-8, default: 4)
- Include Exercises (toggle, default: true)
- Include Resources & Tools (toggle, default: true)

**Structure**:
```
- Module 1-N (repeatable)
  - Module Overview
  - Lessons 1-M (repeatable)
    * Lesson objectives
    * Main content
    * Key takeaways
  - Exercises (optional)
  - Resources & Tools (optional)
```

**Features**:
- Nested structure (modules → lessons)
- Automatic learning objective generation
- Exercise creation with difficulty levels
- Resource recommendations
- Progressive lesson numbering

**Use Cases**:
- Online courses
- Training programs
- Educational modules
- Certification prep
- Skill development programs

---

### 3. **How-To Guide Template**

**Template ID**: `how-to-guide`

**Inputs**:
- Guide Title (text, required)
- Target Audience (text, required)
- Number of Steps (range: 3-15, default: 7)
- Difficulty Level (select: beginner, intermediate, advanced)

**Structure**:
```
- Introduction
- Steps 1-N (repeatable)
  * Step title
  * Step description
  * Detailed instructions
- Tips & Tricks
- Conclusion & Next Steps
```

**Features**:
- Sequential step-by-step format
- Automatic sub-step generation
- Common mistake warnings
- Screenshot placeholders
- Troubleshooting advice

**Use Cases**:
- Tutorials
- DIY instructions
- Process documentation
- Installation guides
- Workflow documentation

---

### 4. **Story / Bestseller Template**

**Template ID**: `story-bestseller`

**Inputs**:
- Genre (select: fantasy, sci-fi, mystery, romance, literary, horror, historical)
- Point of View (select: first-person, third-limited, third-omniscient)
- Tense (select: past, present)
- Tone (multiselect: dark, hopeful, witty, somber, suspenseful, romantic, humorous)
- Themes (textarea)
- Reference Files (file upload, .pdf/.txt/.docx, multiple)

**Structure**:
```
- Synopsis
- Character Profiles
  * Names, descriptions, motivations
  * Character arcs
- World-Building / Setting
- Act 1: Setup (3-10 scenes)
- Act 2: Confrontation (5-15 scenes)
- Act 3: Resolution (3-10 scenes)
```

**Special Features**:
- **File Upload**: Upload reference files to learn writing style
- **Style Analysis**: AI extracts tone, voice, themes, vocabulary from references
- **Style Consistency**: All generated content matches learned style
- **Three-Act Structure**: Professional story structure
- **Character Development**: Detailed character profiles

**Use Cases**:
- Novel writing
- Short stories
- Creative fiction
- Screenplay adaptation
- Genre fiction

---

### 5. **Social Media Post Template**

**Template ID**: `social-media`

**Inputs**:
- Platform (select: Instagram, TikTok, X/Twitter, LinkedIn, Facebook, Threads)
- Subject/Main Idea (textarea, required)
- Goal (select: awareness, engagement, traffic, leads, sales, education)
- Target Audience (text, required)
- Tone (select: casual, bold, professional, playful, inspiring, educational, authentic)
- Generate A/B Variations (toggle, default: true)

**Structure**:
```
- Hook
- Body
- Call-to-Action
- A/B Test Variations (optional, 3 versions)
```

**Platform-Specific Features**:
- **Instagram**: First-line hook, visual formatting, emoji usage
- **Twitter**: Character limits, thread potential
- **LinkedIn**: Professional tone, business insights
- **TikTok**: Visual/emotional hooks, relatable content

**Features**:
- Platform-optimized formatting
- Psychological triggers
- A/B testing variations
- Engagement optimization
- Human-like (non-robotic) tone

**Use Cases**:
- Social media marketing
- Personal branding
- Product launches
- Engagement campaigns
- Content marketing

---

### 6. **Newsletter Series Template**

**Template ID**: `newsletter-series`

**Inputs**:
- Series Topic/Theme (text, required)
- Target Audience (text, required)
- Tone (select: conversational, professional, friendly, authoritative, inspiring)
- Main Call-to-Action (textarea, required)

**Structure**:
```
- Email 1: Introduction & Big Idea
  * Subject line options (3)
  * Preview text
  * Email body
- Email 2: Deep Dive
  * Subject line options
  * Preview text
  * Actionable insights
- Email 3: Case Study / Story
  * Subject line options
  * Preview text
  * Real-world example
- Email 4: Action Plan & Strong CTA
  * Subject line options
  * Preview text
  * Next steps
  * Strong CTA
  * P.S. section
```

**Features**:
- 4-part email sequence
- Multiple subject line options per email
- Preview text generation
- Scannability optimization (bullets, short paragraphs)
- Progressive value delivery
- CTA optimization

**Use Cases**:
- Email marketing campaigns
- Lead nurturing
- Product launches
- Course promotion
- List engagement

---

### 7. **Advertising Template**

**Template ID**: `advertising`

**Inputs**:
- Product/Offer (textarea, required)
- Target Audience (text, required)
- Platform (select: Meta Ads, Google Ads, YouTube Ads, TikTok Ads, LinkedIn Ads)
- Tone (select: urgent, conversational, premium, empathetic, bold, educational)
- Main Benefit/USP (textarea, required)
- Customer Pain Points (textarea)

**Structure**:
```
- Angle / Big Idea (3 unique angles)
- Headline Options (5 variations)
- Primary Text / Ad Copy
  * Hook
  * Agitate
  * Solve
  * Benefits
  * Credibility
- Supporting Bullets (Features/Benefits)
- Call-to-Action Variations (5 types)
```

**Features**:
- Platform-specific copy length
- Psychological trigger integration
- Multiple headline variations
- Benefits-first approach
- Character count optimization
- A/B testing support

**Use Cases**:
- Paid advertising campaigns
- Landing page copy
- Ad creative testing
- Conversion optimization
- Product marketing

---

## 🔧 How It Works

### 1. Template Configuration

Each template is defined in `src/config/templates/[template-name].ts`:

```typescript
export const myTemplate: TemplateConfig = {
  id: 'my-template',
  name: 'My Template',
  description: 'Description of what this template does',
  icon: '📝',
  category: 'Category Name',
  color: 'blue',
  bgGradient: 'from-blue-50 to-cyan-50',

  // User inputs shown in creation form
  inputs: [
    {
      id: 'title',
      label: 'Title',
      type: 'text',
      required: true,
    },
    // ... more inputs
  ],

  // Section structure
  sections: [
    {
      id: 'intro',
      title: 'Introduction',
      aiPromptTemplate: `Write an introduction about {{title}}...`,
    },
    // ... more sections
  ],

  // AI configuration
  aiConfig: {
    model: 'gpt-4',
    temperature: 0.7,
    maxTokens: 2000,
    systemPrompt: 'You are an expert writer...',
  },

  // UI customization
  ui: {
    editorLayout: 'sections',
    showProgress: true,
    customToolbar: ['generate', 'expand', 'shorten'],
  },
};
```

### 2. Dynamic Form Generation

The `DynamicForm` component automatically generates a form based on `template.inputs`:

```typescript
// Supports multiple input types:
- text         // Single-line text input
- textarea     // Multi-line text input
- number       // Numeric input
- select       // Dropdown selection
- multiselect  // Multiple checkboxes
- toggle       // On/off switch
- range        // Slider for numeric ranges
- file         // File upload (with optional multiple files)
```

### 3. Project Creation

When a user submits the form:

```typescript
1. Form values collected
2. Project created with unique ID
3. Sections initialized from template config
4. Repeatable sections duplicated based on count
5. Optional sections included/excluded
6. User redirected to TemplateEditor
```

### 4. Content Generation

```typescript
1. User clicks "Generate Content" for a section
2. Template's aiPromptTemplate loaded
3. Variables interpolated ({{variable}} → actual values)
4. AI generation request sent
5. Content returned and displayed
6. Section status updated
7. Project metadata recalculated
```

### 5. AI Prompt Interpolation

Templates use a simple variable syntax:

```typescript
// Simple variables
{{subject}}  → "Digital Marketing"
{{tone}}     → "professional"

// Nested properties
{{learnedStyle.voice}}  → "contemplative"

// Conditionals
{{#if platform == 'instagram'}}
  Instagram-specific instructions
{{/if}}

{{#if learnedStyle}}
  Use learned style: {{learnedStyle.tone}}
{{/if}}
```

---

## 🆕 Adding New Templates

### Step 1: Create Template Configuration

Create a new file: `src/config/templates/my-new-template.ts`

```typescript
import { TemplateConfig } from '@/types/templates';

export const myNewTemplate: TemplateConfig = {
  id: 'my-new-template',
  name: 'My New Template',
  description: 'What this template helps users create',
  icon: '🎯',
  category: 'Your Category',
  color: 'purple',
  bgGradient: 'from-purple-50 to-pink-50',

  inputs: [
    // Define user inputs here
  ],

  sections: [
    // Define content sections here
  ],

  aiConfig: {
    model: 'gpt-4',
    temperature: 0.7,
    maxTokens: 2000,
    systemPrompt: 'Your system prompt here',
  },

  ui: {
    editorLayout: 'sections',
    showProgress: true,
  },
};
```

### Step 2: Add to Type Definition

Update `src/types/templates.ts`:

```typescript
export type TemplateId =
  | 'ebook'
  | 'online-course'
  // ... existing templates
  | 'my-new-template';  // Add your template ID
```

### Step 3: Register in Template Registry

Update `src/config/templates/index.ts`:

```typescript
import { myNewTemplate } from './my-new-template';

export const TEMPLATES: Record<TemplateId, TemplateConfig> = {
  'ebook': ebookTemplate,
  // ... existing templates
  'my-new-template': myNewTemplate,  // Add your template
};
```

### Step 4: Test

1. Run the app
2. Navigate to `/templates`
3. Your new template should appear in the grid
4. Click it, fill the form, and test generation

That's it! The system handles everything else automatically.

---

## 🤖 AI Integration

### Current Implementation (Development Mode)

The current implementation uses **stub/mock** AI generation for development:

```typescript
// src/lib/ai/generator.ts
export async function generateSectionContent(request) {
  // Simulates AI with delay and mock content
  await simulateDelay(1500);
  return {
    content: generateMockContent(request),
    metadata: { model: 'gpt-4-mock', ... }
  };
}
```

### Production Implementation

To enable real AI generation:

#### Option 1: OpenAI Integration

1. **Install SDK**:
```bash
npm install openai
```

2. **Create API Route**: `src/app/api/ai/generate/route.ts`

```typescript
import { OpenAI } from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

export async function POST(req: Request) {
  const { prompt, systemPrompt, temperature, maxTokens } = await req.json();

  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [
      { role: 'system', content: systemPrompt },
      { role: 'user', content: prompt },
    ],
    temperature,
    max_tokens: maxTokens,
  });

  return Response.json({
    content: response.choices[0].message.content,
    model: response.model,
    tokensUsed: response.usage?.total_tokens,
  });
}
```

3. **Update Generator**: Uncomment production code in `src/lib/ai/generator.ts`

```typescript
export async function generateSectionContent(request) {
  const prompt = interpolateTemplate(
    request.sectionConfig.aiPromptTemplate,
    { ...request.inputs, ...request.context }
  );

  const template = getTemplate(request.templateId);

  const response = await fetch('/api/ai/generate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      prompt,
      systemPrompt: template.aiConfig.systemPrompt,
      temperature: template.aiConfig.temperature,
      maxTokens: template.aiConfig.maxTokens,
    }),
  });

  const data = await response.json();

  return {
    content: data.content,
    metadata: {
      model: data.model,
      tokensUsed: data.tokensUsed,
      generatedAt: new Date(),
    },
  };
}
```

#### Option 2: Anthropic Claude Integration

Similar to OpenAI, but using `@anthropic-ai/sdk`.

#### Option 3: Custom AI Backend

Point the API calls to your own backend service.

### File Analysis (for Story Template)

To enable reference file analysis:

1. **Create File Upload Handler**:

```typescript
// src/app/api/ai/analyze-file/route.ts
export async function POST(req: Request) {
  const formData = await req.formData();
  const file = formData.get('file') as File;

  // Extract text from file
  const text = await extractTextFromFile(file);

  // Send to AI for analysis
  const analysis = await analyzeWritingStyle(text);

  return Response.json(analysis);
}
```

2. **Update `analyzeReferenceFile`** in `generator.ts`

---

## 📚 API Reference

### `useTemplateProject` Hook

```typescript
const {
  currentProject,          // Current active project
  projects,               // All projects
  isGenerating,          // Loading state
  createProject,         // Create new project
  generateSection,       // Generate content for section
  regenerateSection,     // Regenerate with variations
  updateSectionContent,  // Manual content update
  markSectionComplete,   // Mark section as done
  generateAllSections,   // Generate all pending sections
} = useTemplateProject();
```

#### `createProject(templateId, title, inputs)`

Creates a new project from a template.

**Parameters**:
- `templateId`: Template ID (e.g., 'ebook')
- `title`: Project title
- `inputs`: Form values from DynamicForm

**Returns**: `Project` object

**Example**:
```typescript
const project = createProject('ebook', 'My Book', {
  subject: 'Digital Marketing',
  targetAudience: 'Small business owners',
  tone: 'professional',
  chapterCount: 10,
  includeIntroduction: true,
  includeConclusion: true,
});
```

#### `generateSection(sectionId)`

Generates AI content for a specific section.

**Parameters**:
- `sectionId`: Section ID

**Returns**: `Promise<AIGenerationResponse>`

**Example**:
```typescript
await generateSection('introduction');
await generateSection('chapters_0'); // First chapter
```

#### `regenerateSection(sectionId, variation?)`

Regenerates content with optional variation.

**Parameters**:
- `sectionId`: Section ID
- `variation`: 'expand' | 'shorten' | 'change-tone' (optional)

**Example**:
```typescript
await regenerateSection('chapters_0', 'expand');
```

### Template Configuration Types

```typescript
interface TemplateConfig {
  id: TemplateId;
  name: string;
  description: string;
  icon: string;
  category: string;
  color: string;
  bgGradient: string;
  inputs: TemplateInput[];
  sections: SectionConfig[];
  aiConfig: AIConfig;
  ui?: UIConfig;
}

interface TemplateInput {
  id: string;
  label: string;
  type: InputType;
  placeholder?: string;
  description?: string;
  required?: boolean;
  defaultValue?: any;
  options?: Array<{ value: string; label: string }>;
  min?: number;
  max?: number;
  accept?: string;
  multiple?: boolean;
  validation?: (value: any) => boolean | string;
}

interface SectionConfig {
  id: string;
  title: string;
  description?: string;
  optional?: boolean;
  aiPromptTemplate: string;
  fields?: TemplateInput[];
  subSections?: SectionConfig[];
  repeatable?: boolean;
  minInstances?: number;
  maxInstances?: number;
}
```

---

## 💡 Examples

### Example 1: Creating an E-Book Project

```typescript
// 1. User selects E-Book template
// 2. Fills form:
{
  subject: "The Complete Guide to React",
  targetAudience: "Intermediate JavaScript developers",
  tone: "practical",
  chapterCount: 12,
  includeIntroduction: true,
  includeConclusion: true
}

// 3. Project created with 14 sections:
- Introduction
- Chapter 1
- Chapter 2
- ... Chapter 12
- Conclusion

// 4. User generates introduction
await generateSection('introduction');

// 5. AI generates content based on template prompt:
"Write a compelling introduction for an ebook about The Complete Guide to React.
Target audience: Intermediate JavaScript developers
Tone: practical
..."
```

### Example 2: Adding a Custom Template

```typescript
// Create: src/config/templates/landing-page.ts
export const landingPageTemplate: TemplateConfig = {
  id: 'landing-page',
  name: 'Landing Page',
  description: 'High-converting landing page copy',
  icon: '🚀',
  category: 'Marketing',
  color: 'green',
  bgGradient: 'from-green-50 to-emerald-50',

  inputs: [
    {
      id: 'product',
      label: 'Product Name',
      type: 'text',
      required: true,
    },
    {
      id: 'targetAudience',
      label: 'Target Audience',
      type: 'text',
      required: true,
    },
    {
      id: 'mainBenefit',
      label: 'Main Benefit',
      type: 'textarea',
      required: true,
    },
  ],

  sections: [
    {
      id: 'hero',
      title: 'Hero Section',
      aiPromptTemplate: `Create a compelling hero section for {{product}}.
Target audience: {{targetAudience}}
Main benefit: {{mainBenefit}}

Generate:
- Headline
- Subheadline
- CTA button text`,
    },
    {
      id: 'features',
      title: 'Features Section',
      aiPromptTemplate: `List 5-7 key features for {{product}}...`,
    },
    // ... more sections
  ],

  aiConfig: {
    model: 'gpt-4',
    temperature: 0.8,
    maxTokens: 1500,
    systemPrompt: 'You are an expert landing page copywriter...',
  },

  ui: {
    editorLayout: 'sections',
    showProgress: false,
  },
};

// Add to type definition
export type TemplateId = ... | 'landing-page';

// Register in index.ts
export const TEMPLATES = {
  ...
  'landing-page': landingPageTemplate,
};

// Done! Template now available in app
```

---

## 🎯 Best Practices

### 1. Writing AI Prompts

**Good**:
```
Write a professional introduction for an ebook about {{subject}}.
Target audience: {{targetAudience}}
Tone: {{tone}}

The introduction should:
- Hook the reader immediately
- Explain what the book covers
- Set clear expectations
- Be 800-1200 words

Use engaging storytelling and concrete examples.
```

**Bad**:
```
Write an introduction about {{subject}}
```

### 2. Defining Inputs

- Always include clear labels and descriptions
- Set sensible defaults
- Use validation for required fields
- Provide helpful placeholders
- Choose appropriate input types

### 3. Section Structure

- Keep sections focused (single purpose)
- Use repeatable sections for variable content
- Leverage subsections for hierarchical content
- Make optional sections truly optional
- Provide clear section titles

### 4. Template Organization

- One template per file
- Clear, descriptive names
- Consistent category naming
- Meaningful icons
- Helpful descriptions

---

## 🐛 Troubleshooting

### Issue: Template not appearing

**Solution**: Check that:
1. Template is exported from its file
2. Template is registered in `index.ts`
3. Template ID is added to `TemplateId` type
4. No TypeScript errors

### Issue: Form validation failing

**Solution**: Check that:
1. Required fields are filled
2. Custom validation functions return correct types
3. Input types match expected values

### Issue: Content not generating

**Solution**: Check that:
1. Section has a valid `aiPromptTemplate`
2. All template variables are defined in inputs
3. AI integration is properly configured
4. No console errors during generation

---

## 📊 Performance Considerations

- **Lazy Loading**: Templates loaded on-demand
- **Code Splitting**: Each template in separate file
- **Memoization**: Form values cached
- **Optimistic Updates**: UI updates before AI completes
- **Progressive Enhancement**: Works without JavaScript for form

---

## 🔒 Security Considerations

- **Input Validation**: All user inputs validated
- **File Upload**: Restrict file types and sizes
- **API Keys**: Never expose in client code
- **Rate Limiting**: Implement on AI endpoints
- **Content Sanitization**: Sanitize all generated content

---

## 🚀 Future Enhancements

Potential improvements:

1. **Template Marketplace**: User-contributed templates
2. **Version Control**: Track template changes
3. **Collaboration**: Multi-user editing
4. **Export Formats**: PDF, DOCX, HTML export
5. **Analytics**: Track generation quality
6. **A/B Testing**: Built-in variation testing
7. **Template Inheritance**: Base templates with variations
8. **Plugin System**: Extend templates with plugins

---

## 📝 Summary

The template engine provides:

✅ **7 Production-Ready Templates**
✅ **Extensible Architecture**
✅ **Type-Safe Configuration**
✅ **Dynamic Form Generation**
✅ **AI Integration Layer**
✅ **Section-Based Editing**
✅ **Progress Tracking**
✅ **File Upload Support**
✅ **Repeatable Sections**
✅ **Conditional Logic**

**To add a new template**: Create config file → Register in index → Done!

**To enable AI**: Configure API route → Uncomment production code → Done!

The system is designed to be powerful yet simple, extensible yet maintainable.

---

**Questions?** Check the code comments or review the examples above.

**Happy Template Building!** 🎉