Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ContentManager

Overview

ContentManager is a singleton class that provides comprehensive content management capabilities for the Rio platform. It manages dynamic content for login, onboarding, and homepage screens with schema-based validation, automatic image processing, and workflow-based approval integration.

General Purpose:

  • Dynamic Content Management: Manages content for login screens, onboarding flows, and homepage sections
  • Schema-Based Validation: Enforces content structure through predefined schemas for each content type
  • Automatic Image Processing: Detects base64 images, uploads to FileManager, and generates public URLs
  • Workflow Integration: Supports approval workflows for content creation and status changes
  • Architectural Pattern: Singleton instance with 'default' instanceId

Data Structure

State Schema

interface ContentManagerState {
  private: {
    contents: Content[]
  }
  public: {}
}

Content Structure

interface Content {
  id: string
  contentKey: ContentKey
  contentGroupKey: ContentGroupKey
  contentTitle: string            // Content title (mandatory)
  status: ContentStatus
  startDate?: string              // ISO 8601 datetime
  endDate?: string                // ISO 8601 datetime
  order?: number                  // Display order for sorting
  fields: Record<string, any>     // Schema-validated content fields
  createdBy: string
  createdAt: string
  updatedAt: string
}

Enums and Types

enum ContentStatus {
  PENDING = 'pending',
  ACTIVE = 'active',
  INACTIVE = 'inactive'
}

enum ContentGroupKey {
  LOGIN = 'login',
  ONBOARDING = 'onboarding',
  HOMEPAGE = 'homepage'
}

enum ContentKey {
  LOGIN_LOGIN = 'login_login',
  ONBOARDING_ONBOARDING = 'onboarding_onboarding',
  HOMEPAGE_HERO_BANNER = 'homepage_hero_banner',
  HOMEPAGE_TOP_SLIDER = 'homepage_top_slider',
  HOMEPAGE_BOTTOM_SLIDER = 'homepage_bottom_slider',
  HOMEPAGE_SECTION = 'homepage_section'
}

enum ContentFieldType {
  BOOLEAN = 'boolean',
  TEXT = 'text',
  NUMBER = 'number',
  RICHTEXT = 'richtext',
  IMAGE = 'image',
  DATETIME = 'datetime',
  ARRAY = 'array',
  ENUM = 'enum',
  COLOR = 'color'
}

enum ContentEvents {
  CONTENT_CREATE = 'content_create',
  CONTENT_UPDATE = 'content_update',
  CONTENT_STATUS_UPDATE = 'content_status_update'
}

Content Groups and Schemas

Content Groups organize related content types:

  • Login: Login screen backgrounds and visuals
  • Onboarding: Onboarding screen content with titles, descriptions, images
  • Homepage: Hero banners, sliders, and dynamic sections

Content Schemas define field structure for each content type:

  • Login Login: Background image field
  • Onboarding: Title, description, image, gradient color
  • Homepage Hero Banner: Image and optional description
  • Homepage Slider: Image and action URL
  • Homepage Section: Entity type, sort field, and filter configuration

Homepage Section Filter Fields: The Homepage Section content type includes comprehensive filter fields for dynamic entity queries:

  • entityType (ENUM): offer | voucher | event - Required field to specify entity type
  • sortField (ENUM): relevance | distance | newest | featured - Required sort order
  • filterOfferTypes (ENUM, multi-select): Filter by offer types (values from OfferType enum)
  • filterCategories (ENUM, multi-select): Filter by categories (dynamic values fetched from active BenefitCategory records at request time)
  • filterSubcategories (ENUM, multi-select): Filter by subcategories (dynamic values fetched from active BenefitCategory subcategories at request time)
  • filterFeaturedOnly (BOOLEAN): Show only featured offers
  • filterCreatedAtStart / filterCreatedAtEnd (DATETIME): Filter by creation date range
  • filterStartDateStart / filterStartDateEnd (DATETIME): Filter by offer start date range
  • filterViewStartDateStart / filterViewStartDateEnd (DATETIME): Filter by visibility date range

Enum Value Format: All ENUM fields return key/value pairs for UI rendering:

interface EnumKeyValue {
    key: string   // For static enums: Enum key (e.g., 'DISCOUNT')
                  // For dynamic enums: Database ID (e.g., '507f1f77bcf86cd799439011')
    value: string // For static enums: Enum value (e.g., 'discount')
                  // For dynamic enums: Display name (e.g., 'Health & Wellness')
}

Dynamic Enum Loading:

  • Category and subcategory enum values are fetched dynamically from BenefitCategory collection
  • Only active categories/subcategories are returned
  • Values are populated at request time in getContentSchemas endpoint
  • Categories include id (key) and name (value)
  • Subcategories include id (key) and name (value)

Core Functionality

Content Management

  • CRUD Operations: Create, read, update content with comprehensive validation
  • Status Management: Control content lifecycle (pending, active, inactive)
  • Date-Based Publishing: Support for start/end dates to control content visibility
  • Order Management: Optional ordering for content display sequences
  • Filtering: Filter content by group, key, or status

Image Processing

  • Automatic Detection: Identifies base64-encoded images in content fields
  • FileManager Integration: Uploads images to FileManager with systematic naming
  • Public URL Generation: Enhances responses with public image URLs in nested images object
  • Format Support: JPEG, PNG, GIF, WebP with MIME type validation
  • Filename Management: Generates unique filenames for uploaded images

