Skip to content
WAWCD Docs

Overview

Overview

Section titled “Overview”

  • What the feature does

    • Persists and exposes per-user AI Chatbot settings (AiChatbot) and operating schedules (AiOperatingSchedule).
    • Provides authenticated REST endpoints to:
      • create/read/update/delete the current user’s chatbot settings
      • add/list/update/delete operating schedules
    • Auto-attaches a user’s GptPrompt (if one exists) to the chatbot settings record.
    • Stores optional “enhancement” configuration via WorkflowEnhancement linked 1:1 to the chatbot.

  • Why it exists (business purpose)

    • Lets customers control AI automation behavior safely:
      • turn the chatbot on/off
      • restrict when it is allowed to run (operating hours)
      • configure model choice and max message limits
    • Centralizes configuration so downstream AI execution can read a single source of truth for a user.

  • Who uses it

    • Product managers: define supported configuration knobs (toggles, scheduling behavior, limits).
    • Developers: implement UI and backend integrations against stable endpoints/contracts.
    • Software architects: reason about dependencies, lifecycle, and failure modes when changing AI runtime behavior.

Key Concepts

Section titled “Key Concepts”

  • AiChatbot (settings record)

    • Entity: src/ai-chatbot/entities/ai-chatbot.entity.ts
    • Constraint: one row per user enforced via @Unique(['user']).
    • Key fields:
      • modelType?: ModelType (src/constants)
      • isChatbotOn: boolean
      • isOperatingHour: boolean
      • chatMaxMessages?: number | null
      • optional relations: prompt, chatbotEnhancement, operatingSchedule

  • AiOperatingSchedule (operating hours entries)

    • Entity: src/ai-chatbot/entities/ai-operating-schedule.entity.ts
    • Key fields:
      • day: number (stored as float in entity; DTOs treat it as int)
      • startHour: string, endHour: string (service expects HH:mm)
      • timezone: string (IANA timezone, e.g. America/New_York)
    • Rule: no overlapping schedules for the same day (validated in service).

  • Enhancement

    • Entity: WorkflowEnhancement (src/workflow-enhancements/entities/workflow-enhancement.entity.ts)
    • Input type used here: CreateWorkflowEnhancementInput imported by CreateAiChatbotDto.
    • Special handling: is_new_template is treated like a relation id in the service ({ id: ... } as any).

  • Prompt

    • Entity: GptPrompt (src/gpt-prompt/entities/gpt-prompt.entity.ts)
    • Selection behavior: the service automatically attaches a prompt for the user if one exists.

System Context

Section titled “System Context”

  • Module boundary

    • Module: src/ai-chatbot/ai-chatbot.module.ts
    • Controller: src/ai-chatbot/ai-chatbot.controller.ts
    • Service: src/ai-chatbot/ai-chatbot.service.ts

  • Dependencies

    • Auth: JwtAuthGuard (src/common/auth/jwt-auth.guard.ts) and getUserId(req) (src/utils/shared.utils.ts)
    • Persistence: TypeORM repositories for AiChatbot, AiOperatingSchedule, WorkflowEnhancement, GptPrompt
    • Timezone operations: date-fns-tz functions formatInTimeZone, fromZonedTime in schedule validation

High-Level Flow

Section titled “High-Level Flow”
  1. Client calls an endpoint under AiChatbotController (/ai-chatbot/...).
  2. JwtAuthGuard authenticates; getUserId(req) resolves userId.
  3. Controller delegates to AiChatbotService.
  4. Service loads and mutates state in the DB:
    • settings (AiChatbot)
    • enhancement (WorkflowEnhancement) if provided
    • schedules (AiOperatingSchedule) with overlap validation
    • prompt link (GptPrompt) if present
  5. Response returns the updated settings or schedule data.

Business Flows

Section titled “Business Flows”

Happy path

Section titled “Happy path”

  • Create chatbot settings

    • User saves initial settings with optional enhancement and schedules.
    • Service saves settings, then schedules, and returns settings with relations via findByUser.

  • Update chatbot settings

    • User changes toggles/model/limits and optionally updates enhancement and schedules.
    • Service validates schedule changes, saves updates, returns settings with relations.

  • Manage operating schedules

    • User adds a batch of schedules, lists schedules, edits one schedule, or deletes one.
    • Service enforces ownership and overlap rules and persists changes.

Alternate paths

Section titled “Alternate paths”

  • No prompt exists

    • Settings are still saved; prompt stays unset.

  • No enhancement

    • Settings are saved without chatbotEnhancement.

  • No schedules

    • Settings are saved with no schedules; schedule endpoints return an empty list (or NOT_FOUND if chatbot is missing).

Failure scenarios

Section titled “Failure scenarios”

  • Update settings before creation

    • PATCH /ai-chatbot fails with BAD_REQUEST (“Chatbot must be created first”).

  • Schedule validation failures

    • Start time equals end time → BAD_REQUEST.
    • End time is not after start time (in timezone) → BAD_REQUEST.
    • Overlaps another schedule on the same day → BAD_REQUEST.

  • Unauthorized schedule access

    • Fetching/updating a schedule not owned by the user → FORBIDDEN.