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
2. Implemented Templates
3. How It Works
4. Adding New Templates
5. AI Integration
6. API Reference
7. 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:

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:

// 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:

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

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:

// 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

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:

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:

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:

// 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:

npm install openai

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

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

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:

// 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

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:

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:

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:

await regenerateSection('chapters_0', 'expand');

Template Configuration Types

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

// 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

// 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! 🎉