Project Lifecycle Management
Relevant source files
The following files were used as context for generating this wiki page:
Project Lifecycle Management in Barekey encompasses the end-to-end process of creating, configuring, and decommissioning project-scoped vaults. Projects serve as the primary container for secrets and environment variables, owned exclusively by Organizations rather than individual users. The lifecycle is defined by strict slug policies, envelope encryption initialization, and a hierarchical structure where projects contain multiple deployment stages (environments).
Sources: AGENTS.md:46-50, pkg/convex/projects.ts:98-112
Project Provisioning and Identification
The creation of a project initiates with a user-provided name, which is then transformed into a unique, URL-friendly slug. Barekey enforces a "slug policy" requiring all identifiers to match ^[a-z0-9]+$. To ensure uniqueness within an organization, the system utilizes a collision-resistant allocation strategy that appends numeric suffixes to a normalized base slug.
Provisioning Workflow
When a project is created via createForCurrentOrg, the backend performs the following sequence:
- Identity Validation: Ensures the user is authenticated and belongs to the target organization.
- Slug Allocation: Normalizes the project name and searches for a unique candidate using 4-digit or 6-digit random numeric suffixes.
- Data Persistence: Inserts the project document into the Convex database.
- Stage Seeding: Automatically initializes three default stages:
development,staging, andproduction.
Sources: pkg/convex/projects.ts:10-53, pkg/convex/projects.ts:88-142, AGENTS.md:62-67
The diagram shows the logic for unique slug allocation and initial project setup.
Sources: pkg/convex/projects.ts:25-53, pkg/convex/projects.ts:133-142
Environment and Stage Management
Projects are subdivided into "Stages," which represent distinct environments (e.g., development, production). Stages provide the namespace for variables and secrets. While projects are seeded with defaults, users can manage the stage lifecycle through the Project Settings interface.
Stage Lifecycle Operations
- Creation: Custom stages can be added. Slugs are derived from the stage name but remain immutable once created to prevent breaking runtime SDK/CLI references.
- Renaming: Users can update the display name of a stage without affecting its underlying slug.
- Deletion: Deletion is protected by a safety guard; a stage cannot be deleted if it still contains variables.
Sources: pkg/convex/project_stages.ts:121-163, pkg/convex/project_stages.ts:219-257, pkg/ui/src/pages/o/[org]/project/[projectSlug]/settings/page.tsx:142-167
| Component | Logic / Constraint | Source File |
|---|---|---|
| Stage Slug | Immutable once allocated; lowercase alphanumeric and hyphens. | pkg/convex/project_stages.ts:168-172 |
| Default Stages | development, staging, production seeded on project init. | pkg/convex/projects.ts:80-96 |
| Deletion Guard | Blocked if variableCount > 0. | pkg/convex/project_stages.ts:245-253 |
Secret and Variable Lifecycle
The core of Project Lifecycle Management is the handling of encrypted variables. Variables are scoped to specific stages within a project. Barekey uses envelope encryption, where a per-project Data Encryption Key (DEK) is used to encrypt individual secrets.
Data Flow for Secrets
- Drafting: Variables are staged in a UI draft state, allowing for bulk imports from
.envfiles or manual entry. - Encryption (at rest): When applied, values are encrypted via
encryptSecretValueForProjectbefore being stored in theprojectVariablestable. - Decryption (on-demand): Plaintext values are never returned in bulk listings. They must be decrypted individually via a mutation that returns the ephemeral plaintext for UI reveal.
Sources: pkg/convex/project_variables.ts:46-51, pkg/convex/project_variables.ts:135-144, pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx:135-150
The sequence diagram illustrates the atomic application of a variable draft with server-side encryption.
Sources: pkg/convex/project_variables.ts:108-185
Decommissioning and Deletion
Deleting a project is a permanent action that is heavily guarded to prevent accidental data loss. The "Danger Zone" in project settings implements a multi-step verification process.
Deletion Prerequisites
A project cannot be deleted until it is completely empty. This requires:
- Zero active variables across all stages.
- Zero custom or default stages (all stages must be deleted first).
- A 5-second countdown timer in the UI to prevent "mis-clicks."
When deleteForCurrentOrg is invoked, the system also cleans up associated projectKeys (encryption metadata) before removing the project document itself.
Sources: pkg/convex/projects.ts:228-265, pkg/ui/src/pages/o/[org]/project/[projectSlug]/settings/page.tsx:238-254
Data Model Summary
The project lifecycle is persisted across several key tables in the Convex schema.
| Table | Description | Key Fields |
|---|---|---|
projects | Root container for an organization's vault. | orgId, slug, name, createdByClerkUserId |
projectStages | Environment namespaces within a project. | projectId, slug, name, isDefault |
projectVariables | Encrypted secrets and variable metadata. | projectId, stageSlug, name, encryptedValue, kind |
projectKeys | Encryption metadata (DEK/KEK associations). | projectId, orgId |
Sources: pkg/convex/projects.ts:55-80, pkg/convex/project_stages.ts:58-70, pkg/convex/project_variables.ts:29-39, pkg/convex/projects.ts:252-258
Project Lifecycle Management in Barekey ensures that from the moment of creation (with automated stage seeding and unique slug generation) to decommissioning (requiring total resource cleanup), every stage of a project's life is handled with security and architectural integrity. The system enforces strict organizational ownership and utilizes envelope encryption to protect the primary assets—secrets—contained within the project vault.