Convex Deployment & Environment Config
Relevant source files
The following files were used as context for generating this wiki page:
Convex serves as the unified backend and database layer for Barekey, a developer SaaS vault manager. It handles the storage and management of encrypted environment variables, project structures, and organizational logic. The system architecture avoids a separate API server, instead hosting all logic within Convex functions (queries, mutations, and actions) that the React frontend accesses via the ConvexReactClient over WebSockets.
The configuration and deployment lifecycle ensures that sensitive developer data is managed through a multi-stage environment pipeline. This includes a robust project-scoped stage system (Development, Staging, Production) and a strict deployment workflow that utilizes the Convex CLI to synchronize backend code and schema definitions.
Sources: AGENTS.md:12-19, AGENTS.md:25-30
Backend Architecture & Functions
The Convex backend is organized into discrete modules within the pkg/convex/ directory. These modules define the API surface used by the frontend and future SDKs.
Function Types
Convex distinguishes between different types of server-side execution contexts:
| Function Type | Purpose | Restrictions |
|---|---|---|
query | Publicly accessible read-only database operations. | Cannot modify data. |
mutation | Publicly accessible write operations. | Atomic execution; guaranteed consistency. |
action | Executes side effects (e.g., calling third-party APIs). | No direct ctx.db access. |
internal* | Functions accessible only by other Convex functions. | Hidden from the internet/client. |
Sources: AGENTS.md:135-140, AGENTS.md:162-166
Data Flow for Function Execution
The following diagram illustrates how the frontend interacts with Convex functions to manage environment configurations.
Description: The flow of requests from the user interface through the Convex client to the database layer.
Sources: AGENTS.md:25-30, AGENTS.md:135-145
Environment Configuration & Stages
Every project in Barekey is initialized with a standard set of environment stages to support a typical development lifecycle. These stages act as containers for project variables.
Default Project Stages
When a new project is created via the projects.createForCurrentOrg mutation, the following default stages are automatically provisioned:
- Development: Initial coding and testing.
- Staging: Pre-production environment for final verification.
- Production: Live environment for end-user workloads.
Sources: pkg/convex/projects.ts:98-111, pkg/convex/projects.ts:145-156
Stage Schema
Stages are stored in the projectStages table and are linked to specific projects and organizations.
| Field | Type | Description |
|---|---|---|
projectId | id("projects") | Reference to the owner project. |
orgId | string | The organization ID owning the project. |
slug | string | URL-friendly identifier (e.g., "staging"). |
name | string | Display name for the UI. |
isDefault | boolean | Flag indicating if it is a system-generated stage. |
Sources: pkg/convex/schema.ts:31-41
Deployment Workflow
The deployment of Convex functions and schema changes is managed through a strict CLI-driven process. This ensures that the backend remains in sync with the frontend requirements.
Core CLI Commands
Developers and AI agents use the following commands to manage the deployment state:
npx convex dev: Starts a local development server and watches for file changes to automatically sync with a development deployment.npx convex deploy: Deploys current functions and schema to the production environment.npx convex env set KEY val: Manages environment variables required by the Convex functions themselves (e.g.,CLERK_JWT_ISSUER_DOMAIN).
Sources: INDEX.md:89-100, INDEX.md:123-128
Deployment State Machine
The deployment process follows a specific sequence to ensure integrity before a Pull Request is merged.
Description: The operational lifecycle for deploying backend changes to Convex.
Sources: INDEX.md:103-112
Environment Variable Storage
Environment variables (secrets) are managed within specific project stages. They are stored in the projectVariables table and utilize envelope encryption for security.
Storage Logic
Variables are tied to a stageSlug within a projectId. This allows the same variable name (e.g., DATABASE_URL) to exist with different values across "Development" and "Production" stages.
Description: Relationship between projects, their environment stages, and the variables stored within those stages.
Sources: pkg/convex/schema.ts:43-64, pkg/convex/project_variables.ts:47-60
Atomic Updates
The applyDraftForCurrentOrgProjectStage mutation allows for bulk operations (creates, updates, and deletes) in a single transaction. This prevents partial state updates when importing multiple variables from .env files or the UI composer.
Sources: pkg/convex/project_variables.ts:98-109, pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx:327-347
Conclusion
The Convex Deployment and Environment Config system provides a scalable, serverless backend for Barekey. By leveraging Convex's atomic mutations and stage-scoped variable management, the project ensures data consistency and secure deployment paths for developer secrets across multiple environments.