Content Module - Feature List

1. Feature Overview

The Content module provides section-wise CMS editing for frontend static copy/layout blocks while keeping runtime lists dynamic.

It covers:

• homepage static sections
• about page static sections
• FAQ page intro section
• legal document pages (/privacy-policy, /terms-of-service)
• product-category page static sections
• global footer static sections
• SEO linkage per page through existing seo records

It does not replace runtime data sources for:

• products list
• blog list
• FAQ list

Those remain served by existing feature APIs. Content stores only the section copy/config that wraps those runtime blocks.

2. Route Ownership and Surfaces

Swagger tags used by controllers:

• Content Pages (Admin)
• Content Pages

3. Page Coverage Matrix

4. Section Coverage Matrix

4.1 Homepage (home)

Ordered sections:

1. hero
2. top_picks
3. categories
4. heritage
5. why_us
6. faq_intro
7. blogs

4.2 About (about)

Ordered sections:

1. hero
2. quote
3. why_choose
4. story_blocks
5. faq_intro
6. blogs

4.3 Product category pages (products_*)

Ordered sections:

1. hero
2. products_header
3. blogs_header

4.4 FAQ page (faq)

Ordered sections:

1. faq_intro

4.5 Global footer (global_footer)

Ordered sections:

1. brand_block
2. quick_links
3. collections_links
4. support_links
5. featured_collections_cards
6. copyright

4.6 Legal pages (privacy_policy, terms_of_service)

Ordered sections:

1. document

5. Feature Matrix (Admin)

Notes:

• Admin GET auto-creates a page row if it does not exist yet.
• PATCH meta and PUT section also auto-create page rows.
• DELETE section does not auto-create and returns CONTENT_NOT_FOUND if page/section does not exist.

6. Feature Matrix (Public + Mobile)

Public behavior:

• returns only enabled sections (isEnabled = true)
• returns sections ordered by position ASC, then id ASC
• returns 404 CONTENT_NOT_FOUND when page row does not exist

7. Validation and Safety Rules

7.1 Page-to-section allowlist

A section can only be written if it is explicitly allowed for the target page key.

Violation result:

• HTTP 400
• errorCode: CONTENT_SECTION_KEY_INVALID

7.2 Section payload schema validation

Every section payload is validated via a central schema registry.

Violation result:

• HTTP 400
• errorCode: CONTENT_SECTION_PAYLOAD_INVALID

7.3 Tiptap-first text model

Display text fields are Tiptap JSON docs:

• must contain { type: "doc", content: [...] }
• content array must be non-empty

Technical fields remain primitive:

• href
• src
• alt
• iconKey
• booleans
• numbers

7.4 URL safety

URL fields must be either:

• absolute HTTP(S), or
• site-relative path (/...)

8. Section-Level Content Capabilities

8.1 Hero and list headers

Supports rich label/heading/description plus optional CTA and optional image slots.

8.2 Card/repeater blocks

why_us, why_choose, and story_blocks support repeaters with bounds:

• card arrays: 1..12
• story blocks: 1..10

8.3 Footer link groups

Link group sections support:

• rich title
• items[] with rich label + safe href

9. SEO Linking Features

Each content page can point to one SEO record via seoId:

• nullable FK to seo.id
• PATCH /meta validates referenced SEO exists
• response includes resolved seo object when seoId is present

Failure on invalid SEO id:

• HTTP 400
• errorCode: CONTENT_SEO_NOT_FOUND

10. Permissions and Security

Permission module is Content and provides:

• Content_CREATE
• Content_READ
• Content_UPDATE
• Content_DELETE

Current admin usage:

• Content_READ
• Content_UPDATE
• Content_DELETE

Public route is explicitly marked with @Public() and has no admin role/permission guard.

11. Ordering and Visibility Behavior

Authoring control fields:

• position (default 0)
• isEnabled (default true)

Read behavior:

• admin read includes disabled sections
• public read filters out disabled sections

12. Frontend Integration Behavior

Expected frontend behavior with this module:

• fetch page payload by page key
• merge with runtime list APIs (products/blogs/faqs)
• render section blocks in returned order
• if page missing (404 CONTENT_NOT_FOUND), fallback to hardcoded defaults

This keeps deployment safe while content is progressively authored.

13. Release/QA Checklist

• Admin page fetch auto-creates missing page row with default title.
• Public page fetch does not auto-create and returns CONTENT_NOT_FOUND for missing rows.
• Invalid page/section combination returns CONTENT_SECTION_KEY_INVALID.
• Invalid Tiptap JSON or malformed payload returns CONTENT_SECTION_PAYLOAD_INVALID.
• Invalid seoId returns CONTENT_SEO_NOT_FOUND.
• Section ordering by position is stable.
• Disabled sections are excluded from public payload.
• Mobile route parity (/api/mobile/content/pages/:pageKey) returns same contract as /api/content/pages/:pageKey.

14. Feature Flow Diagram

15. File Map

• apps/api/src/modules/content/content.contract.ts
• apps/api/src/modules/content/content-schema.registry.ts
• apps/api/src/modules/content/content.service.ts
• apps/api/src/modules/content/admin/content-admin.controller.ts
• apps/api/src/modules/content/customer/content-customer.controller.ts
• packages/db/src/schema/content/content-page.schema.ts
• packages/db/src/schema/content/content-section.schema.ts

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

---

See Also

• Backend Reference: See Content Module - Backend Documentation for DB, module composition, and validation internals.
• API Reference: See Content Module - API & Integration Guide for payload contracts and examples.