Advanced FAQ

The qoliber Advanced FAQ is a premium, contextual FAQ and knowledge-base suite for Magento 2 / Adobe Commerce / Mage-OS. Merchants build a structured knowledge base — topics, tags, FAQ items, and full FAQ landing pages — and surface the right answers in the right place: a dedicated FAQ hub, topic hubs, optional per-FAQ SEO detail pages, the product page, the category page, and re-usable widgets.

The storefront works on both the default Luma theme and Hyvä (via the optional Qoliber_AdvancedFaqHyva module), and the same content is exposed over REST and GraphQL.

Value proposition

• Author once, reuse everywhere. A single content model (Topics, Tags, FAQ items, FAQ Pages) feeds every storefront surface, the API, and the structured data — no duplicated copy across product, category, and CMS.
• Contextual answers. FAQs follow the catalog: assign directly, inherit from categories, group by topic/tag, or auto-assign with catalog-rule conditions.
• Discoverable content. Clean URLs, breadcrumbs, canonicals, XML sitemap inclusion, and standards-compliant FAQPage structured data built for answer-engine / generative-engine discoverability.
• Built to extend. A lean core with optional satellites (GraphQL, REST, Hyvä, rules, OpenSearch, AI) that each override a graceful extension point and degrade cleanly when absent.

Features

Content administration

• FAQ items — question, short WYSIWYG answer, optional long-form full_answer for detail pages, url_key, featured flag, and an opt-in has_detail_page flag.
• Topics — grouped FAQ collections with an identifier used in topic-hub URLs.
• Tags — cross-cutting labels for filtering and reuse.
• FAQ Pages — standalone knowledge-base landing pages built from topics.
• Search Insights — admin report of storefront search terms, including a no-results "content gaps" report.
• Full grids with inline edit, mass enable / disable / delete, and store-view scoping.

Storefront surfaces

• /faq hub — search box, topic sidebar navigation, and FAQ listing.
• Topic hubs — /faq/<topic-identifier>.
• Per-FAQ SEO detail pages — opt-in /faq/<topic-identifier>/<url-key> (only when the FAQ has has_detail_page enabled), rendering the long-form answer.
• Product page FAQ tab — contextual FAQs on the PDP, with a configurable max-items cap.
• Category FAQ block — FAQs on category pages, positioned above or below content.
• FAQ Block widget — drop FAQs anywhere (CMS / layout / Page Builder) from a topic, hand-picked items, or featured items.
• Top-navigation FAQ link — optional menu entry on Luma and Hyvä.

Assignment

• Direct product assignment.
• Category-inherited assignment (a product shows FAQs assigned to its categories).
• Topic / tag based grouping.
• Rule-based auto-assignment via Magento catalog-rule conditions (Qoliber_AdvancedFaqRule).

Search

• OpenSearch (Qoliber_AdvancedFaqSearch) with an edge-ngram analyzer for prefix / as-you-type matching, plus no-results capture feeding the admin content-gaps report.
• MySQL fallback built into the core so search works with no extra infrastructure.
• Real-time indexing on FAQ save / delete and on topic/tag assignment changes.

AI authoring (optional)

• With Qoliber_AdvancedFaqAi + Qoliber_Ai, editors generate a draft answer from a question (admin "Generate with AI" button and a console command). Drafts are always editable, and the feature degrades gracefully when no provider is configured.

APIs and internationalization

• REST (Qoliber_AdvancedFaqWebapi) and GraphQL (Qoliber_AdvancedFaqGraphQl) for topics, topic items, and product/category context.
• Per-store-view content overrides with fallback, consistently applied across storefront, REST, and GraphQL.

SEO / AEO structured data

• Clean, human-readable URLs with canonicals and breadcrumbs.
• XML sitemap inclusion via a sitemap ItemProvider.
• Toggleable FAQPage JSON-LD — schema.org-valid, machine-readable structured data for answer-engine / generative-engine optimization (AEO/GEO) and content discoverability by crawlers and AI assistants.

Themes and CSP

• The frontend uses native <details> accordions and is CSP-safe on both Luma and Hyvä — no inline-script reliance.

Module map

The suite is a lean core plus a set of optional satellites. The core has no hard dependency on any satellite; each optional module overrides a graceful extension point and degrades cleanly when absent.

Module	Package	Role
Qoliber_AdvancedFaq	qoliber/advanced-faq	Core: content models, repositories, admin grids, storefront, widget, REST contracts, MySQL search, JSON-LD, sitemap.
Qoliber_AdvancedFaqWebapi	qoliber/advanced-faq-webapi	REST endpoints.
Qoliber_AdvancedFaqGraphQl	qoliber/advanced-faq-graphql	GraphQL queries.
Qoliber_AdvancedFaqHyva	qoliber/advanced-faq-hyva	CSP-safe Tailwind storefront templates for Hyvä.
Qoliber_AdvancedFaqRule	qoliber/advanced-faq-rule	Rule-based auto-assignment via catalog-rule conditions.
Qoliber_AdvancedFaqSearch	qoliber/advanced-faq-search	OpenSearch provider + real-time indexing + reindex command.
Qoliber_AdvancedFaqAi	qoliber/advanced-faq-ai	AI draft-answer generation.
Qoliber_Ai	qoliber/ai	Shared, provider-agnostic AI abstraction (Claude / ChatGPT / Gemini / Grok).

The core ships safe default implementations and lets satellites override them via DI preferences:

• SearchProviderInterface — core uses a MySQL provider; AdvancedFaqSearch swaps in OpenSearch.
• AnswerGeneratorInterface — core ships a null generator; AdvancedFaqAi swaps in a real one.
• RuleMatcherInterface — core ships a null matcher; AdvancedFaqRule swaps in a catalog-rule-condition matcher.

Requirements

Requirement	Version
Magento / Adobe Commerce / Mage-OS	2.4.x (with magento/framework)
PHP	8.1+ (8.1 / 8.2 / 8.3 / 8.4 / 8.5)
Composer	2.x
OpenSearch	Required only for Qoliber_AdvancedFaqSearch
Hyvä	Required only for Qoliber_AdvancedFaqHyva

Next steps

• Installation — Composer install and module enablement
• Configuration — Admin settings
• Usage — Authoring and storefront workflows
• AI answer generation — Configure and use AI drafting
• API — REST and GraphQL
• Developer notes — Architecture and extension points
• Roadmap — Upcoming features