Etechflow_Faq — Help-Centre / FAQ Module for Magento 2

A self-contained FAQ / knowledge-base module with public detail pages,
admin management, REST API, and full theme/branding configurability.
Works on Magento Open Source, Adobe Commerce, with Hyvä or
Luma themes — no Tailwind, no Alpine, no PageBuilder dependencies.

┌─────────────────────────────────────────────────────────────┐
│   Help Centre & FAQs                                        │
│                                                             │
│   [Search articles...] [Search]                             │
│                                                             │
│   ┌──────────┐ ┌──────────┐ ┌──────────┐                    │
│   │ ORDERS   │ │ RETURNS  │ │ DELIVERY │   …                │
│   │ ▸ q1     │ │ ▸ q1     │ │ ▸ q1     │                    │
│   │ ▸ q2     │ │ ▸ q2     │ │ ▸ q2     │                    │
│   └──────────┘ └──────────┘ └──────────┘                    │
└─────────────────────────────────────────────────────────────┘

/faqs                            → listing of all categories
/faqs/orders/can-i-return-x      → detail page with related articles
/rest/V1/etechflow/faq          → REST: all categories with items

Features

• Categories with display label, URL identifier, icon, sort order, active toggle.
• Q&A items with auto-generated slugs (unique per category), subtitle, rich answer body, SEO meta title + description.
• Slug-based detail pages at /faqs/{category}/{slug} — breadcrumb, left-rail category navigation, main content card, right-rail (search/helpful/contact), related articles grid.
• Listing page at /faqs — categories grid (desktop) + mobile accordion, in-page search filter, per-category modal showing all questions.
• REST API — three read-only public endpoints returning JSON, no auth required.
• System Configuration for branding (colours, font), hero (image + copy), contact details, and display toggles — no template hacking needed.
• Theme-agnostic — vanilla CSS scoped under .kfaq-*, vanilla JS (no framework). Renders identically on Hyvä and Luma.
• Demo data (opt-in) seeds 9 categories + 36 sample questions for a working out-of-the-box page.

Requirements

Quick start

Manual install (no Composer)

cd <magento-root>
mkdir -p app/code/Etechflow/Faq
# unzip the package into the directory above (so registration.php sits at app/code/Etechflow/Faq/registration.php)
unzip Etechflow_Faq-v1.0.0.zip -d app/code/Etechflow/Faq

bin/magento module:enable Etechflow_Faq
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Composer install (path repository)

# In <magento-root>/composer.json add:
#   "repositories": [{ "type": "path", "url": "../Etechflow_Faq" }]
composer require etechflow/module-faq:^1.0
bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush

Verify

• Admin → Content → FAQs → Categories — lists 0 rows (or 9 if demo data enabled).
• Admin → Stores → Configuration → EtechFlow → FAQ — defaults are populated.
• Storefront → /faqs — renders the listing page.

Documentation

Module structure

app/code/Etechflow/Faq/
├── Api/                                 service contracts
│   ├── Data/{Category,Item}Interface.php
│   └── FaqRepositoryInterface.php
├── Block/                               view blocks
│   ├── Config.php                       — reads Stores → Configuration values
│   ├── Listing.php                      — /faqs landing
│   └── View.php                         — /faqs/{cat}/{slug} detail
├── Controller/
│   ├── Adminhtml/{Category,Item}/*.php  — admin CRUD
│   ├── Index/Index.php                  — /faqs route
│   ├── Router.php                       — matches /faqs/{cat}/{slug}
│   └── View/Index.php                   — detail-page controller
├── Model/                               models, resource models, source models, repository
├── Setup/Patch/Data/
│   ├── BackfillUrlKeys.php              — populates slugs for legacy rows
│   └── InstallDemoData.php              — opt-in seed (9 cats + 36 items)
├── Ui/                                  admin form/listing data providers + action columns
├── etc/                                 module config (acl, di, db_schema, system.xml, etc.)
├── view/
│   ├── adminhtml/                       admin layouts + UI components
│   └── frontend/                        layouts + templates (listing.phtml, view.phtml)
├── composer.json
├── registration.php
└── *.md, LICENSE

Support

Open an issue or reach the maintainer at the email in composer.json.

Changelog

All notable changes to Etechflow_Faq will be documented in this file. The
format is based on Keep a Changelog and
this project adheres to Semantic Versioning.

[1.0.0] — 2026-05-16

Added

• Initial public release.
• Admin: Categories CRUD (label, identifier/slug, icon, sort order, active flag).
• Admin: Q&A items CRUD (question, url_key, subtitle, answer, SEO meta, sort, active).
• Slug auto-generation on save with per-category uniqueness (-2, -3, … suffix).
• Schema-version backfill patch (BackfillUrlKeys) populates slugs for legacy rows.
• Storefront listing at /faqs — categories grid, mobile accordion, search filter,
  modal "all questions in category", contact cards, trust bar.
• Storefront detail at /faqs/{category}/{slug} — breadcrumb, left categories
  sidebar with active state, main card (eyebrow + H1 + subtitle + rich answer),
  right rail (search, helpful Y/N, contact card), related articles grid.
• Custom Controller/Router.php handles the /faqs/{cat}/{slug} URL pattern
  without colliding with the /faqs listing.
• REST API endpoints: GET /V1/etechflow/faq, GET /V1/etechflow/faq/categories,
  GET /V1/etechflow/faq/categories/:id/items.
• System Configuration section Stores → Configuration → EtechFlow → FAQ for
  branding (primary/secondary/text colors, font), hero (image + title + subtitle),
  contact (phone, email, contact-form URL, store-finder URL), and display toggles.
• CSS custom properties wired to config so any host theme can re-skin without
  forking templates.
• Optional demo-data patch (InstallDemoData, off by default) seeds 9 categories
  • 36 Q&A items for a new install.
• Composer manifest (magento2-module, MIT).
• INSTALL.md, USAGE.md, README.md, CHANGELOG.md.

Compatible with

• Magento Open Source 2.4.4 → 2.4.8
• Adobe Commerce 2.4.4 → 2.4.8
• PHP 8.1, 8.2, 8.3
• Hyvä Theme 1.3+ (no Hyvä-only code — works on Luma too)
• Luma / blank / any custom frontend theme