# Knowledge Base

Topics, categories, articles, and help center configuration


Publish self-service content as topics → categories → articles, configure the client portal help center record that the published site reads, and run frontline report queries.

Backend modules: `backend/plugins/frontline_api/src/modules/{knowledgebase,helpcenter,reports}`. Frontend: `frontend/plugins/frontline_ui/src/modules/{knowledgebase,helpcenter,report}` at `/frontline/knowledgebase`, `/frontline/helpcenter`, and `/frontline/reports`.

## Knowledge base

### Hierarchy

Content is organized `Topic` → `Category` → `Article`:

- A `Topic` is the top-level grouping published to portals (`title`, `description`, `brandId`, `color`, `icon`, `languageCode`).
- A `Category` groups articles inside a topic (`title`, `description`, `icon`, `topicIds`, `parentCategoryId`, `numArticles`).
- An `Article` carries `title`, `summary`, `content`, `status` (`draft`/`publish`), `isPrivate`, `reactionChoices`/`reactionCounts`, `topicId`, `categoryId`, `attachments`, `image`, `pdfAttachment`, publication fields (`createdUser`, `createdDate`, `modifiedDate`), and form codes that attach a lead form to the article.

### Knowledge base queries and mutations

Schema: [`modules/knowledgebase/graphql/schemas/knowledgeBaseTypeDefs.ts`](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/plugins/frontline_api/src/modules/knowledgebase/graphql/schemas/knowledgeBaseTypeDefs.ts).

| Operation | Kind | Purpose |
| --- | --- | --- |
| `knowledgeBaseTopics` / `knowledgeBaseTopicDetail` / `knowledgeBaseTopicsTotalCount` | query | Topic reads |
| `knowledgeBaseCategories` / `knowledgeBaseCategoryDetail` / `knowledgeBaseCategoriesTotalCount` / `knowledgeBaseCategoriesGetLast` | query | Category reads |
| `knowledgeBaseArticles` / `knowledgeBaseArticleDetail` / `knowledgeBaseArticlesTotalCount` | query | Article reads |
| `knowledgeBaseArticleDetailAndIncViewCount` / `knowledgeBaseArticlesIncrementViewCount` | query/mutation | Read while incrementing the article view counter |
| `knowledgeBaseTopicsAdd` / `…Edit` / `…Remove` | mutation | Topic management |
| `knowledgeBaseCategoriesAdd` / `…Edit` / `…Remove` | mutation | Category management |
| `knowledgeBaseArticlesAdd` / `…Edit` / `…Remove` | mutation | Article management |
| `cpKnowledgeBaseTopicDetail` | query | Client portal read used by the published help center |

### AI knowledge source

The knowledge base registers an AI knowledge source through [`meta/automations`](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/plugins/frontline_api/src/modules/knowledgebase/meta/automations.ts): `ai.knowledgeSources` contains `{ key: 'knowledgebase.article', label: 'Knowledge base articles', moduleName: 'knowledgebase', sourceSelector: 'remote-module', supportsFullScope: true }`. Articles index with the category title included (articles are often titled numerically), so agent knowledge lookups match meaningful terms.

## Help Center

### The config record

`HelpCenterConfig` is the single record a published help center site reads. `helpCenterConfigUpdate(config)` upserts it; sections include:

- **General**: `title`, `description`, `url`, `erxesAppToken`, `brandId`, `languageCode`, knowledge-base toggle/label/`kbTopicId` (`kbToggle`, `kbLabel`), ticket toggle/label/`ticketChannelId`/`ticketPipelineId`/`ticketStatusId` (`ticketToggle`, `ticketLabel`).
- **Appearance**: top-level `color` and `backgroundImage`, plus a `styles` object with `mainLogo`, `favicon`, `bodyColor`, `headerColor`, `footerColor`, `helpCenterColor`, `backgroundColor`, `activeTabColor`, `baseFont`/`baseColor`, `headingFont`/`headingColor`, `linkColor`/`linkHoverColor`, `primaryButtonColor`/`secondaryButtonColor`, `dividerColor`, and raw `headerHtml`/`footerHtml`.
- **Header**: `wordmark`, `homeLabel`, `formsLabel`, `announcementsLabel`, `searchPlaceholder`.
- **Footer**: `logo`, `description`, `copyright`, and `columns` (`heading` plus `links` of `label`/`url`).

### Domain resolution

`helpCenterGetConfigByDomain` ignores its argument and reads the config from the request's `Origin` header. The header is normalized and matched (case-insensitively, prefix + `/`) against each config's `url`. Its `wrapperConfig.skipPermission: true` flag makes it callable without the `showHelpCenter` permission, which is what the published app calls before any user logs in.

> [!WARNING]
> If `helpCenterGetConfigByDomain` returns nothing, no config's `url` matches the request's `Origin`. Create one with `helpCenterConfigUpdate`.

### Help Center queries and mutations

Schema: [`modules/helpcenter/graphql/schemas/helpCenterConfig.ts`](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/plugins/frontline_api/src/modules/helpcenter/graphql/schemas/helpCenterConfig.ts).

| Operation | Kind | Purpose |
| --- | --- | --- |
| `helpCenterConfig(_id)` / `helpCenterConfigs(page, perPage, searchValue, brandId)` / `helpCenterConfigsTotalCount` | query | Admin reads |
| `helpCenterGetConfigByDomain` | query | Public resolution by request `Origin` (`skipPermission: true`) |
| `helpCenterConfigUpdate(config)` / `helpCenterConfigRemove(_id)` | mutation | Upsert / remove |

### How the Help Center app uses it

The standalone `apps/help-center` Next.js app (port `3900`, `NEXT_PUBLIC_ERXES_API_URL`, `NEXT_PUBLIC_APP_VERSION`) calls `helpCenterGetConfigByDomain` for configuration, then `cpKnowledgeBaseTopicDetail` for content, `cpForms`/`cpFormDetail` for forms, and `cpGetTickets`/`cpGetTicket`/`cpTicketGetNotes`/`cpCreateTicket`/`cpTicketCreateNote` for portal tickets. See [Help Center](https://erxes.io/docs/app-help-center).

## Reports

The `reports` module backs `/frontline/reports`, `/frontline/calls/dashboard`, and `/frontline/calls/statistics`.

| Area | Queries | Service |
| --- | --- | --- |
| Inbox | `reportConversationList`, `reportConversationOpen`/`Closed`/`Resolved`, `reportConversationTags`, `reportConversationSources`, `reportConversationResponses`, `reportConversationExport`, `conversationProgressChart` and member/source/tag progress | `reportConversation*` resolvers |
| Tickets | `reportTicketList`, `reportTicketSource`, `reportTicketDate`, `reportTicketOpen`, `reportTicketTags`, `reportTicketCustomProperties`, `reportTicketStatusSummary`, `reportTicketPriority`, `reportTicketExport` | ticket report resolvers |
| Calls | `callReportIntegrations`, `callGetQueueStats`, `callGetAgentStats`, `getCallbackStats`, `callVolumeSeries`, `callCarrierBreakdown`, `callHeatmap`, `callHeatmapDaily`, `callTopNumbers`, `callGetOperatorStats`, `callHistoryList` | `callReportService.ts`, `callHistoryService.ts`, `callStatistics.ts` |
| Facebook | `reportFacebookPages`, `reportFacebookActivity`, `reportFacebookBots`, `reportFacebookSyncPostStats` | `facebookSyncService.ts` |
| Saved charts | `reportCharts`, `reportChartDetail`, `reportChartAdd`, `reportChartEdit`/`Remove` (stored in `frontline_report_charts`) | chart resolvers |