Overview

• Velt keeps the structural / non-PII data — IDs, document and organization references, locations and targets, statuses, timestamps, and relationships. This is what Velt needs to position pins, thread comments, drive real-time sync, and render the UI shell.
• You keep the content / PII — comment text, user information, transcripts, attachment files, and any custom fields — inside your own database and/or file storage.

​

How it works

• On write (a comment is added, a recording is saved, …): Velt strips the PII out of the record, writes only the structural remainder to Velt’s database, and hands the stripped PII to your provider to persist.
• On read (loading a document, receiving a real-time update, …): Velt calls your provider to fetch the PII back, then merges it into the structural record so the UI renders exactly as it would in a fully Velt-hosted setup.

​

Supported features at a glance

​

Registering data providers

const dataProviders = {
  comment:       commentDataProvider,
  reaction:      reactionDataProvider,
  recorder:      recorderDataProvider,
  notification:  notificationDataProvider,
  activity:      activityDataProvider,
  attachment:    attachmentDataProvider,
  anonymousUser: anonymousUserDataProvider,
  user:          userDataProvider,
};

<VeltProvider
  apiKey='YOUR_API_KEY'
  dataProviders={dataProviders}
>
</VeltProvider>

await Velt.setDataProviders({
  comment:       commentDataProvider,
  reaction:      reactionDataProvider,
  recorder:      recorderDataProvider,
  notification:  notificationDataProvider,
  activity:      activityDataProvider,
  attachment:    attachmentDataProvider,
  anonymousUser: anonymousUserDataProvider,
  user:          userDataProvider,
});

​

Two ways to implement: callback or URL

• Callback function — implement the method directly in your frontend code.
• Config URL — point Velt at an HTTP endpoint (config.getConfig.url, config.saveConfig.url, config.deleteConfig.url) and Velt makes the request for you.

​

Async headers and credentials

const getFreshToken = async () => {
  const response = await fetch('/api/velt/resolver-token');
  const { token } = await response.json();
  return token;
};

const commentResolverConfig = {
  saveConfig: {
    url: 'https://your-backend.com/api/velt/comments/save',
    headers: async () => ({ Authorization: `Bearer ${await getFreshToken()}` }),
    credentials: 'include'
  }
};

const commentDataProvider = {
  config: commentResolverConfig
};

<VeltProvider
  apiKey='YOUR_API_KEY'
  dataProviders={{ comment: commentDataProvider }}
>
</VeltProvider>

const getFreshToken = async () => {
  const response = await fetch('/api/velt/resolver-token');
  const { token } = await response.json();
  return token;
};

const commentResolverConfig = {
  saveConfig: {
    url: 'https://your-backend.com/api/velt/comments/save',
    headers: async () => ({ Authorization: `Bearer ${await getFreshToken()}` }),
    credentials: 'include'
  }
};

const commentDataProvider = {
  config: commentResolverConfig
};

Velt.setDataProviders({ comment: commentDataProvider });

​

The provider contract

​

config (ResolverConfig)

​

Response shape (ResolverResponse)

interface ResolverResponse<T> {
  data?:       T;        // the resolved payload (for `get`); omit for save/delete
  success:     boolean;
  statusCode:  number;   // 200 = success; anything else is treated as a failure
  message?:    string;
  timestamp?:  number;
}

​

HTTP endpoint contract (URL style)

• A POST to your url
• Content-Type: application/json plus any headers you supplied
• A request body equal to the JSON request object for that operation (the same object your callback would receive)

​

Metadata your provider receives

{ apiKey, documentId, organizationId, folderId? }   // folderId only when present

​

Per-feature reference

​

Complete field inventory

• User objects are reduced to { userId } in Velt’s DB for most features (comments, recordings, activity). The full user object (name, email, avatar, …) lives in your backend, resolved via your user provider. It is the data source that all the other resolvers rely on when they strip user objects down to { userId }.
• The client-facing metadata (see above) accompanies every PII payload you store.
• Velt sets an internal flag on the structural record (e.g., isCommentResolverUsed, isReactionResolverUsed, isRecorderResolverUsed, isNotificationResolverUsed, isActivityResolverUsed) so the UI knows to wait for resolver data. You don’t need to store these.

​

Attachment & recording storage

​

Storage scopes

await Velt.setDataProviders({
  // Comment attachments → YOUR storage
  attachment: {
    async save({ file, name, metadata }) {
      const url = await myBucket.put(file, name);
      return { data: { url }, success: true, statusCode: 200 };
    },
    async delete({ attachmentId, metadata }) {
      await myBucket.remove(attachmentId);
      return { success: true, statusCode: 200 };
    },
  },

  // Recording metadata → YOUR DB, and recording FILES → YOUR storage
  recorder: {
    async get(req)    { /* … */ },
    async save(req)   { /* … */ },
    async delete(req) { /* … */ },
    storage: {
      async save({ file, name }) {
        const url = await myBucket.put(file, name);
        return { data: { url }, success: true, statusCode: 200 };
      },
      async delete({ attachmentId }) {
        await myBucket.remove(attachmentId);
        return { success: true, statusCode: 200 };
      },
    },
  },
});

​

The upload contract (storage providers)

