opendesk

The customer portal is a Studio app (Studio ships with frappe). Customers use it at /help to read the knowledge base, raise tickets and reply to them. Agents use the desk app at /opendesk.

This file explains how the portal is built, where its code lives and how to work on it. For the knowledge base from end to end (DocTypes, APIs, desk authoring), read KNOWLEDGE_BASE.md.

How Studio runs the portal

Studio is a Frappe app that renders pages from JSON. Each page is a tree of blocks: Vue components with props, events and styles. A page can also have a TypeScript setup script. The values that the script returns are available to the blocks through {{ }} expressions.

Opendesk ships the portal as a standard app: the pages live as files in this folder, not only in the database.

• The files in git are the source of truth. bench migrate imports them into the Studio App, Studio Page and Studio Component DocTypes. It also deletes pages that have no file.
• With developer_mode on, a save in the Studio editor writes the JSON back to these files. Commit the file diff.
• Page scripts (.ts) and Vue components (.vue) live only on disk. The database never holds them.
• bench build-studio-app opendesk --site <site> builds the production bundle into opendesk/public/app_builds/opendesk/ (gitignored). bench build --app opendesk also builds it.

Studio documents its own rules. Read them before you change a page:

Topic	File in apps/frappe
Dev server and watch-studio setup	studio/frontend/README.md
File layout, page JSON, setup(context), custom Vue components, sync loop	skills/studio-app-building/SKILL.md
Runtime rules: {{ }}, event scripts, v-model, Repeater, icons, tokens	skills/studio-app-building/RULES.md
Routing and the global boot	skills/studio-app-building/ROUTING.md
Visual design language	skills/studio-app-building/DESIGN.md

What is where