Schema-Based Validation

  • Field Validation: Validates content fields against contentKey-specific Zod schemas
  • Type Safety: Ensures field types match schema definitions
  • Group Constraints: Validates contentKey is allowed in specified contentGroupKey
  • Date Validation: Ensures startDate is before endDate when both provided
  • Required Fields: Enforces mandatory fields based on content type

Metadata Operations

  • Content Group Definitions: Provides metadata about available content groups
  • Schema Definitions: Returns field definitions for UI rendering (type, label, validation rules)
  • Public Access: Metadata endpoints accessible without authentication
  • UI Support: Field metadata includes placeholders, validation rules, and optional flags

Workflow Integration

ContentManager extends WorkflowCompatibleStateManager to support approval workflows:

  • Status Transitions: Workflow rules can control status changes between pending, active, and inactive
  • Events: Three workflow events trigger processing:
    • CONTENT_CREATE: Fired when new content is created
    • CONTENT_UPDATE: Fired when content fields are updated
    • CONTENT_STATUS_UPDATE: Fired when content status changes
  • Approval Integration: Works with ApprovalManager for multi-step approval processes
  • Business Rules: Workflow configuration defines allowed transitions and approval requirements

API Methods

Content CRUD Operations

  • createContent (WRITE) - Create new content with automatic image processing

    • Validates contentKey is allowed in contentGroupKey
    • Processes base64 images and uploads to FileManager
    • Validates fields against contentKey schema
    • Executes workflow for approval processing
    • Returns created content ID

  • updateContent (WRITE) - Update existing content with optional image processing

    • All fields optional except ID
    • Processes new base64 images if provided
    • Validates updated fields against schema
    • Executes workflow for approval processing
    • Returns updated content ID

  • updateContentStatus (WRITE) - Update content status

    • Changes status between pending, active, inactive
    • Executes workflow for approval processing
    • Returns updated content ID

  • getContent (READ) - Retrieve single content by ID

    • Returns content with enhanced image URLs
    • Images accessible via nested fields.images object
    • Public URLs generated via FileManager

  • getContents (READ) - List active contents with filtering (client access)

    • Only returns contents with status 'active'
    • Filter by contentGroupKeys or contentKeys (query string parameters)
    • Three-tier sorting: 1) Schema order (descending), 2) Content order (descending), 3) updatedAt (descending)
    • All images enhanced with public URLs
    • Returns simplified content objects with id, contentKey, contentGroupKey, status, order, fields
    • Accessible by all user identities

  • getContentsForBackoffice (READ) - List all contents with filtering (backoffice access)

    • Returns contents with any status (pending, active, inactive)
    • Filter by contentGroupKeys, contentKeys, or statuses (body parameters)
    • Sorted by order (descending) then updatedAt (descending)
    • All images enhanced with public URLs
    • Returns full content objects
    • Only accessible by program_management_user

Metadata Operations

  • getContentGroup (READ) - Get content group definition

    • Returns group metadata including allowed content keys
    • No authentication required

  • listContentGroups (READ) - List all content group definitions

    • Returns all available content groups
    • No authentication required

  • getContentSchemas (READ) - Get content schema definitions

    • Returns field metadata for UI rendering
    • Filter by contentGroupKey or contentKey
    • Includes field types, labels, validation rules, placeholders
    • ENUM fields return key/value pairs with enumValues: [{ key, value }]
    • Multi-select ENUMs indicated by isMultiSelect: true field property
    • Dynamic enums (filterCategories, filterSubcategories) fetched from active BenefitCategory records at request time
    • Static enums (entityType, sortField, filterOfferTypes) use enum-to-key-value conversion
    • No authentication required

Approval Operations

  • approveContent (QUEUED_WRITE) - Approve content changes
    • Called internally by ApprovalManager
    • Updates content status based on approval record
    • Only accessible by ApprovalManager class

Method Types:

  • WRITE - Sync state mutation (1-30s)
  • READ - Sync state access (1-30s)
  • QUEUED_WRITE - Async state mutation (1-890s)

Key Features

  1. Architecture Pattern: Singleton class with 'default' instanceId for centralized content management across all content types
  2. Integration Points: Deep integration with FileManager for image storage, WorkflowExecuter for approval flows, and ApprovalManager for status change approvals
  3. Workflow Support: Full workflow integration with status-based approval rules, supports content creation, update, and status change events
  4. Schema-Based Validation: Comprehensive Zod schema validation for each content type, ensures data integrity and type safety
  5. Image Processing: Automatic base64 detection, FileManager upload integration, public URL generation
  6. Data Management: ContentManagerStateManager for state operations, supports filtering, sorting, pagination, and date-based content visibility
  7. Metadata System: Public endpoints for content group and schema definitions, supports dynamic UI generation based on field metadata, dynamic enum loading for categories/subcategories from BenefitCategory
  8. Security Features: Role-based authorization for CRUD operations, public access for metadata endpoints, ApprovalManager-only access for approval methods
  9. Audit/Logging: Complete content lifecycle tracking with createdBy, createdAt, updatedAt timestamps, and LogManager integration
  10. Content Organization: Three-tier structure (ContentGroup → ContentKey → Fields) with validation at each level, supports multiple content types per group