interface ResolverAttachment {
  attachmentId: number;
  file: File;                          // the raw bytes
  name?: string;
  mimeType?: string;
  metadata?: AttachmentResolverMetadata;
}
// You return: { data: { url }, success: true, statusCode: 200 }

• a file part containing the raw file, and
• a request part containing JSON: { attachment: { attachmentId, name, mimeType }, metadata, event }.

​

How recording files are uploaded

​

Excluding & extending fields

const commentDataProvider = {
  config: {
    fieldsToRemove:   ['internalTicketId', 'priorityScore'],   // move OUT of Velt's DB
    additionalFields: ['teamName'],                            // copy to your DB, keep in Velt's
  },
  async get(req)    { /* … */ },
  async save(req)   { /* … */ },
  async delete(req) { /* … */ },
};

• fieldsToRemove — data sovereignty (move). Each listed field is copied into the payload sent to your backend and deleted from Velt’s database. On read, Velt restores the field from your backend and merges it back into the record. Use this when a custom field must not be stored by Velt at all. Reaction, recorder, and activity providers move fields when their value is anything other than undefined, including 0, false, and ""; the comment provider’s existing path remains truthy-gated.
• additionalFields — replication (copy). Each listed field is deep-copied into the payload sent to your backend, but kept in Velt’s database. On read there is nothing to merge (the field is already present). Use this when you want a copy of a field in your own backend (e.g., for analytics or search) without removing it from Velt.

​

Where these are supported

​

Worked example

await Velt.setDataProviders({
  comment: {
    config: { fieldsToRemove: ['priorityScore'] },
    async get({ commentAnnotationIds, documentIds, organizationId }) {
      const rows = await db.comments.find({ organizationId, documentIds, commentAnnotationIds });
      const data = {};
      for (const r of rows) {
        // r.partial already includes priorityScore — Velt merges it back in
        data[r.annotationId] = r.partial;
      }
      return { data, success: true, statusCode: 200 };
    },
    async save({ commentAnnotation }) {
      // each PartialCommentAnnotation here includes priorityScore
      await db.comments.upsertMany(commentAnnotation);
      return { success: true, statusCode: 200 };
    },
    async delete({ commentAnnotationId }) {
      await db.comments.remove(commentAnnotationId);
      return { success: true, statusCode: 200 };
    },
  },
});

​

Operational behavior

• Timeouts. Reads are wrapped in a timeout (default 1 minute, configurable via config.resolveTimeout). On timeout, Velt proceeds gracefully and renders whatever structural data it already has — it never blocks the UI indefinitely.
• Retries. retryCount / retryDelay let you retry transient failures. Combine with revertOnFailure to roll back Velt’s optimistic local change if your save/delete ultimately fails.
• Degrade, don’t drop. If resolution fails, Velt keeps the structural record and renders it without the PII rather than dropping it. Your data is never lost because a resolver call failed.
• Not every update calls save. Velt only sends a save when the PII actually changed and the action maps to a meaningful resolver event (add/update/delete of the comment body, etc.). Pure structural changes (status, priority, assignment) are handled by Velt and won’t necessarily call your save.
• Custom notifications only. The notification resolver applies only to notifications whose source is custom. Standard comment/recording notifications are resolved through their own feature providers. See Notifications.
• Cross-organization notifications. “For You” notifications can come from organizations other than the active one. Velt calls your notification/comment get endpoints with each entry’s own organizationId — make sure your endpoints honor the organizationId in the request rather than assuming the current org.
• Activity is multi-feature. A single activity record may contain PII owned by several providers. Velt resolves them in sequence (user → comment → reaction → recorder → activity), so register all relevant providers for activity feeds to render fully.

​

Backend implementation

​

End-to-end example

// Callback style
await Velt.setDataProviders({
  comment: {
    config: { fieldsToRemove: ['internalTicketId'] },
    async get({ organizationId, documentIds, commentAnnotationIds }) {
      const data = await myApi.getComments({ organizationId, documentIds, commentAnnotationIds });
      return { data, success: true, statusCode: 200 };
    },
    async save({ commentAnnotation, metadata, event }) {
      await myApi.saveComments(commentAnnotation, metadata, event);
      return { success: true, statusCode: 200 };
    },
    async delete({ commentAnnotationId, metadata }) {
      await myApi.deleteComment(commentAnnotationId, metadata);
      return { success: true, statusCode: 200 };
    },
  },
});

// URL style — same shape, expressed as endpoints
await Velt.setDataProviders({
  comment: {
    config: {
      fieldsToRemove: ['internalTicketId'],
      getConfig:    { url: 'https://api.example.com/velt/comments/get' },
      saveConfig:   { url: 'https://api.example.com/velt/comments/save' },
      deleteConfig: { url: 'https://api.example.com/velt/comments/delete' },
    },
  },
});

​

Debugging

import { useVeltClient } from '@veltdev/react';

const { client } = useVeltClient();

useEffect(() => {
  if (!client) return;

  const subscription = client.on('dataProvider').subscribe((event) => {
    console.log('Data Provider Event:', event);
    console.log('Module Name:', event.moduleName);
  });

  return () => subscription?.unsubscribe();
}, [client]);

const subscription = Velt.on('dataProvider').subscribe((event) => {
  console.log('Data Provider Event:', event);
  console.log('Module Name:', event.moduleName);
});

// Unsubscribe when done
subscription?.unsubscribe();