# Knowledge base

Agents write articles in the desk at `/opendesk/kb`. Customers and guests read them in the portal at `/help`. This file follows an article from the database to both apps. For how the portal itself is built, read [`README.md`](README.md).

## Data

| DocType | Folder under `opendesk/opendesk/doctype/` | Holds |
|---|---|---|
| `OD Article` | `od_article` | title, category, content, excerpt, author, `status`, `visibility`, `title_slug`, views |
| `OD Article Category` | `od_article_category` | name, description, icon, `pinned`, `pinned_order` |
| `OD Article Feedback` | `od_article_feedback` | one vote per user or guest visitor: 0 none, 1 like, 2 dislike |

`OD Settings` holds the site-wide switches on its knowledge base tab:

- `public_knowledge_base`: guests can read the KB. If it is off, guests must sign in.
- `prefer_knowledge_base`: the customer home is the KB (`/help`), not the ticket list (`/help/my-tickets`).
- `allow_anonymous_article_voting`: guests can vote.
- `banner_image`, `banner_preset`: the banner on the KB home.

## Who can read what

Only `Published` articles are readable outside the desk. `visibility` then decides who sees an article:

| Visibility | Guest | Customer | Agent |
|---|---|---|---|
| `Public` | yes, if `public_knowledge_base` is on | yes | yes |
| `Customers` | no | yes | yes |
| `Private` | no | no | yes |

Agents see every article, in every status. A signed-in user without a customer role sees only `Public`.

The rules live in `od_article/od_article.py`:

- `make_article_filters()` builds the filters that every list query uses.
- `can_view_article()` checks one article.
- `permission_query` and `has_permission` apply the same rules to Frappe permissions. `opendesk/hooks.py` registers them.

A category has no visibility field. `get_category_visibility()` in `od_article_category.py` reads it from the category's articles. An article that joins a category can only get stricter visibility, never wider (`get_stricter_visibility()`).

The `General` category is reserved. It cannot be renamed or deleted.

## APIs

`opendesk/api/knowledge_base.py` has the KB endpoints.

- **Reads** (guests allowed, `GET`): `get_categories`, `get_articles`, `get_kb_sidebar`, `get_article`, `get_article_markdown`, `search_articles`.
- **Guest writes** (`POST`, rate limited): `vote_on_article`, `increment_views`. A guest voter is known by the `od_visitor` cookie.
- **Agent only**: `create_category`, `delete_articles`, `move_to_category`, `merge_category`, `get_category_visibility`, `set_category_visibility`, `get_general_category`.

Every guest endpoint calls `validate_public_access()` first. Keep that call in any new guest endpoint.

Other files:

- `opendesk/api/article.py`: `get_related` (articles for a ticket), `get_article_stats` and search helpers.
- `opendesk/search.py`: the RediSearch index for articles. `after_migrate` and a scheduled job build it.
- `opendesk/api/config.py`: `get_config` gives the portal its KB flags, banner and KB form scripts.

## Desk: authoring

| What | Where |
|---|---|
| Article and category list | `desk/src/pages/knowledge-base/KnowledgeBaseAgent.vue` (`/opendesk/kb`) |
| Read and edit an article | `desk/src/pages/knowledge-base/Article.vue` (`/opendesk/kb/articles/:articleId`) |
| New article | `desk/src/pages/knowledge-base/NewArticle.vue` |
| Category, access, move and merge dialogs | `desk/src/components/knowledge-base/` |
| Desk KB state | `desk/src/stores/knowledgeBase.ts` |
| KB settings tab | `desk/src/components/Settings/KnowledgeBase/KnowledgeBase.vue` |

The desk links to the portal copy of an article with `CUSTOMER_PORTAL_ROOT + ROUTES.article(...)` from `@opendesk/shared`.

## Portal: reading

| Page | URL | Data |
|---|---|---|
| `public_kb` | `/help` | `get_categories`, `get_articles` (popular or recent) |
| `categories` | `/help/categories` | `get_categories` |
| `category` | `/help/category/:category` | `get_articles` for one category |
| `article` | `/help/articles/:name-slug` | `get_article`, `increment_views`, `vote_on_article`, `get_article_markdown` |

All four pages allow guests and use `useKnowledgeBaseHeader` and the `kb_settings` Studio Component. The sidebar, the article cache and hover prefetch are in `studio/opendesk/stores/knowledgeBase.ts`. The article parts (body, contents, feedback, sidebar, "copy for LLM") are in `studio/opendesk/components/knowledge_base/`.

Search (`PortalArticleSearch`) and the article suggestions on the new ticket form both use `useArticleSearch`, which calls `search_articles`.

## Settings shared by both apps

The KB look and feel (banner, pinned categories, header links) has one form, `shared/src/settings/KnowledgeBaseForm.vue`. The desk Settings tab and the portal Settings dialog both render it.

`shared/src/settings/knowledgeBaseDraft.ts` holds the unsaved draft. It writes `OD Settings`, the category pins and the header links. Header links are stored in an `OD Form Script` with `apply_to_knowledge_base` set.

`?preview=1` on the KB home shows the unsaved draft (`shared/src/knowledgeBasePreview.ts`).

## Old URLs

`website_redirects` in `opendesk/hooks.py` keeps the URLs of the old portal working:

| Old | New |
|---|---|
| `/opendesk/kb-public` | `/help` |
| `/opendesk/kb-public/articles/<name>` | `/help/articles/<name>` |
| `/opendesk/kb-public/<category>` | `/help/category/<category>` |

## Tests

- Backend: `opendesk/tests/api/test_knowledge_base.py` (public reads, customer-only articles, permissions, category access, search), `opendesk/tests/api/test_article.py`, `opendesk/tests/test_search.py`, and the DocType tests in `od_article` and `od_article_category`.
- End to end: `e2e/tests/knowledge-base/` has the portal walkthrough and the agent spec. `e2e/helpers/portal.ts` makes categories and articles over REST.

When you add a guest endpoint, add a test that a guest is refused while `public_knowledge_base` is off.