studio/opendesk/
  opendesk.json          Studio App record: route "help", app_home = public_kb
  router.ts              opens the Settings dialog at <page>/settings/<screen>
  studio_page/<page>/    <page>.json (block tree) + <page>.ts (setup script)
  studio_components/     Studio Components: reusable block trees with inputs
  components/            custom Vue components, by area
  stores/                module-level state shared between pages
  composables/           page logic, one concern per file
  tailwind.config.js     adds shared/src to Studio's Tailwind scan
  tsconfig.json          @app/* alias. Studio rewrites it on every app save

Pages

Page	URL	Guest	Shows
public_kb	/help	yes	KB home: banner, search, pinned categories, popular and recent articles
categories	/help/categories	yes	All categories with a filter
category	/help/category/:category	yes	Articles in one category
article	/help/articles/:name	yes	Article body, contents, feedback, related articles
customer_tickets	/help/my-tickets	no	Ticket list with saved views, filters, sort and export
new_ticket	/help/tickets/new	no	New ticket form with article suggestions
ticket	/help/tickets/:name	no	Ticket thread, reply composer, details and feedback

The article URL param is <name>-<slug>. articleName() in stores/knowledgeBase.ts reads the name from it.

Studio Components

Every page embeds header and kb_settings.

• header: the top bar. It has the brand, breadcrumbs, quick links, the theme toggle and the account menu. Its inputs (crumb, parentRoute, drawerToggle and others) are listed in the JSON.
• kb_settings: the portal Settings dialog. It has profile, members, knowledge base and portal settings tabs. It has no inputs and binds to useSettingsModal.
• category_grid: a Repeater of category cards. public_kb and categories use it.

Custom Vue components

Under components/, by area: ui, header, list, ticket, knowledge_base and settings. A block uses one with isCustomVueComponent: true and the file name as componentName.

• Portal-only components start with Portal.
• The file name must be unique in studio/opendesk/ and must not match a Studio built-in component. Studio skips a clash and writes an Error Log.
• The desk imports NewTicketForm.vue and CustomActions.vue from here by relative path. Test the desk when you change them.

Stores

The stores are module-level singletons, not Pinia.

• settings/index.ts: useSettingsModal(context). Every page spreads it into its return value. It binds the router and socket, and it exposes t (translate) and routes (ROUTES) to the blocks.
• session.ts: user and site flags from opendesk.api.config.get_config (isGuest, isAgent, isPublicKnowledgeBase, brand).
• router.ts: holds the router, because page scripts get it only through context. Use navigateTo() from here.
• knowledgeBase.ts: the KB sidebar, an article cache and hover prefetch.
• views.ts: saved ticket list views (OD View).
• ticketMeta.ts: ticket statuses and priorities, loaded lazily because guests cannot read them.
• recent.ts, conversationLayout.ts: per-browser preferences in localStorage.

Composables

• useKnowledgeBaseHeader: the header for the four KB pages. It runs KB form scripts into header links and custom actions.
• useArticleSearch: debounced article search, used by the search box and the new ticket form.
• useDrawer: the ticket page's mobile side drawer. useBottomSheet: open state for the knowledge base sidebar, a frappe-ui BottomSheet on phones.
• useTicketThread, useReplyComposer, useTicketDetails, useTicketFeedback, useOutsideHoursBanner, useChatRows: the parts of the ticket page.
• useRememberedCount: remembers a list's length so its skeleton keeps the same size.

Shared code: @opendesk/shared

shared/src holds the code that the portal and the desk both use. The root package.json links it as @opendesk/shared, so run yarn install in apps/opendesk before the first build.

• portalRoutes.ts: ROUTES, every portal path. The desk uses it to link into the portal.
• translation.ts: __() and fetchTranslations().
• utils.ts: dates, CUSTOMER_PORTAL_ROOT, updateTicket, addHeadingIds, countLabel and more.
• settings/: KnowledgeBaseForm and PortalPermissionsForm, used by both the desk Settings and the portal Settings dialog.
• filter/, ticketCells.ts, ticketStatus.ts, tiptap.ts, formScripts.ts and shared icons.

Put code in shared/src only when both apps use it. Inside shared/src, use relative imports.

Backend and serving

• opendesk/hooks.py:
  • studio_app_boot sets the global boot (timezone, home page, brand).
  • update_website_context sets the portal title and favicon.
  • website_redirects sends the old /opendesk/my-tickets and /opendesk/kb-public URLs to /help.
• opendesk/opendesk/hooks/studio_app.py: the two hook functions.
• opendesk/www/opendesk/index.py: sends a customer who opens /opendesk to the portal.
• opendesk/api/: the portal calls config.py, knowledge_base.py, article.py and customer.py. Ticket calls go to opendesk/opendesk/doctype/od_ticket/api.py.

Set up for development

1. Do the "Frontend Development & Exported Apps" setup in apps/frappe/studio/frontend/README.md: developer_mode, ignore_csrf, bench setup requirements --dev and yarn dev --host in apps/frappe/studio/frontend. In developer mode bench watch starts the same dev server.
2. Run yarn install in apps/opendesk. This links @opendesk/shared.
3. Start the watcher and keep it running: bench --site <site> watch-studio.
4. Open /dev/help on the Vite dev server, for example http://<site>:8080/dev/help.

Use /dev/help while you work. /help serves the last production build, so it does not show your changes until you build again.

What reloads by itself:

• .ts and .vue files: Vite hot-reloads them.
• Page and component JSON: watch-studio imports it.
• tailwind.config.js: restart Vite.
• A new folder under studio/: restart watch-studio.

Do not run bench migrate or build-studio-app in the edit loop. Build only to check the production bundle.

Make a change

Change a page

1. Read the page's .json and .ts together. The blocks bind only to what setup returns, to route, to inputs (inside a Studio Component) and to dataItem (inside a Repeater).
2. Put the logic in the .ts file, a composable or a store. Keep each {{ }} expression to a name or a short call.
3. Edit the block tree in the Studio editor or in the JSON file. If you edit the JSON while the page is open in the editor, refresh the editor before you save there.
4. Check the page at /dev/help as a guest, a customer and an agent where they apply.

Add a page

1. Make the page in the Studio editor, inside the Opendesk app. In developer mode the save writes studio_page/<page>/<page>.json.
2. Add <page>.ts next to it with export default function setup(context). Spread useSettingsModal(context) (or useKnowledgeBaseHeader(context) on a KB page) into the return value.
3. Add header and kb_settings blocks, like the other pages.
4. Add the path to ROUTES in shared/src/portalRoutes.ts.
5. Set allow_guest only if guests must see the page.

Add a component

1. Add components/<area>/Portal<Name>.vue. Use frappe-ui components and Tailwind with the semantic tokens.
2. Use it in a block with isCustomVueComponent: true and componentName: "Portal<Name>".
3. Make it a Studio Component (studio_components/) only if it is a block tree that pages repeat. Make it a Vue component when it has its own logic.

Rename or retitle a page

Keep page_name the same. Move the .json and .ts to the new folder name together. A new title also changes the route name, so search for router.push({ name: ... }) callers.

Conventions

• Routes: use ROUTES in scripts and {{ routes.x(...) }} in blocks. Navigate with navigateTo() from stores/router.ts.
• Translation: use __('literal string') from @opendesk/shared/translation with {0} placeholders. In blocks, use {{ t('...') }}. Build labels inside a function or computed, so they follow a language change.
• Imports: @app/... for code in studio/opendesk, @opendesk/shared/<module> for shared code.
• Comments: one line, only for a reason the code cannot show.
• Guest APIs: @frappe.whitelist(allow_guest=True, methods=["GET"]), with validate_public_access() and a @rate_limit where it can be abused.
• Commits: conventional commits with the portal or kb scope, for example fix(portal): send a reply that has only attachments.

Gotchas

• If you edit opendesk.json or a Studio Component JSON by hand, increase its modified value. bench migrate skips the file otherwise. watch-studio imports it anyway.
• watch-studio does not sync deletions. bench migrate deletes pages and apps that have no file. It never deletes Studio Components.
• A database patch does not change these files. When a patch changes Studio records, change the files too.
• The Studio file explorer cannot edit exported JSON. Edit it in the editor or on disk.
• A component in a block tree that Studio does not know fails the build.

Tests

• End to end: Playwright specs in e2e/tests/. Portal specs sit next to their desk page: knowledge-base/, tickets/customer/, tickets/list/, tickets/new/ and settings/portal-settings-walkthrough.spec.ts. Read e2e/README.md for how to run and write them.
• Backend: opendesk/tests/api/test_knowledge_base.py, test_article.py, test_customer.py and test_auth.py. Read opendesk/tests/AGENTS.md for the rules.