Project Overview
Relevant source files
The following files were used as context for generating this wiki page:
Barekey is a developer SaaS vault manager designed to manage encrypted environment variables (secrets) for developer teams with a focus on high-quality developer experience (DX). The platform allows users to create organizations, manage projects within those organizations, and secure sensitive configuration data using robust encryption methods.
The system is currently in an early scaffold state where core features like signup, organization creation, and project management are functional, while the user interface and advanced vault features are actively being developed.
Sources: AGENTS.md:5-10, pkg/ui/src/pages/new/page.tsx:94-135
System Architecture
The project utilizes a modern BaaS (Backend-as-a-Service) architecture centered around Convex and Clerk. There is no separate API server; instead, the frontend Single Page Application (SPA) communicates directly with Convex via WebSockets or HTTP.
Core Technology Stack
| Layer | Tool | Description |
|---|---|---|
| Backend / DB | Convex | BaaS hosting all logic and data storage in pkg/convex/. |
| Auth & Orgs | Clerk | Manages user identities and organization memberships. |
| Frontend | React SPA | Built with Vite, using Shadcn and Tailwind for styling. |
| Communication | ConvexReactClient | Facilitates real-time communication between UI and backend. |
Sources: AGENTS.md:14-22
Application Flow
The following diagram illustrates the high-level relationship between the user, the frontend, and the managed backend services.
The SPA utilizes Clerk's React SDK and ConvexProviderWithClerk to handle authentication. Backend functions verify identity using ctx.auth.getUserIdentity().
Sources: AGENTS.md:24-38
Data Model and Relationships
The system organizes data hierarchically starting from the Organization level. A project is the primary unit of configuration, and it contains stages (environments) and encrypted variables.
| Entity | Description | Ownership |
|---|---|---|
| Organization | Managed by Clerk; acts as the primary container for projects. | Owned by User(s) |
| Project | A workspace for configuration. Has a unique DEK. | Owned by Org |
| Stage | An environment (e.g., Development, Production) within a project. | Owned by Project |
| Secret | An encrypted environment variable associated with a stage. | Owned by Project/Stage |
Sources: AGENTS.md:40-47, pkg/convex/projects.ts:98-120
Entity Relationship Diagram
Encryption Architecture
Barekey employs Envelope Encryption to secure secrets. This ensures that even if the primary database is compromised, the actual secret values remain protected.
Key Hierarchy
- Master KEK (Key Encryption Key): Stored as an environment variable (
BAREKEY_MASTER_KEY_B64). It is used to wrap/unwrap project-specific keys. - Project DEK (Data Encryption Key): A unique 32-byte AES-GCM key generated per project. It is stored in the database, but only in an encrypted state (wrapped by the KEK).
- Encrypted Value: The actual environment variable value, encrypted using the Project DEK.
Sources: AGENTS.md:58-65, pkg/convex/lib/encryption.ts:8-15
Encryption Sequence
When a secret is stored, the system follows this sequence to ensure security:
Project and Stage Lifecycle
Project Creation
Projects are created within the context of an active organization. When a project is initialized, it automatically seeds default stages: development, staging, and production.
Sources: pkg/convex/projects.ts:87-95, pkg/convex/projects.ts:121-131
Variable Management
Variables are managed per stage. The system supports a "Draft" workflow where multiple changes (creates, updates, deletes) can be applied atomically.
- Kind
secret: Standard encrypted value. - Kind
ab_roll: (Planned) Supports A/B testing by returning different values based on a probabilitychance.
Sources: pkg/convex/project_variables.ts:81-110, AGENTS.md:67-85
Deletion Safety
To prevent accidental data loss, a project cannot be deleted until all associated stages and variables have been removed. Similarly, a stage cannot be deleted if it contains active variables.
Sources: pkg/convex/projects.ts:241-255, pkg/convex/project_stages.ts:278-290
Technical Standards
The project enforces strict development rules to maintain code quality and security:
- Slug Policy: All slugs (org, project, stage) must match
^[a-z0-9]+$to ensure URL compatibility and consistency. - TypeScript: Use of
anyis forbidden;unknownis preferred. Components must not useexport default. - Convex Usage: Queries must use
.withIndex()instead of.filter()for performance. Mutations usectx.db.patchfor shallow merges.
Sources: AGENTS.md:49-56, AGENTS.md:144-165, AGENTS.md:173-195
Summary
Barekey provides a structured environment for managing sensitive developer secrets through a multi-tenant organization and project model. By leveraging Convex for real-time backend logic and envelope encryption for data security, it creates a robust vault system that prioritizes both security and developer efficiency. Key operations include atomic variable drafting, stage-scoped configuration, and automated project bootstrapping.