Architectuur-overzicht¶
Dit document geeft een technisch overzicht van IntroVox' architectuur voor architecten, ontwikkelaars en IT-besluitvormers.
Systeem-overzicht¶
IntroVox is een Nextcloud-app die de standaard Nextcloud-app-architectuur volgt: een PHP-backend die REST-endpoints exposed, een Vue-3-frontend gebundeld met webpack, en staat opgeslagen in Nextcloud's appconfig- en preferences-tabellen.
┌──────────────────────────────────────────────────────────────┐
│ 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 gebruiker) │ │ │
│ │ │ (wizard_*) │ │ (wizard_*, tours_*, tour_*) │ │ │
│ │ └────────────┘ └───────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
│
▼
licenses.voxcloud.nl
(telemetrie + optionele abonnementssleutel)
Kerncomponenten¶
Frontend (Vue 3 + Shepherd.js)¶
| Component | Verantwoordelijkheid |
|---|---|
src/main.js |
Kleine bootstrap op elke Nextcloud-pagina: beslist of er een tour draait (src/runtime/chooseTour.mjs) en laadt pas dan de tour-code |
src/runtime/tour.js |
De tour-chunk: mount WizardManager; alleen geladen op een pagina waar een tour draait |
src/admin.js |
Admin-instellingen-UI-entry-point |
src/personal.js |
Persoonlijke-instellingen-UI-entry-point |
src/embed/embed.js |
<introvox-tour-list> voor andere apps: de tours die een gebruiker kan starten, als kale links die de andere app zelf stijlt |
src/components/WizardManager.vue |
Beheert Shepherd.js-tour-levenscyclus en stap-rendering, voor de welkomsttour en tours voor apps |
src/admin/ToursList.vue, src/admin/NewTourDialog.vue |
Het paneel Tours van de beheerder: de lijst met tours, en een tour voor een app maken of wijzigen |
src/admin/TourEditor.vue, src/admin/StepWizard.vue |
De stappen van één tour, en de dialoog die een stap bewerkt, met de teksteditor en de media (StepTextEditor.vue, StepMediaBlock.vue) |
src/components/SupportSettings.vue |
Het paneel Support: over IntroVox, links, en Show the admin tour again |
src/components/wizardSteps.js |
Default-stap-definities gewrapped in t('introvox', ...), en de helpers die het element van een stap zoeken en erop wachten |
Technologie-stack: Vue 3 (Composition API), webpack, Shepherd.js, @nextcloud/vue.
Backend (PHP)¶
| Component | Verantwoordelijkheid |
|---|---|
AdminController |
Admin-CRUD voor de stappen van elke tour, talen, instellingen; export/import |
ToursController |
Admin: de tours zelf (lijst, aanmaken, wijzigen, verwijderen, opnieuw tonen, statistieken, exporteren en importeren) |
AssistantController, TourAssistant |
Admin: een tour vertalen en stappen laten schrijven met de Nextcloud Assistant (OCP\TaskProcessing) |
ApiController |
Endpoints voor elke ingelogde gebruiker: getWizardSteps, tourEvent, tourReached, checklistOpened, tracking-events |
LinkController |
De deellink van een tour, GET /tour/{id}: stuurt door naar de pagina van de tour |
MediaController, MediaUploadController, MediaService |
Afbeeldingen, video's en ondertitels in stappen: gecontroleerd, ontdaan van metadata, opgeslagen in de app-data van IntroVox, alleen geserveerd aan gebruikers die de stap krijgen |
LicenseController |
Een optionele abonnementssleutel: validatie en gebruiksrapport. Niets in IntroVox wordt erdoor beperkt |
PersonalController |
Per-gebruiker-tour-voorkeuren (wizard_disabled, tours_disabled) en de lijst met tours voor apps van de gebruiker |
TourListEmbed |
Laat een andere app <introvox-tour-list> tonen: laadt de bundle ervan |
TourRepository, TourStateService, TourValidator |
De tours, per-gebruiker-tour-staat, en een tour controleren voor hij wordt opgeslagen |
TelemetryService |
Aggregeert anonieme gebruiks-stats; verzendt naar licentie-server |
LicenseService |
Valideert de optionele abonnementssleutel tegen licenses.voxcloud.nl |
TelemetryJob |
Background-job die telemetrie elke 24 uur verzendt, zodra een beheerder de vraag gezien heeft |
LicenseUsageJob |
Background-job die dagelijks (met stabiele jitter) het gebruik rapporteert als er een abonnementssleutel is |
LoadScripts |
Event-listener die IntroVox' bootstrap op elke pagina laadt, met de initial state introvox/runtime |
UserMenuEntry |
Event-listener die Tours aan het gebruikersmenu toevoegt |
ChecklistWidget |
"Getting started" op het Dashboard (Dashboard-API v2) |
AdminSettings / PersonalSettings |
Nextcloud-Settings-pagina-integratie |
Zie Backend-architectuur.
Opslag-model¶
| Opslag | Gebruik |
|---|---|
oc_appconfig |
Globale instellingen (wizard_enabled, wizard_version); per-taal-overrides van de welkomsttour (wizard_steps_<lang>, alleen als een beheerder er een heeft opgeslagen); de tour-index (tours) en de stappen van tours voor apps (tour_steps_<id>_<lang>); telemetrie-voorkeuren |
oc_preferences |
Per-gebruiker-staat (introvox/wizard_disabled, tours_disabled, tour_<id>_seen / _completed / _skipped / _reached, checklist_<id>, checklist_uploaded, telemetrie-timestamps voor markUserStarted/Completed/Skipped) |
App-data van IntroVox (IAppData) |
Afbeeldingen, video's en ondertitels van stappen; JSON-back-ups van de laatste tien verwijderde tours |
| Browser-localStorage | Alleen-frontend voltooiings-staat van de welkomsttour (introvox_completed, introvox_version); gecheckt tegen wizard_version om auto-restart te beslissen |
Geen custom database-tabellen — IntroVox blijft binnen Nextcloud's standaard opslag-abstracties.
Integratie-punten¶
Nextcloud-services¶
IntroVox is afhankelijk van deze Nextcloud-APIs:
OCP\IConfig— globale en per-gebruiker-configuratieOCP\IL10N— gebruikers-taal-detectie en vertalingOCP\IGroupManager— groep-lidmaatschap-checks voor stap-filteringOCP\IUserSession— current-user-lookup- DOMPurify (frontend) — schoont stap-HTML op bij het tonen (
src/utils/stepHtml.js) OCP\Support\Subscription\IRegistry—delegateHasValidSubscription()endelegateHasExtendedSupport(), gemeld in de telemetrieOCP\TaskProcessing\IManager—core:text2text-taken voor Translate with AI en Write steps with AIOCP\Files\IAppData— de eigen kopieën van media in stappen, en back-ups van toursOCP\Dashboard\IAPIWidgetV2— de checklist op het DashboardLoadAdditionalEntriesEvent— Tours in het gebruikersmenuOCP\App\IAppManager,OCP\INavigationManager— of een gebruiker de app van een tour kan openen, en het apps-menu voor Where does it start?OCP\L10N\IFactory— taal-display-naam-auto-discovery (v1.6.0+)- Nextcloud-Settings-secties — admin- en persoonlijke-instellingen-pagina's
- Background-jobs —
TimedJobvoor telemetrie en het gebruiksrapport
Externe services¶
licenses.voxcloud.nl— telemetrie-verzameling, en validatie van een optionele abonnementssleutel (niets in IntroVox hangt ervan af)
Request-flow: tour-start¶
Browser IntroVox-frontend IntroVox-backend
│ │ │
│── elke pagina ──────────────────────────────────────────▶│
│ │ │── LoadScripts: js/main.js,
│ │ │ luie 'runtime'-initial-state
│ │ │ (schakelaars, welkomstversie,
│ │ │ app-tours die klaarstaan)
│◀─ pagina + runtime-state ───────────────────────────────│
│── main.js (klein) ──────────▶│ │
│ │── chooseTour(): geen │
│ │ tour? stop, geen request│
│ │── laad 'tour'-chunk │
│ │── GET /api/steps │
│ │ (?tour=<id> voor een │
│ │ app-tour) ───────────▶│
│ │ │── welkomst: wizard_steps_<lang>, of de
│ │ │ vertaalde standaard (DefaultStepsService)
│ │ │── app-tour: tour_steps_<id>_<lang>;
│ │ │ 404 als hij niet voor deze gebruiker is
│ │ │── filter op visibleToGroups
│ │◀─ steps[] ───────────────│
│ │── wacht op de app │
│ │── Shepherd.start() │
│ │── POST /api/wizard/start │
│ │ of /api/tours/<id>/event ▶│── tellen / als gezien markeren
│◀─ tour verschijnt ───────────│ │
Zie Frontend-architectuur voor de volgorde van de regels in chooseTour().
Beveiligings-model¶
- CSRF-bescherming op elke route, ook
GET, sinds 2.0.0, behalveGET /media/{file}(een<img>of<video>kan geen token meesturen) enGET /tour/{id}(een deellink uit een mail; stuurt alleen door). v1.5.0 herstelde haar op de state-changing admin-endpoints - Defensieve admin-checks via
IGroupManager::isAdmin()op elk admin-endpoint, naast de framework-annotation-based check - Stap-HTML wordt bij opslaan en importeren gecontroleerd (
StepValidator: bekende velden, types, lengtes) en bij tonen opgeschoond:sanitizeStepHtml()(DOMPurify) laat alleen eenvoudige opmaak en links over, zodat geïmporteerde bestanden en Transifex-vertalingen geen markup kunnen toevoegen. Tot en met 1.6.x escapeteOCP\Util::sanitizeHTMLhet bij opslaan;UnescapeLegacyWizardStepHtmlherstelt stappen die zo zijn opgeslagen - Server-side groep-filtering —
visibleToGroupswordt afgedwongen op de API-laag; verborgen stappen worden nooit naar de client gestuurd - HTTP-response-validatie op licentie-server-calls —
LicenseServicecheckt statuscodes en JSON-shape voor responses te vertrouwen (v1.5.0+)
Veerkracht¶
- Defensieve
is_array()-guard inTourRepository::steps()— alswizard_steps_<lang>oftour_steps_<id>_<lang>niet decodeert naar een JSON-array, telt het als geen stappen, en valt de backend terug op defaults in plaats van crashen - App-menu-readiness-fallback-selectors + 10s-timeout (v1.4.2+) — tour blijft niet oneindig hangen als menu-selectors niet matchen
- Stappen wachten op een ontbrekend element — een stap waarvan het element er nog niet is, wacht met zijn tekst rechtsonder opzij (linksonder zolang er een venster open is), laat de pagina bruikbaar en schuift naar het element zodra het verschijnt; Next gaat gewoon verder. Tot en met 1.7.x werd zo'n stap gecentreerd getoond (v1.4.1+), daarvoor overgeslagen
Zie ook¶
- API-referentie — REST-endpoints
- Frontend-architectuur — Vue 3 + Shepherd.js-details
- Backend-architectuur — PHP-controllers en -services
- Transifex-integratie — l10n-workflow