# TutorialGeneratorService

**Kind:** Service

**Source:** [`atloria-monorepo/apps/api/src/documentation/services/tutorial-generator.service.ts`](https://github.com/sherkety/atloria/blob/main/atloria-monorepo/apps/api/src/documentation/services/tutorial-generator.service.ts#L72)

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

| Method | Signature | Returns | Description |
|---|---|---|---|
| `generateTutorial` | `generateTutorial(tutorial: DetectedTutorial, options: {
      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)