A sophisticated, asynchronous ebook generation engine built with Laravel. It leverages Google Gemini AI for high-quality content creation and design guidelines, while integrating seamlessly with Google Workspace for document management and delivery.

The system is designed as a Schema-Driven AI Pipeline, focusing on structured data generation and background processing.

graph TD
    Client[Client/Frontend] -- "POST /api/ebooks" --> Laravel[Laravel API]
    Laravel -- "Dispatch Job" --> RedisQ[Redis Queue]
    RedisQ -- "Execute Generation" --> Worker[Laravel Worker]
    Worker -- "JSON Schema Prompt" --> Gemini[Google Gemini AI]
    Gemini -- "Structured JSON" --> Worker
    Worker -- "Map to DTO" --> Mapper[EbookMapper]
    Worker -- "Blade Render" --> Renderer[EbookRenderer]
    Worker -- "Upload Doc" --> GoogleDrive[Google Drive/Docs]

• Laravel API: Entry point for generation requests, OAuth handling, and validation.
• Gemini AI Engine: Utilizes the Gemini API with strict JSON schemas to generate structured ebook content (chapters, outlines, and design palettes).
• Redis: Manages the job queues for long-running AI generation and file upload tasks.
• Google Workspace Integration: Automates the creation of Google Docs from rendered HTML and manages files within Google Drive.

The codebase is organized by domain-specific responsibility:

app/
├── Actions/
│   ├── Google/          # Google Drive/Docs operations (Upload, Auth)
│   ├── GenerateEbookAction.php   # Orchestrates Gemini call and DTO mapping
│   ├── GetGeminiResponseAction.php # Generic wrapper for Gemini interaction
│   └── GenerateGeminiImageAction.php # AI image generation (DALL-E/Imagen alternative)
├── DTOs/
│   ├── EbookDto.php     # User input DTO
│   └── Gemini/          # Strongly-typed structures for Gemini JSON responses
├── Http/
│   ├── Controllers/     # API Endpoints (Ebook, Google OAuth)
│   └── Requests/        # Request validation logic
├── Jobs/                # Background tasks (GenerateEbookJob, UploadDocumentJob)
├── Mappers/             # Data transformation (AI Response -> Internal DTOs)
├── Prompts/             # AI Prompt engineering and JSON Schema definitions
├── Services/
│   ├── EbookRenderer.php # Blade-based HTML rendering for ebooks
│   └── Google/          # Google Client Factory and Auth Service
└── resources/
    └── views/
        └── ebooks/      # Blade templates for ebook styling

User requests are validated and dispatched to a high-latency background queue.

sequenceDiagram
    participant U as Client
    participant C as EbookController
    participant J as GenerateEbookJob
    participant G as Gemini API

    U->>C: POST /api/ebooks
    C->>C: Validate Request
    C->>J: Dispatch(EbookDto)
    C-->>U: 202 Accepted
    J->>G: GenerateContent(Prompt + Schema)
    G-->>J: JSON Response
    J->>J: Render HTML Template
    J->>U: (Optional) Callback/SSE Update

The system converts structured AI content into native Google Docs.

sequenceDiagram
    participant J as UploadDocumentJob
    participant A as UploadFileAction
    participant D as Google Drive API

    J->>A: execute(path, filename)
    A->>D: Create File (mimeType: application/vnd.google-apps.document)
    D-->>A: Document ID
    A->>A: Clean up local temp files

1. Schema-Driven Reliability: Uses Gemini's responseSchema to ensure the AI always returns valid, parseable JSON that matches our Gemini/EbookDto structure.
2. Smart Backoff: GenerateEbookJob implements exponential backoff to handle AI rate limits and transient API failures gracefully.
3. Memory-Safe Rendering: Ebooks are rendered using Blade templates, allowing for complex layouts while maintaining low memory overhead.
4. OAuth Automation: GoogleAuthService manages token refreshing and client authentication, ensuring workers always have valid credentials for Drive uploads.

• POST /api/ebooks: Trigger a new ebook generation.
• GET /api/google/auth: Initiate Google OAuth flow.
• POST /api/ebooks/image: Generate an AI image for the ebook.

To modify the AI behavior or structure, edit app/Prompts/CreateEbookPrompt.php.

• Update build() for prompt engineering instructions.
• Update getSchema() to add new required fields (e.g., target language, reading time).

Visual layout is controlled via Blade in resources/views/ebooks/template.blade.php.