Skip to content

convex-components-guide.md

Latest commit

 

History

History
252 lines (162 loc) · 8.05 KB

convex-components-guide.md

File metadata and controls

252 lines (162 loc) · 8.05 KB
Raw

Convex Components & Architecture Patterns

Convex is a backend-as-a-service (BaaS) platform designed to make it easy to build full-stack reactive applications with minimal setup. It combines a real-time database, serverless functions, and authentication, all managed within a TypeScript-first developer experience.

🔧 Core Features

  1. Reactive Database

    • Document-based (like Firebase or MongoDB)
    • All queries are reactive: clients auto-update on data change
    • Queries written in TypeScript, securely executed from client

  2. Serverless Functions

    • Write logic with query() and mutation() in TypeScript
    • Fully managed environment, async and npm-ready

  3. Authentication

    • Built-in support for GitHub, Google, JWT, etc.
    • Access control via roles and TypeScript logic

  4. Real-time React Integration

    • Use hooks like useQuery() and useMutation()
    • Automatic reactivity without polling

  5. File Storage

    • Upload and serve files via Convex's native file API

✅ Benefits

  • Full-stack in one repo — unified client + server code
  • Type safety everywhere — auto-inferred TypeScript types
  • Live collaboration — perfect for reactive shared UIs
  • Zero backend ops — no infrastructure to manage

🧠 Ideal Use Cases

  • Collaborative tools (whiteboards, CRMs)
  • Real-time dashboards
  • AI assistants and agents with UIs
  • Internal tools
  • MVPs and fast-moving startups

🧰 Developer Experience

  • CLI: npx convex dev, convex deploy
  • File-based routing in convex/functions/
  • Hot reload and codegen

🧪 Example Tech Stack with Convex

  • Frontend: React (with Tailwind, ShadCN)
  • Backend: Convex (queries, mutations, auth)
  • DB: Convex Reactive DB
  • Hosting: Vercel / Netlify
  • AI: OpenAI / Langchain / OpenRouter APIs

🧱 Convex Component Patterns & Examples

1. Retrieval-Augmented Generation (RAG)

  • Store text chunks in Convex.
  • Use external embedding (e.g., OpenAI) for vector search.
  • Query relevant data to enrich LLM prompts.

2. Agent State Management

  • Agents persist state and memory in Convex.
  • Store thoughts, actions, decisions, or queued tasks.
  • Useful for multi-agent orchestration.

3. Workflow Engine

  • Track user or system state across steps.
  • Implement UI wizards, multi-step processes, or backend orchestration.

4. RESEND Integration

  • Use action() to send transactional emails via Resend.
  • Templates and metadata stored in Convex DB.

5. Rate Limiter

  • Log actions per user/IP in a rate_limit_log table.
  • Throttle usage based on time windows.

6. Presence Tracking

  • Store online status and activity with periodic heartbeat mutations.
  • Clean stale users via CRON or TTL.

7. Shard Counter

  • Distribute counter writes across documents.
  • Reduce write contention for high-frequency actions.

8. Aggregates

  • Pre-compute totals or metrics on write or via CRON.
  • Store in aggregates table for fast retrieval.

9. Geo Spatial

  • Store lat/lng coordinates.
  • Filter using bounding box or Haversine formula in query().

10. Collaborative State

  • Real-time data syncing between clients using useQuery().
  • Ideal for shared editors, dashboards, or Kanban boards.

11. Text Sync

  • Implement collaborative editors.
  • Use patching or CRDT integration (e.g., Y.js, Automerge).

12. Twilio Integration

  • Use action() to trigger SMS, voice, or calls.
  • Store Twilio credentials in Convex secrets.

13. Action Cache

  • Cache expensive results (e.g., LLM outputs or API calls).
  • Store and reuse if recent.

🧮 Component Summary Table

Component Type Native or Pattern Convex Usage
RAG Pattern External support Store + query chunks, external embeddings
AGENT Pattern Custom Stateful logic via mutation() + orchestration
Workflow Pattern Native + Custom Multi-step flow via state tracking in DB
RESEND Integration External API Send emails via action() using Resend
RateLimiter Pattern Custom Track usage in DB, check on each request
Presence Pattern Custom Heartbeat + user state updates
CRON Feature Native Schedule tasks like cleanup, reminders
Shard Counter Pattern Custom Split counter writes across multiple docs
Aggregates Pattern Custom Precompute and store stats via mutation or CRON
Geo Spatial Pattern Custom Manual bounding box or Haversine checks
Collaborative Pattern Built-in friendly Real-time synced state via useQuery()
Text Sync Pattern External + Custom CRDT/OT integration or patch model
Twilio Integration External API SMS/call API via action()
Action Cache Pattern Custom Store API result in DB to prevent redundant calls

🧠 Pro Tips for Power Users

  • Keep functions modular: Extract logic into helpers to reuse across queries/mutations.
  • Use action() only for side effects: Never access Convex DB from action()—use mutation() instead.
  • Cache external calls: Store expensive API/LLM results to reduce latency and cost.
  • Enable real-time debugging: Use admin-only logs or metadata capture for audit/debug workflows.
  • Pair with AI tools: Store prompts, outputs, and feedback for fine-tuning and diagnostics.
  • Simulate queues and delays: Combine CRON + timestamps for task scheduling without true queues.

Additional Patterns & Utilities

Session & Auth Metadata

  • Extend session objects with onboarding or billing metadata.

Temporal Logic

  • Schedule tasks via CRON and timestamps.
  • Simulate delays or expiry windows.

Webhook Listener

  • Handle external webhooks via action().
  • Persist events and trigger downstream flows.

Settings & Feature Flags

  • Store per-user or global flags in a settings table.
  • Toggle features dynamically.

Stripe Billing

  • Handle Stripe webhooks and store subscription data.
  • Sync feature access with Convex roles/fields.

Job Queues

  • Store jobs in DB and process with CRON.
  • Mark status: pending, processing, done, failed.

Audit & Event Logs

  • Track system and user actions.
  • Include metadata for compliance or debugging.

Notification System

  • Store and serve real-time in-app alerts.
  • Extend with Resend or Twilio for multi-channel support.

Chat Threads

  • Store messages and participants.
  • Support real-time threaded conversations.

Agent Memory Store

  • Structured memory (facts, chat logs, serialized context).
  • Used to reconstruct prompts or plan next actions.

Schema-less Meta Store

  • Use JSON blobs for flexible schema needs.
  • Good for dynamic forms or user-generated config.

Encrypted or Redacted Fields

  • Protect sensitive data with role-based access.
  • Mask or encrypt fields based on context.

Ecosystem & Tooling

Tool Use Case
Convex DevTools Live inspect DB, queries, and mutations
Convex Playground Test backend functions interactively
CLI Codegen Generate type-safe hooks and definitions
Convex + Vercel/Fly Full-stack hosting integrations
Convex Secrets Store API keys securely
Convex on Fly.io Run your own edge-based infra (optional)

This document serves as a flexible blueprint for designing high-performance, real-time applications using Convex. Whether building solo tools, collaborative systems, or AI agents, these patterns offer a scalable starting point.