Architecture Overview¶
This document gives a technical overview of IntroVox's architecture for architects, developers, and IT decision-makers.
System Overview¶
IntroVox is a Nextcloud app that follows Nextcloud's standard app architecture: a PHP backend exposing REST endpoints, a Vue 3 frontend bundled with webpack, and state stored in Nextcloud's appconfig and preferences tables.
┌──────────────────────────────────────────────────────────────┐
│ Nextcloud Server │
│ ┌─────────────────┐ ┌──────────────────────────────────┐ │
│ │ Files / Apps │ │ IL10N · IGroupManager │ │
│ │ menu │ │ IUserSession · IConfig │ │
│ └────────┬────────┘ └──────────────┬───────────────────┘ │
│ │ │ │
│ ┌────────┴──────────────────────────┴────────────────────┐ │
│ │ IntroVox App │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Vue Frontend │──│ PHP REST API │──│ Background │ │ │
│ │ │ Shepherd.js │ │ Controllers │ │ Jobs │ │ │
│ │ └──────────────┘ └──────┬───────┘ └──────────────┘ │ │
│ │ │ │ │
│ │ ┌────────────────────────┴──────────────────────┐ │ │
│ │ │ Services │ │ │
│ │ │ TelemetryService · LicenseService │ │ │
│ │ └────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┴───────────────────────────┐ │
│ │ Nextcloud Database │ │
│ │ ┌────────────┐ ┌───────────────────────────────┐ │ │
│ │ │ appconfig │ │ preferences (per-user) │ │ │
│ │ │ (wizard_*) │ │ (wizard_*, tours_*, tour_*) │ │ │
│ │ └────────────┘ └───────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
│
▼
licenses.voxcloud.nl
(telemetry + optional subscription key)
Core Components¶
Frontend (Vue 3 + Shepherd.js)¶
| Component | Responsibility |
|---|---|
src/main.js |
Small bootstrap on every Nextcloud page: decides whether a tour runs (src/runtime/chooseTour.mjs) and only then loads the tour code |
src/runtime/tour.js |
The tour chunk: mounts WizardManager; loaded only on a page where a tour runs |
src/admin.js |
Admin settings UI entry point |
src/personal.js |
Personal settings UI entry point |
src/embed/embed.js |
<introvox-tour-list> for other apps: the tours a user can start, as plain links the other app styles |
src/components/WizardManager.vue |
Manages Shepherd.js tour lifecycle and step rendering, for the welcome tour and tours for apps |
src/admin/ToursList.vue, src/admin/NewTourDialog.vue |
The admin's Tours pane: the list of tours, and making or changing a tour for an app |
src/admin/TourEditor.vue, src/admin/StepWizard.vue |
The steps of one tour, and the dialog that edits a step, with its text editor and media (StepTextEditor.vue, StepMediaBlock.vue) |
src/components/SupportSettings.vue |
The Support pane: about IntroVox, links, and Show the admin tour again |
src/components/wizardSteps.js |
Default step definitions wrapped in t('introvox', ...), and the helpers that find and wait for a step's element |
Technology stack: Vue 3 (Composition API), webpack, Shepherd.js, @nextcloud/vue.
Backend (PHP)¶
| Component | Responsibility |
|---|---|
AdminController |
Admin CRUD for the steps of every tour, languages, settings; export/import |
ToursController |
Admin: the tours themselves (list, create, change, delete, show again, statistics, export and import) |
AssistantController, TourAssistant |
Admin: translating a tour and drafting steps with the Nextcloud Assistant (OCP\TaskProcessing) |
ApiController |
Endpoints for every logged-in user: getWizardSteps, tourEvent, tourReached, checklistOpened, tracking events |
LinkController |
A tour's share link, GET /tour/{id}: redirects to the tour's page |
MediaController, MediaUploadController, MediaService |
Images, videos and captions in steps: checked, stripped of metadata, stored in IntroVox's app data, served only to users who get the step |
LicenseController |
An optional subscription key: validation and usage report. Nothing in IntroVox is limited by it |
PersonalController |
Per-user tour preferences (wizard_disabled, tours_disabled) and the user's list of tours for apps |
TourListEmbed |
Lets another app show <introvox-tour-list>: loads its bundle |
TourRepository, TourStateService, TourValidator |
The tours, per-user tour state, and checking a tour before it is stored |
TelemetryService |
Aggregates anonymous usage stats; ships to license server |
LicenseService |
Validates the optional subscription key against licenses.voxcloud.nl |
TelemetryJob |
Background job that ships telemetry every 24 hours, once an admin has been asked |
LicenseUsageJob |
Background job that reports usage daily (with stable jitter) when a subscription key is set |
LoadScripts |
Event listener that loads IntroVox's bootstrap on every page, with the introvox/runtime initial state |
UserMenuEntry |
Event listener that adds Tours to the user menu |
ChecklistWidget |
"Getting started" on the Dashboard (Dashboard API v2) |
AdminSettings / PersonalSettings |
Nextcloud Settings page integration |
See Backend Architecture.
Storage Model¶
| Storage | Use |
|---|---|
oc_appconfig |
Global settings (wizard_enabled, wizard_version); per-language admin overrides of the welcome tour (wizard_steps_<lang>, only present when an admin saved one); the tour index (tours) and the steps of tours for apps (tour_steps_<id>_<lang>); telemetry preferences |
oc_preferences |
Per-user state (introvox/wizard_disabled, tours_disabled, tour_<id>_seen / _completed / _skipped / _reached, checklist_<id>, checklist_uploaded, telemetry timestamps for markUserStarted/Completed/Skipped) |
IntroVox's app data (IAppData) |
Images, videos and captions of steps; JSON backups of the last ten deleted tours |
| Browser localStorage | Frontend-only completion state of the welcome tour (introvox_completed, introvox_version); checked against wizard_version to decide auto-restart |
No custom database tables — IntroVox stays within Nextcloud's standard storage abstractions.
Integration Points¶
Nextcloud Services¶
IntroVox depends on these Nextcloud APIs:
OCP\IConfig— global and per-user configurationOCP\IL10N— translation context (admin/personal UI strings)OCP\L10N\IFactory—findLanguage(null)for raw user-locale detection (v1.7.0+, deliberately bypasses per-app validation that silently rerouted on missing translations),getLanguages()for the override-picker display names, andget('introvox', $lang)to build the auto-translated default tour for any languageOCP\IGroupManager— group membership checks for step filteringOCP\IUserSession— current-user lookupOCP\Support\Subscription\IRegistry—delegateHasValidSubscription()anddelegateHasExtendedSupport(), reported in telemetryOCP\TaskProcessing\IManager—core:text2texttasks for Translate with AI and Write steps with AIOCP\Files\IAppData— IntroVox's own copies of step media, and tour backupsOCP\Dashboard\IAPIWidgetV2— the checklist on the DashboardLoadAdditionalEntriesEvent— Tours in the user menuOCP\App\IAppManager,OCP\INavigationManager— whether a user can open a tour's app, and the apps menu for Where does it start?- Nextcloud Settings sections — admin and personal settings pages
- Background jobs —
TimedJobfor telemetry and the usage report
External Services¶
licenses.voxcloud.nl— telemetry collection, and validation of an optional subscription key (nothing in IntroVox depends on it)
Request Flow: Tour Start¶
Browser IntroVox Frontend IntroVox Backend
│ │ │
│── any page ─────────────────────────────────────────────▶│
│ │ │── LoadScripts: js/main.js,
│ │ │ lazy 'runtime' initial state
│ │ │ (switches, welcome version,
│ │ │ app tours due for this user)
│◀─ page + runtime state ─────────────────────────────────│
│── main.js (small) ──────────▶│ │
│ │── chooseTour(): no tour? │
│ │ stop, no request │
│ │── load 'tour' chunk │
│ │── GET /api/steps │
│ │ (?tour=<id> for an │
│ │ app tour) ───────────▶│
│ │ │── welcome: wizard_steps_<lang>, or the
│ │ │ translated defaults (DefaultStepsService)
│ │ │── app tour: tour_steps_<id>_<lang>;
│ │ │ 404 when it is not for this user
│ │ │── filter by visibleToGroups
│ │◀─ steps[] ───────────────│
│ │── wait for the app │
│ │── Shepherd.start() │
│ │── POST /api/wizard/start │
│ │ or /api/tours/<id>/event ▶│── count it / mark it seen
│◀─ tour appears ──────────────│ │
See Frontend Architecture for the order of the rules in chooseTour().
Security Model¶
- CSRF protection on every route,
GETincluded, since 2.0.0, exceptGET /media/{file}(an<img>or<video>cannot send a token) andGET /tour/{id}(a share link from a mail; it only redirects). v1.5.0 restored it on the state-changing admin endpoints - Defensive admin checks via
IGroupManager::isAdmin()on every admin endpoint, in addition to the framework's annotation-based check - Step HTML is checked on save and import (
StepValidator: known fields, types, lengths) and cleaned when shown:sanitizeStepHtml()(DOMPurify) keeps only basic formatting and links, so imported files and Transifex translations cannot add markup. Up to 1.6.xOCP\Util::sanitizeHTMLescaped it on save;UnescapeLegacyWizardStepHtmlrepairs steps stored that way - Server-side group filtering —
visibleToGroupsis enforced in the API layer; hidden steps are never sent to the client - HTTP response validation on license-server calls —
LicenseServicechecks status codes and JSON shape before trusting responses (v1.5.0+)
Resilience¶
- Defensive
is_array()guard inTourRepository::steps()— ifwizard_steps_<lang>ortour_steps_<id>_<lang>doesn't decode to a JSON array, it counts as no steps, so the backend falls back to defaults rather than crashing - App-menu readiness fallback selectors + 10s timeout (v1.4.2+) — tour won't hang indefinitely if menu selectors don't match
- Steps wait for a missing element — a step whose element isn't there yet waits aside in the bottom right corner with its text (bottom left while a dialog is open), leaves the page usable, and moves to the element once it appears; Next still goes on. Up to 1.7.x such a step was shown centered (v1.4.1+), before that it was skipped
See Also¶
- API Reference — REST endpoints
- Frontend Architecture — Vue 3 + Shepherd.js details
- Backend Architecture — PHP controllers and services
- Transifex Integration — l10n workflow