Concept & Architecture

Structure Overview

Welcome to Pluvo's API documentation. This document provides an overview of the key concepts and underlying structure of the Pluvo platform. It is intended as a starting point for developers building integrations or synchronizing data with Pluvo.

Core Concepts

Users

Participants, trainers, or managers — anyone who interacts with Pluvo is a User. Users have roles, belong to groups, and can carry additional metadata via ExtraCategory values.

Key identifiers:

• id — Pluvo's internal UUID (stable, unique)
• ref — Your external identifier (set by you, unique per entity type)
• email — Unique per organization

Groups

Organizational units that group users. Groups determine access to trainings and can have their own managers. Users can be both a participant and a manager in different groups.

Trainings (Learning Journeys)

A Training is what users see as a "learning journey" in the interface. It contains courses, modules, events, and progress rules. Trainings can be linked to offers for enrollment.

Offers & Enrollment

An Offer is the overarching enrollment offering. An OfferEvent is a specific entry point (e.g., a start date or cohort). Users enroll in an OfferEvent, not directly in a training.

Flow: Offer → OfferEvent (with dates) → Enrollment → linked Training

Portfolio & Results

A PortfolioItem stores evidence, achievements, or certificates linked to a user. PortfolioReport is an advanced query for analyzing progress, scores, and time spent across users and trainings.

Courses & Modules

Within a Training you'll find content organized in module groups and modules. These contain e-learning content such as videos, theory, assignments, quizzes, or external LTI modules.

Extra Categories

Custom fields that can be attached to users, groups, trainings, offers, and other entities. These allow you to store additional metadata like department, job title, or any organization-specific data.

Certificates

Templates that can be issued to users upon completion. Certificates automatically create a PortfolioItem when generated.

Webhooks

Pluvo can push events to your system via HTTP POST. Events cover user lifecycle, training completion, enrollment changes, portfolio updates, and more.

Architecture

The Pluvo API is built as a GraphQL API. Key features:

• Single endpoint — All queries and mutations go to /graphql/
• Typed schema — Every object has a well-defined type with specific fields
• Ref fields — Most objects support a ref field for external system mapping
• Relay-style pagination — List queries use edges/node pattern with cursor-based pagination
• Webhook security — All webhooks include HMAC signature verification via headers

Data Model

Organisation
├── Users (with roles: participant, trainer, manager)
├── Groups (with participants and managers)
├── Trainings (learning journeys)
│   ├── Courses (e-learning content)
│   │   └── Modules (videos, theory, assignments, quizzes)
│   └── Events (module groups with conditions)
├── Offers (enrollment offerings)
│   └── OfferEvents (specific entry points with dates)
│       └── Enrollments (user ↔ event link)
├── Extra Categories (custom fields per entity type)
├── Certificates (templates, issued to users)
└── Portfolio Items (achievements, evidence, certificates)

Interaction Flows

User onboarding:

Create user → Add to group → Enroll in offer event → User accesses training

Course completion:

User completes course → Portfolio item created → Certificate issued → Webhook fired

Data sync (HRM integration):

External system → updateOrCreateUser → updateExtraCategoryValues → addUsersToGroup

Recommended Patterns

• Use updateOrCreateUser for robust user synchronization — it handles both creation and updates in a single call.
• Use ref fields to map Pluvo objects to your external system IDs.
• Archive instead of deleting (archiveUsers, archiveOffers, etc.) — most entities do not support hard deletes.
• Use PortfolioReport for evaluation and reporting — it supports advanced filtering by score, progress, completion, and date ranges.
• Use webhooks to react to changes instead of polling the API.
• Avoid direct dependency on UI names; work with ref, id, and contentType.