Content Module - Feature List

1. Feature Overview

Content module implements newsletter publishing with two access levels:

• public preview for published items
• entitled full access via active subscription tiers (newsletter.basic, newsletter.premium)

The module is split into leaf API surfaces for:

• content series
• content items
• featured content

2. Route Ownership and Surfaces

3. Admin Feature Matrix

4. Customer/Mobile Feature Matrix

Mobile equivalents are available under /api/mobile/content/....

5. Key Business Rules

• Content type is currently constrained to newsletter (content_type enum).
• Tier requirement is resolved from newsletter_content_tier with item-level rule taking precedence over series-level rule.
• basic access can be satisfied by basic or premium; premium requires premium.
• featured_content is a separate model; newsletter pinning is not read from content_item.isPinned.
• Featured date windows are DB validated: start_date <= end_date when both are present.
• Slug-history fallback is used for backward-compatible series/item URL lookups.

6. State Models

6.1 Newsletter item status model

Additional runtime constraints:

• published with a future scheduledAt is rejected (CONTENT_STATUS_INVALID).
• archived content cannot be republished (CONTENT_ARCHIVED_NOT_PUBLISHABLE).

6.2 Entitlement state model

no tier rule -> preview/free content tier rule (basic|premium) + active user_feature_access_window -> full access missing entitlement -> CONTENT_ACCESS_DENIED

7. Caching Strategy

Content customer keyspaces:

• content:customer:items:list:
• content:customer:item:slug:
• content:customer:library:
• content:customer:subscriptions:
• content:customer:series:list:
• content:customer:series:slug:

Featured keyspaces:

• content:featured:admin:list:
• content:featured:customer:active:
• content:featured:customer:all:

Implementation notes:

• deterministic keys via CacheKeyUtil.build(...)
• invalidation via invalidatePattern(prefix*) after admin writes
• Redis read/write failures degrade gracefully to DB reads with warning logs

8. Rate Limiting

Content rate-limit envs:

• CONTENT_ADMIN_RATE_LIMIT
• CONTENT_ADMIN_RATE_WINDOW_SECONDS
• CONTENT_CUSTOMER_ITEM_RATE_LIMIT
• CONTENT_CUSTOMER_ITEM_RATE_WINDOW_SECONDS
• CONTENT_CUSTOMER_SERIES_RATE_LIMIT
• CONTENT_CUSTOMER_SERIES_SEARCH_RATE_LIMIT
• CONTENT_CUSTOMER_SERIES_RATE_WINDOW_SECONDS

Operational behavior:

• Redis sorted-set sliding windows keyed per client/user and endpoint class
• request identifiers use UUIDv7
• threshold breach throws RateLimitExceededException with RATE_LIMIT_EXCEEDED

9. Queue/Worker Features

Content module triggers newsletter delivery jobs:

9.1 Newsletter Email Delivery

9.2 Newsletter Push Delivery

10. Error UX Mapping

11. Newsletter Features

• subscription-based entitlement model (not product_access)
• admin tier assignment for series/items (basic or premium)
• subscriber listing with tier filter (all, basic, premium)
• email and push delivery endpoints for newsletter broadcasts

Flow diagram:

12. Integration Flows

12.1 Newsletter Publishing Flow

An admin creates and sends a newsletter to subscribers.

1. Admin calls POST /api/admin/content-series to create a series with tier configuration.
2. Admin calls POST /api/admin/content-items to create a newsletter item linked to the series.
3. Admin calls POST /api/admin/content-items/:id/publish to publish the newsletter.
4. (Optional) Admin calls POST /api/admin/content-items/:id/send-email to email subscribers or send-push for push notifications.
5. System enqueues newsletter delivery job to QueueName.NOTIFICATIONS.

12.2 Subscriber Access Flow

A customer accesses full newsletter content via subscription entitlement.

1. Customer browses public newsletter list via GET /api/content/items.
2. Customer clicks a newsletter, triggering GET /api/content/items/:slug which returns preview content.
3. Customer calls GET /api/content/items/:slug/full with JWT.
4. System checks newsletter_content_tier for item-level or series-level requirement.
5. System resolves active tiers from user_feature_access_window.
6. If entitled, system returns full content; if not, returns CONTENT_ACCESS_DENIED with subscribe CTA.

12.3 Featured Newsletter Flow

An admin promotes a newsletter via featured placement.

1. Admin calls POST /api/admin/content-featured with newsletter item ID and date window.
2. Admin calls POST /api/admin/content-featured/reorder to adjust display priority.
3. Customer calls GET /api/content/items/featured to see active featured newsletters.
4. Customer calls GET /api/content/items/featured/all for paginated featured list.

---

13. Release/QA Checklist

• Admin series/item/featured routes resolve and enforce respective permission codes.
• Publish/unpublish and scheduling constraints enforce status invariants.
• Tier assignment works at item and series level with item-first precedence.
• Preview is public and full content stays JWT + entitlement protected.
• Featured date-window validation rejects invalid ranges.
• Series/item slug-history fallback resolves legacy slugs.
• Customer and featured cache keyspaces invalidate correctly on admin mutations.
• Content and series customer endpoints enforce configured rate windows.

Time fields in this module are stored as timezone-aware values and should be handled as ISO-8601 instants by API consumers.

---

See Also

• API Reference: See Content - API & Integration Guide Section 11 (Endpoint Reference + Payload Cheatsheet) for complete request/response DTOs.
• Backend Reference: See Content - Backend Documentation Section 3 (Data Model) for schema details.