Velt Self Hosting Data Best Practices

Velt Self-Hosting Data Best Practices

Comprehensive implementation guide for Velt's self-hosting data feature in React and Next.js applications. Contains 24 rules across 8 categories, prioritized by impact to guide automated code generation and integration patterns.

When to Apply

Reference these guidelines when:

• Storing sensitive user-generated content on your own infrastructure
• Configuring VeltProvider dataProviders prop for comments, attachments, reactions, recordings, or users
• Choosing between endpoint-based (config) and function-based (custom) data providers
• Building backend API routes to handle Velt data provider requests
• Implementing database storage patterns (MongoDB, PostgreSQL) for Velt data
• Uploading attachments to S3 or other object storage via multipart/form-data
• Debugging data provider events with the dataProvider subscription
• Migrating from Velt-hosted storage to self-hosted storage

Rule Categories by Priority

Quick Reference

1. Core Setup (CRITICAL)

• core-provider-setup — Configure VeltProvider dataProviders prop with correct initialization order
• core-response-format — Return the required response shape from all data provider handlers
• core-auth-provider — Use authProvider on VeltProvider with dataProviders; never call identify()
• core-python-sdk-setup — Install and initialize the Velt Python SDK (velt-py)

2. Comment Data Provider (HIGH)

• comment-endpoint-provider — Use endpoint-based config for comment data provider
• comment-function-provider — Use function-based comment data provider for full control

3. Attachment Data Provider (HIGH)

• attachment-multipart-provider — Handle attachment uploads with multipart/form-data

4. Additional Providers (MEDIUM)

• provider-user-resolver — Implement read-only user data provider for PII protection
• provider-reaction-recording — Configure reaction and recording data providers
• provider-recorder — Self-host recording data and media files
• provider-notification — Self-host notification data for custom notifications
• provider-activity — Self-host activity log data for custom activities (function-based and endpoint-based DataProvider)
• provider-retry-timeout — Configure retry policies and timeouts per data provider

5. Backend Implementation (MEDIUM)

• backend-api-routes — Structure backend API routes for data provider endpoints
• backend-database-patterns — Implement database storage with upsert and proper indexing
• backend-s3-attachments — Store and delete attachments in S3-compatible object storage

6. Data Types (MEDIUM)

• data-types-reference — Self-hosting provider interfaces, config, and request/response type reference (the SDK ↔ backend contract)

7. Python SDK (HIGH)

• python-rest-api-backend — Use sdk.api.* for REST API operations without a database (no MongoDB). Covers the REST services — documents getDocumentsCount, users invitation lifecycle, crdt deleteCrdtData, workspace extensions (domain requests, API key copy/update, advanced webhooks, getApiKeyMetadata), workflow definitions/executions — and the opt-in filter_unknown_fields flag on add/update methods
• python-comments — Comments CRUD via sdk.selfHosting.comments
• python-attachments — Attachment upload and delete via sdk.selfHosting.attachments with S3
• python-users-reactions — Users and reactions management via sdk.selfHosting.users/reactions, PartialReactionAnnotation model, and the v0.1.12 user → from_ rename
• python-frameworks — Django, Flask, and FastAPI integration patterns
• python-token — Generate user auth tokens via sdk.selfHosting.token.getToken for frontend authProvider

8. Debugging (LOW-MEDIUM)

• debug-data-provider-events — Monitor data provider events for troubleshooting

How to Use

Read individual rule files for detailed explanations and code examples:

rules/shared/core/core-provider-setup.md
rules/shared/comment/comment-endpoint-provider.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Source pointers to official documentation

Compiled Documents

• AGENTS.md — Compressed index of all rules with file paths (start here)
• AGENTS.full.md — Full verbose guide with all rules expanded inline