Documentation Index
Fetch the complete documentation index at: https://docs.opensync.dev/llms.txt
Use this file to discover all available pages before exploring further.
Convex Backend
OpenSync’s entire backend runs on Convex. There is no separate server, no Docker containers, and no infrastructure to manage. Convex provides the database, serverless functions, real-time subscriptions, HTTP endpoints, file storage, and scheduled jobs.
One-click deploy
The fastest way to set up the backend:
This creates:
- A new Convex project linked to your account
- All database tables with their schemas and indexes
- Serverless functions for queries, mutations, and actions
- HTTP endpoints for the sync API (
/sync/session, /sync/message, /sync/batch, /search, etc.)
- Search indexes for full-text search
- Vector indexes for semantic search
- Scheduled function support for background embedding generation
Manual deploy
1. Install the Convex CLI
2. Clone and initialize
git clone https://github.com/waynesutton/opensync
cd opensync
npm install
npx convex dev
- Sign in to your Convex account (or create one).
- Create a new project.
- Push the schema, functions, and indexes.
npx convex dev runs in watch mode. It pushes changes to your development deployment every time you save a file in the convex/ directory.
3. Set environment variables
npx convex env set WORKOS_API_KEY sk_your_key
npx convex env set WORKOS_CLIENT_ID client_your_id
npx convex env set OPENAI_API_KEY sk-your-key # Optional, for semantic search
4. Deploy to production
This pushes your functions and schema to the production deployment. Production deployments have a separate URL from development.
Database schema
The Convex backend defines these tables:
| Table | Purpose | Key fields |
|---|
users | User accounts | workosId, email, name, apiKey |
sessions | AI coding sessions | userId, externalId, source, model, totalTokens, cost |
messages | Messages within sessions | sessionId, externalId, role, textContent |
parts | Message content blocks | messageId, type (text, tool-call, tool-result) |
sessionEmbeddings | Vector embeddings for sessions | sessionId, embedding (1536-dim), textHash |
messageEmbeddings | Vector embeddings for messages | messageId, embedding (1536-dim) |
apiLogs | API request logs | userId, endpoint, statusCode |
dailyWrapped | Daily activity summaries | userId, date, stats |
docPages | Documentation page metadata | slug, title, content |
docEmbeddings | Documentation search embeddings | docPageId, embedding |
Indexes
Key indexes defined in the schema:
| Table | Index | Fields | Purpose |
|---|
sessions | by_user | userId | List sessions for a user |
sessions | by_user_external | userId, externalId | Dedup during sync |
sessions | by_user_and_source | userId, source | Filter by tool |
messages | by_session | sessionId | List messages in a session |
messages | by_external_id | externalId | Dedup during sync |
sessions.searchableText. Vector indexes enable cosine similarity search on sessionEmbeddings.embedding.
HTTP endpoints
The sync API is defined in convex/http.ts. These are the endpoints that plugins call:
| Endpoint | Method | Purpose |
|---|
/sync/session | POST | Create or update a session |
/sync/message | POST | Create or update a message |
/sync/batch | POST | Bulk sync sessions and messages |
/search | POST | Full-text, semantic, or hybrid search |
/health | GET | Health check (no auth required) |
/api/sessions | GET | List sessions |
/api/sessions/:id | GET | Get session with messages |
/api/export | GET | Export sessions in eval formats |
/api/context | GET | Get context for RAG |
/health require an Authorization: Bearer osk_... header.
Convex dashboard
Access your project at dashboard.convex.dev:
- Data tab: Browse and edit documents in any table
- Functions tab: See all deployed functions, their execution logs, and errors
- Logs tab: Real-time function execution logs with timing and error details
- Settings tab: Environment variables, deployment URLs, and project configuration
Scaling
Convex handles scaling automatically:
| Aspect | How it scales |
|---|
| Functions | Scale to zero when idle, scale up under load |
| Database | Storage grows with usage, no provisioning needed |
| Real-time | WebSocket connections managed by Convex infrastructure |
| HTTP endpoints | Handle concurrent requests without configuration |
Monitoring
Function logs
Check dashboard.convex.dev > Logs for:
- Function execution times
- Error stack traces
- Write conflict retries
- Scheduled function results
Common issues
Write conflicts: If you see retry logs for mutations, check the write conflict patterns documentation. OpenSync’s mutations are designed to be idempotent, but rapid syncing from multiple plugins can occasionally trigger retries.
Slow queries: Queries that scan many documents without using an index will be slow. All OpenSync queries use indexes by design, but custom modifications should follow the same pattern.
Next steps
