OpenSana Docs

Convex Backend Architecture

Understand how the Convex schema, functions, and permission model are organized.

The Convex backend is colocated inside apps/web/convex.

Key Ideas

  • schema defines the source of truth for data shape
  • public functions expose the client-facing API
  • internal functions handle server-only workflows
  • permission helpers enforce access rules centrally

Important Rules

  • use indexes instead of .filter()
  • include returns validators on functions
  • use pagination helpers for paginated queries
  • use ConvexError for user-facing errors

Domains

Important backend domains include:

  • tasks
  • task artifacts and attachments
  • organization and project membership
  • CLI sessions, threads, messages, and chunks
  • MCP server request handling

Web App Architecture

A high-level map of the Next.js application and frontend domain boundaries.

MCP Server Architecture

Understand how OpenSana exposes an MCP server over the Convex HTTP layer.

On this page

Key IdeasImportant RulesDomainsRelated Pages