Knowledge Base
The Knowledge Base is ERPat Helpdesk's public, self-service pillar: a searchable library of published articles grouped into categories, browsable by anyone — including logged-out visitors on the open internet — through a modern, brand-themed, dark-mode-aware public shell.
What the Knowledge Base is
The Knowledge Base (KB) is the outward-facing half of the Help Center. Where the Internal Wiki is staff-only, the KB is designed to be read by customers and the public: guides, how-tos, FAQs, and troubleshooting articles that deflect tickets before they are ever raised. Every published KB article is grouped under a category, is full-text searchable, and counts its own views.
help_articles and help_categories tables — discriminated only by a type column. KB records carry type = 'knowledge_base'; Wiki records carry type = 'help'. Categories and articles never cross over: a knowledge_base category only lists knowledge_base articles, and vice-versa. See the Internal Wiki page for the staff-only twin.Where reading lives vs. where authoring lives
Two controllers cooperate to make this work, and knowing which is which explains the whole security model:
Knowledge_base controller — the anonymous/guest reading surface at /knowledge_base.Help controller — all create / edit / delete of KB articles & categories, permission-gated, never public.Public, anonymous access
This is the defining behaviour of the KB pillar, and it is worth understanding precisely because it means published content is internet-visible.
The OptionalAuthGuard
The Knowledge_base controller runs under App\Guards\OptionalAuthGuard (set in initializeGuard()). Unlike a normal authenticated controller, this guard does not bounce a logged-out visitor to the sign-in page. Instead:
A logged-out visitor is resolved as a guest and served the branded public shell. A logged-in staff member hitting the same URL is resolved with full, unserialized permissions and served the in-app management experience instead. One route, two audiences.
What a guest can and cannot do
| Guest can | Guest cannot |
|---|---|
| Browse every active category on the landing page | See any inactive (draft) category or article — those return show_404() |
| Read any published article and its attachments | Preview drafts (only logged-in staff may preview inactive content) |
| Search the whole public KB (all active categories) | Reach any management tab-panel (view_preview / view_articles / view_categories all show_404() for guests) |
| Download files attached to active articles | Create, edit or delete anything (authoring lives in the gated Help controller) |
module_knowledge_base is enabled, every category and article with status active is visible to anyone on the internet for that tenant, with no login. Treat "publish" as "make public." Never place confidential, internal, or customer-specific information in a KB article — that is what the staff-only Internal Wiki is for. Keep drafts as inactive until they are cleared for public release.module_knowledge_base is not enabled, every KB route returns show_404() rather than a "forbidden" page — so a probing visitor cannot even tell the KB exists. The master module_helpdesk toggle must also be on. See Getting Started & Setup for the toggle hierarchy.The branded public shell
Anonymous visitors get a modern, token-driven experience (it adapts to light/dark mode automatically), rendered from two views under help_and_knowledge_base/public/:
| View | Rendered by | What it shows |
|---|---|---|
public/index.php | Knowledge_base::index() (guest) | The landing: a hero with the prompt "How can we help?", a prominent search box, and a branded grid of category cards (each showing its article count). |
public/reader.php | Knowledge_base::category() and ::view() (guest) | A sidebar (search + category list) plus a content panel that shows either a category's article list or a single article's body + attachments. |
For guest requests the controller sets topbar = "includes/public/topbar" and left_menu = false, so there is no staff chrome — just the core public header (CMS theme chrome injected when the Content module is active), the KB shell, and the footer. The shell is scoped to .kb-public-page and driven entirely by the app's semantic theme tokens.
/help-center (route key help-center → help_center/index), renders the CMS core.helpcenter override through the Content module, giving the Help Center a full CMS-themed header/footer. It is a soft dependency (it 404s gracefully if Content/CMS is unavailable). See Web Pages & Help Center for how the CMS shell wraps public Helpdesk surfaces.Article & category data model
Categories — help_categories
The category's display name (e.g. "Getting Started", "Billing").
Optional rich-text blurb shown under the category heading and inside its card.
Always knowledge_base for KB categories (vs. help for the Wiki).
Numeric ordering; categories are listed ORDER BY sort everywhere.
active = public; inactive = hidden from guests. Only active categories appear publicly, and only their active articles are counted.
Live count of that category's active, non-deleted articles, computed by the model and shown on each category card.
Articles — help_articles
Required. The article headline, used in listings, breadcrumbs and search results.
The article body — rich HTML authored in a WYSIWYG editor. Rendered as-is in the reader (admin-authored, trusted content).
Required. The parent category the article belongs to.
Serialized list of attachments, previewed and downloadable from the article view.
active = published/public; inactive = draft (staff-preview only). Guests get show_404() on anything not active.
Incremented on every article view (guest or staff) via the model's increas_page_view(). Category article lists sort by total_views DESC so the most-read pieces surface first.
Set on first save; part of the standard audit block.
status is set to active (a two-radio choice: Active / Inactive). Set it to inactive to unpublish and pull it from public view immediately.Search suggestions
The search box (shared search_box.php, powered by Awesomplete) posts to get_article_suggestion, which queries the model's get_suggestions(). Suggestions match the search term against both article title and body (LIKE), are limited to active articles in active categories of the correct type, capped at 10 results, and sorted by title. For a guest the scope is the entire public KB; for a logged-in user it is narrowed to their allowed categories. Selecting a suggestion navigates straight to {type}/view/{id}.
Statuses at a glance
| Status | Applies to | Guest sees it? | Meaning |
|---|---|---|---|
| active | Category & Article | Yes | Published and public. Counted in total_articles; appears in listings and search. |
| inactive | Category & Article | No (show_404) | Draft / unpublished. Visible only to logged-in staff for preview. |
Workflows
Author and publish a KB article
1 · Open KB management
As a staff user with the knowledge_base permit, go to /knowledge_base. Because you are logged in, you get the in-app tabbed view (Preview / Articles / Categories) rather than the public shell.
2 · Ensure a category exists
On the Categories tab, create the destination category first (title, description, sort, status). Set its status to active so it shows publicly.
3 · Create the article
On the Articles tab, click Create. The form (help/article_form/knowledge_base) captures title, category, the rich-text body, and optional file attachments.
4 · Write and set status
Draft the body. While unfinished, keep the article inactive — staff can preview it, the public cannot.
5 · Publish
Flip the status to active and save. The article is instantly live at /knowledge_base/view/{id} and appears in its category and in public search.
Organize categories
1 · Categories tab
Open the Categories tab in KB management (requires the knowledge_base_categories permit).
2 · Add or edit
Use the Add Category modal to set title, description, a numeric sort, and status.
3 · Order with sort
Lower sort values appear first — categories render ORDER BY sort on the landing, sidebar and dropdowns.
4 · Retire a category
Set it inactive to hide it (and all its articles) from the public without deleting anything; or delete it (soft delete) if the knowledge_base_category_delete permit is held.
Browse as an anonymous visitor
1 · Land
The visitor opens /knowledge_base (or the CMS-themed /help-center front door) with no account. The public shell renders: hero, search, category grid.
2 · Pick a category
Clicking a card goes to /knowledge_base/category/{id} — the reader shows that category's active articles, most-viewed first.
3 · Read an article
Selecting an article opens /knowledge_base/view/{id}, which renders the body, previews any attachments, and increments total_views.
4 · Download attachments
Attached files download via knowledge_base/download_files/{id} — permitted only for active articles.
Search for an answer
1 · Type a question
Start typing in the search box on the landing or reader sidebar. After one character, an AJAX request fires (debounced ~200ms).
2 · See live suggestions
Up to 10 matching article titles appear via Awesomplete, matched against both title and body across the public KB.
3 · Jump to the article
Selecting a suggestion navigates directly to that article's reader view — no results page hop.
Standard Operating Procedures
- Confirm
module_helpdeskandmodule_knowledge_baseare both enabled for the tenant. - Verify the target category exists and is
active. Create it first if not. - Create the article under that category with a clear, searchable title.
- Write the body in the rich-text editor; add attachments if needed.
- Keep status
inactiveand preview it as staff until it reads correctly. - Peer-review for accuracy and for anything confidential — remember this is going public.
- Set status to
activeand save. Confirm it renders at/knowledge_base/view/{id}while logged out. - Verify it appears in its category card count and in public search.
- Identify a repeat question surfacing in Tickets (same issue raised often).
- Author a KB article that answers it thoroughly, in customer-friendly language.
- Publish it (status
active) in the most relevant category. - When replying to the original and future tickets, link the public article URL (
/knowledge_base/view/{id}). - Ensure the article's title and body use the words customers actually search for, so it surfaces in suggestions.
- Track
total_viewsover time — a rising count confirms the article is deflecting real demand.
/help-center shell.Routes & URLs
| Route | Controller / method | Audience | Purpose |
|---|---|---|---|
/knowledge_base | Knowledge_base/index | Public + staff | KB landing (public shell for guests; tabbed management for staff). |
/knowledge_base/category/{id} | Knowledge_base/category/$1 | Public + staff | Category reader — lists that category's active articles. |
/knowledge_base/view/{id} | Knowledge_base/view/$1 | Public + staff | Single-article reader; increments total_views. |
/knowledge_base/download_files/{id} | Knowledge_base/download_files/$1 | Public (active only) | Download an active article's attachments. |
/knowledge_base/get_article_suggestion | Knowledge_base/get_article_suggestion | Public + staff | AJAX search suggestions (JSON). |
/help-center | help_center/index | Public | CMS-themed Help Center front door (soft-depends on Content module). |
help/… KB management (create/edit/delete of articles and categories) is served by the Help controller — e.g. help/article_form/knowledge_base/{id}, help/save_article, help/delete_article, help/save_category, help/delete_category. These are permission-gated and never public. The Knowledge_base controller is read-only.Permissions & access control
Access to the KB requires two things together: the module_knowledge_base toggle enabled and the relevant permit granted. Guests need neither for reading published content — but a logged-in staff user hitting the in-app KB must hold the knowledge_base permit (else they are redirected). Authoring always requires the specific create/update/delete permit.
A logged-out visitor needs no permission at all. As long as module_knowledge_base is enabled, they can read every active category and article, search, and download active-article files. They are handled as a guest by the OptionalAuthGuard and can never reach management panels or drafts.
A logged-in staff user is scoped by their serialized permissions. The knowledge_base permit gates the in-app KB view; knowledge_base_categories (all / specific dropdown) narrows which categories they manage; and the granular create/update/delete permits gate each authoring action inside the Help controller.
| Permission key | Level | Grants |
|---|---|---|
knowledge_base | module (Enabled) | Access the in-app Knowledge Base (management view) as a logged-in user. |
knowledge_base_create | action (Create) | Create new KB articles. |
knowledge_base_update | action (Edit) | Edit existing KB articles. |
knowledge_base_delete | action (Remove) | Delete (soft-delete) KB articles. |
knowledge_base_category | action (Enable Category) | The "Enable Category" capability action for KB categories. |
knowledge_base_category_create | action (Create Category) | Create KB categories. |
knowledge_base_category_update | action (Edit Category) | Edit KB categories. |
knowledge_base_category_delete | action (Remove Category) | Delete (soft-delete) KB categories. |
knowledge_base_categories | specific (all / specific dropdown) | Gates the Categories management tab (has_category) and scopes which categories the user may access — all, or a specific set (stored in knowledge_base_categories_specific). |
These keys are module-owned (declared in the Helpdesk config/permissions.php) and appear in the Roles UI only when module_helpdesk is enabled. For the complete cross-pillar matrix, see the Permissions Reference.
Terminology
The public, searchable article library (type = 'knowledge_base').
A logged-out visitor, resolved by the OptionalAuthGuard; sees only active content.
The branded, dark-mode-aware guest views (public/index.php + public/reader.php).
The CMS-themed public front door at /help-center that frames the Helpdesk public surfaces.
Per-article view counter; also the default sort for a category's article list.
An article/category with status inactive — visible to staff preview only.
Troubleshooting
The module is disabled. Check that both module_helpdesk (master) and module_knowledge_base (pillar) are enabled for the tenant. A disabled module deliberately 404s to hide its existence rather than showing a forbidden page.
The article's status is inactive, or its parent category is inactive. Guests get show_404() on anything not active (both article and category must be active). Set both to active.
The total_articles count only includes active, non-deleted articles. Confirm the articles are active and belong to the right category. Inactive drafts are excluded from the count.
Their knowledge_base_categories access is set to specific with no allowed categories assigned, so the scope resolves to an empty set. Grant them all, or add the specific category IDs in knowledge_base_categories_specific. (Guests always search the full public KB.)
They are logged in but lack the knowledge_base permit, so the in-app view redirects. Grant the permit, or have them read the public shell while logged out. (Reading published content publicly needs no permit.)
The CMS-themed front door soft-depends on the Content module and its core.helpcenter override. If Content/CMS is unavailable it degrades gracefully. Confirm the Content module is installed and enabled — see Web Pages & Help Center.
Related pages
Internal Wiki
The staff-only twin sharing the same tables (type = 'help').
Web Pages & Help Center
The CMS-themed public shell and the /help-center front door.
Tickets
Deflect repeat questions into the KB; link articles from replies.
Permissions Reference
The full knowledge_base* permit matrix across all pillars.