Convex Backend API Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• pkg/convex/schema.ts
• pkg/convex/projects.ts
• pkg/convex/project_variables.ts
• pkg/convex/_generated/server.d.ts
• pkg/convex/lib/auth.ts

Introduction

The Barekey backend is built entirely on Convex, a Backend-as-a-Service (BaaS) that serves as both the application server and the database. This architecture eliminates the need for a traditional separate API server, with the frontend React application connecting directly to Convex via a WebSocket-based ConvexReactClient.

The backend is responsible for managing encrypted environment variables (secrets) for developer teams, handling organization-scoped project lifecycles, and implementing multi-layer encryption. All backend logic resides in the pkg/convex/ directory, structured into functional modules such as authentication, project management, and vault operations.

Sources: AGENTS.md:14-25, AGENTS.md:32-42

Core Function Types

Convex functions are categorized by their access levels and capabilities. The Barekey implementation strictly follows these definitions to ensure data integrity and security.

Function Type	Description	Access Level
query	Read-only functions exposed to the public API/client.	Public
mutation	Functions that can modify the database; exposed to the client.	Public
action	Side-effectful functions for calling third-party services or Node.js built-ins.	Public
internalQuery	Private read-only functions accessible only by other Convex functions.	Internal
internalMutation	Private write functions accessible only by other Convex functions.	Internal

Sources: pkg/convex/_generated/server.d.ts:25-88, AGENTS.md:144-150

Data Modeling and Schema

The Barekey schema is defined in pkg/convex/schema.ts. It utilizes a relational-style document model with explicit indexes to optimize performance, as the architecture forbids the use of .filter() in queries.

Entity Relationship Diagram

The following diagram illustrates the relationships between the core database tables.

The data model centers around the Project, which belongs to an organization (managed by Clerk). Every project contains multiple ProjectStages (e.g., development, production) and holds encrypted ProjectVariables.

Sources: pkg/convex/schema.ts:4-66, AGENTS.md:55-64

Table Definitions

Table	Primary Purpose	Key Indexes
users	Stores user profiles and Clerk ID mapping.	by_clerk_user_id, by_slug
projects	Organization-scoped containers for secrets.	by_org_id_and_slug
projectStages	Environment scopes (dev/prod) within a project.	by_project_id_and_slug
projectVariables	Encrypted secrets belonging to a stage.	by_project_id_and_stage_slug_and_name
projectKeys	Stores the Data Encryption Key (DEK) for a project.	by_project_id

Sources: pkg/convex/schema.ts:4-66

Authentication and Authorization

Barekey integrates with Clerk for identity management. Convex functions verify the user's identity and organization membership before executing logic.

Authentication Flow

1. The client sends a request with a Clerk-issued JWT.
2. The Convex function calls ctx.auth.getUserIdentity() to retrieve user claims.
3. The function validates that the user's orgId matches the requested resource scope.

Secret Management and Encryption

Barekey employs envelope encryption to protect sensitive variable values. This ensures that even if the database is compromised, the secrets remain unreadable without the master keys.

Encryption Hierarchy

• Master KEK (Key Encryption Key): Stored encrypted at rest in Convex.
• Project DEK (Data Encryption Key): One per project, stored encrypted by the KEK in the projectKeys table.
• Secret Value: Each secret is encrypted using the project-specific DEK.

Sources: AGENTS.md:68-75, pkg/convex/project_variables.ts:125-140

Variable Types and Logic

Secrets are defined using a discriminated union in the schema. The kind field determines how the value is handled.

Kind	Behavior
secret	Standard environment variable; returns the decrypted value.
ab_roll	A/B Testing roll; returns Value A or Value B based on a chance (0-1).

Sources: AGENTS.md:77-100, pkg/convex/project_variables.ts:25-34

Logic Flow: Applying Draft Changes

The applyDraftForCurrentOrgProjectStage mutation demonstrates the complexity of the API, supporting bulk creates, updates, and deletes in a single atomic transaction.

Summary

The Convex Backend API Architecture provides a secure, reactive environment for secret management. By leveraging Convex's atomic mutations and built-in indexing, the system maintains high data integrity. The integration with Clerk ensures robust multi-tenant isolation, while the envelope encryption strategy secures sensitive developer data at rest.