​
Architecture

Everything uses one shared backend for account-bound product state across web, Apple, Android, Windows, and future clients.

​
Backend Boundary

Convex is the product backend and source of truth for users, areas, projects, tasks, devices, sync, AI actions, AI request metadata, and feature flags. Clerk is the identity provider. Clients authenticate with Clerk, then call Convex using the Convex JWT template. Vercel AI SDK calls run inside Convex Node actions. Platform clients call authenticated Convex actions for AI features; provider keys and model routing stay behind the backend boundary.

​
Platform Clients

Platform apps should keep fast local UI state, but durable task data belongs to Convex once the app is signed in. Native stores are treated as caches and migration sources, not independent backends.

​
Data Flow

  1. Client authenticates with Clerk.
  2. Client calls sync.initialize to upsert the user and register the installation.
  3. Existing local records migrate through sync.importSnapshot with stable clientId values.
  4. Ongoing reads use reactive queries, cursor pagination, full-text search, or sync.changes for incremental reconciliation.
  5. Ongoing writes use owner-scoped Convex mutations.
  6. AI flows call authenticated Convex actions, which use Vercel AI SDK and then return drafts, summaries, or created task IDs.

​
External Events

Clerk user lifecycle events are delivered to the Convex HTTP webhook. The webhook verifies Svix signatures before upserting or soft-deleting the user record.

​
Maintenance

Convex cron jobs run internal maintenance functions. The current daily jobs purge old sync journal entries and AI request metadata after their retention windows.