System Architecture 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. The system architecture emphasizes high developer experience (DX) and robust security through envelope encryption. The platform is built as a Single Page Application (SPA) using a Backend-as-a-Service (BaaS) approach, where the backend logic and database are hosted entirely on Convex, and authentication/organization management is handled by Clerk.
Sources: AGENTS.md:5-10, AGENTS.md:21-25
High-Level Stack
The project utilizes a modern web stack designed for rapid development and real-time updates.
| Layer | Tool | Description |
|---|---|---|
| Backend / DB | Convex | Hosts all functions, schema, and data. |
| Auth & Orgs | Clerk | Manages user identities and organization structures. |
| Frontend | React SPA | Built with Vite and connects via ConvexReactClient (WebSocket). |
| Styling | Shadcn + Tailwind | Provides the UI component library and utility styling. |
Sources: AGENTS.md:12-19, AGENTS.md:25-28
Data and Encryption Model
Barekey employs an envelope encryption strategy to secure secrets at rest. Each project is assigned a Data Encryption Key (DEK), which is itself encrypted by a Master Key Encryption Key (KEK).
Encryption Hierarchy
The following diagram illustrates the relationship between keys and encrypted data:
The Master KEK is stored encrypted at rest in Convex. For the MVP, encryption is server-side, with a long-term goal of client-side encryption.
Sources: AGENTS.md:52-62, pkg/convex/project_variables.ts:161-165
Core Entities
| Entity | Description | Ownership |
|---|---|---|
| Org | Managed by Clerk; identifies a team workspace. | Owns Projects |
| Project | A workspace for environment variables; contains a unique DEK. | Belongs to Org |
| Stage | A deployment environment (e.g., Development, Staging, Production). | Belongs to Project |
| Secret | An encrypted environment variable. | Belongs to Project Stage |
Sources: AGENTS.md:43-50, pkg/convex/projects.ts:98-106, pkg/convex/project_stages.ts:108-115
Backend Architecture (Convex)
Convex acts as the unified backend layer, handling database operations, business logic, and real-time synchronization.
Directory Structure
pkg/convex/
├── auth/ ← Clerk integration helpers
├── vaults/ ← secrets CRUD, encryption, env config
├── teams/ ← team/org logic
├── projects/ ← project management, DEK lifecycle
└── project_stages.ts ← Stage management and variable counts
Sources: AGENTS.md:30-40
Functional Flow: Creating a Project
When a project is created, the system automatically initializes canonical default stages.
Frontend Architecture
The frontend is a React SPA that uses the ConvexReactClient for data fetching via WebSockets. It leverages a layout-based routing system where project-specific views are nested under a common layout providing project context.
Routing and Context
Route parameters like [org] and [projectSlug] are used to fetch and scope data. The ProjectRouteContext provides shared state (IDs, slugs, timestamps) to all child pages in a project workspace.
export type ProjectRouteContext = {
orgSlug: string;
projectSlug: string;
projectName: string;
createdAtMs: number;
updatedAtMs: number;
};
Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/layout.tsx:28-34, pkg/ui/src/pages/new/page.tsx:24-40
Project Variable Management
Variables are managed per stage. The UI supports atomic bulk updates, allowing users to stage multiple creates, updates, and deletes before committing them to the backend.
Variable Operations
- Listing: Retrieves metadata (name, kind, timestamps) but keeps values encrypted.
- Applying Drafts: Atomically persists staged changes.
- Decryption: An explicit action to reveal a secret value in the UI.
Conclusion
Barekey's architecture leverages Convex's BaaS capabilities to minimize infrastructure overhead while focusing on security through per-project envelope encryption. The system enforces strict organization-level ownership and provides a structured environment for managing secrets across multiple deployment stages.
Sources: AGENTS.md:5-10, AGENTS.md:43-50