TutorialGeneratorService

Kind: Service

Source: atloria-monorepo/apps/api/src/documentation/services/tutorial-generator.service.ts

Tutorial Generator Service

Generates beginner-friendly tutorial content using AI. Each tutorial teaches a single state transition (2-5 minutes).

Leverages Phase 2.1 & 3 context:

• State machines → explain state changes
• UI interactions → use exact button labels
• Screenshots → reference visuals

Multi-agent approach:

• Generator (Claude): Creates initial content
• Reviewer (OpenAI): Reviews for clarity and beginner-friendliness

TutorialGeneratorService is a NestJS backend service that generates short, beginner-friendly tutorials (2–5 minutes) that each teach a single state transition in the product. It builds tutorials using app context (state machine transitions, exact UI button labels, and referenced screenshots) and improves quality via a multi-agent pipeline where one model generates and another reviews for clarity and approachability.

Methods

  generatorProvider?: 'azure-claude' | 'azure-openai';
  reviewerProvider?: 'azure-claude' | 'azure-openai';
  enableReviewer?: boolean;
})` | `Promise<TutorialContent>` | Generate tutorial content from detected tutorial |

Dependencies

• AzureClaudeProvider
• AzureOpenAIProvider

Where it refuses work

• TutorialGeneratorService stops the work with an early return when !tutorial.stateFlow.
• TutorialGeneratorService stops the work with an early return when !tutorial.uiInteractions || tutorial.uiInteractions.length === 0.
• TutorialGeneratorService stops the work with an early return when !tutorial.formFields || tutorial.formFields.length === 0.
• TutorialGeneratorService stops the work with an early return when !tutorial.screenshots || tutorial.screenshots.length === 0.

When something fails

• TutorialGeneratorService handles failure in 2 places: it turns it into a return value in 1, and lets it reach the caller in 1.

Diagram

mermaid
sequenceDiagram
  autonumber
  participant Caller as API/Controller
  participant TGS as TutorialGeneratorService
  participant Ctx as Context Builder<br/>(Phase 2.1/3)
  participant Gen as Generator Agent<br/>(Claude)
  participant Rev as Reviewer Agent<br/>(OpenAI)
  participant Store as Output/DB/Filesystem

  Caller->>TGS: generateTutorial(request)
  TGS->>Ctx: collect state machine + UI labels + screenshots
  Ctx-->>TGS: tutorial context package
  TGS->>Gen: create draft tutorial(context)
  Gen-->>TGS: draft tutorial content
  TGS->>Rev: review & refine(draft, context)
  Rev-->>TGS: approved/refined tutorial
  TGS->>Store: persist/return tutorial
  Store-->>Caller: tutorial result

Usage

ts
import { Injectable } from '@nestjs/common';
import { TutorialGeneratorService } from './documentation/services/tutorial-generator.service';

@Injectable()
export class TutorialsControllerFacade {
  constructor(private readonly tutorialGenerator: TutorialGeneratorService) {}

  async generateBeginnerTutorial() {
    // Example request shape (adjust to your actual DTO/interface)
    const request = {
      // The single transition the tutorial should teach
      transition: {
        fromState: 'Draft',
        toState: 'Published',
        event: 'PUBLISH_CLICKED',
      },
      // UI constraints: exact button label(s) to reference
      ui: {
        primaryActionLabel: 'Publish',
        confirmActionLabel: 'Confirm publish',
      },
      // Optional: screenshot identifiers/URLs to reference in steps
      screenshots: [
        { id: 'editor-toolbar', description: 'Toolbar with Publish button' },
        { id: 'publish-confirmation', description: 'Publish confirmation modal' },
      ],
      audience: 'beginner',
      targetDurationMinutes: 3,
    };

    // Returns a tutorial artifact (e.g., markdown/steps + metadata)
    return this.tutorialGenerator.generateTutorial(request);
  }
}

AI Coding Instructions

• Keep tutorials scoped to one state transition only; do not combine multiple transitions or “advanced” detours even if context includes them.
• When describing UI actions, use exact button labels from context (case-sensitive) and avoid inventing UI text; reference screenshots by their provided IDs/descriptions.
• Preserve the multi-agent flow: generator produces a draft, reviewer refines for beginner clarity; avoid bypassing review unless explicitly configured.
• Ensure the output stays within 2–5 minutes and is step-based with clear “what to click” instructions tied to the state change being taught.
• When adding new context fields (state machine/UI/screenshot metadata), thread them through both generator and reviewer prompts to prevent hallucinated steps.

Relationships

• DEPENDS_ON → AzureClaudeProvider
• DEPENDS_ON → AzureOpenAIProvider

Referenced By

• DocumentationModule (MODULE_PROVIDES)
• DocumentationModule (MODULE_EXPORTS)