Project Settings & Variables UI
Relevant source files
The following files were used as context for generating this wiki page:
- pkg/ui/src/pages/o/[org]/project/[projectSlug]/settings/page.tsx
- pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx
- pkg/ui/src/pages/o/[org]/project/[projectSlug]/overview/page.tsx
- pkg/ui/src/pages/o/[org]/project/[projectSlug]/layout.tsx
- pkg/convex/project_variables.ts
- pkg/convex/projects.ts
The Project Settings & Variables UI provides the management interface for environment-specific secrets and project-level configurations within Barekey. It allows developers to define infrastructure stages (e.g., development, production), manage encrypted variables via a drafting system, and control project lifecycles.
This system is built using a React SPA frontend communicating with a Convex backend. It utilizes a hierarchical navigation structure where a shared layout provides context for nested pages including Variables, Overview, and Settings.
Sources: AGENTS.md:12-25, pkg/ui/src/pages/o/[org]/project/[projectSlug]/layout.tsx:21-72
Project Layout and Context
All project-specific pages reside under a common layout that fetches project metadata and organization claims. This layout provides a ProjectRouteContext to child pages using React Router's useOutletContext.
ProjectRouteContext Structure
| Field | Type | Description |
|---|---|---|
orgSlug | string | The unique identifier for the organization. |
projectSlug | string | The unique identifier for the project. |
projectName | string | The display name of the project. |
createdAtMs | number | Creation timestamp in milliseconds. |
updatedAtMs | number | Last update timestamp in milliseconds. |
Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/layout.tsx:29-35, pkg/ui/src/pages/o/[org]/project/[projectSlug]/layout.tsx:114-122
The navigation within this layout allows users to toggle between functional areas:
- Variables: The primary secret management interface.
- Overview: Identity information and roadmap.
- Settings: Environment management and project deletion.
Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/layout.tsx:21-25
Variable Management System
The Variables UI implements a complex drafting system that allows for bulk updates, imports, and secure decryption of individual secrets.
Variable Drafting Logic
The UI maintains a StageDraftState to track unsaved changes locally before committing them to the Convex backend. This allows users to perform multiple operations (creates, updates, deletes) in a single atomic transaction.
The diagram shows the flow of variable manipulation from user input through local state management to final backend persistence.
Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx:43-52, pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx:279-317
Secret Decryption Flow
Secrets are stored encrypted at rest. To view a value, the UI must trigger an explicit mutation that returns the plaintext for that specific interaction.
This sequence ensures that decrypted values are only held in client memory when explicitly requested by the user.
Sources: pkg/convex/project_variables.ts:219-270, pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx:455-498
Environments and Project Settings
The Settings page manages "Project Stages" (Environments) and high-level project metadata.
Stage Management
Projects are initialized with default stages: development, staging, and production. Users can create, rename, or delete additional stages. Deletion of a stage is restricted if it still contains variables.
| Requirement | Description |
|---|---|
| Unique Slugs | Generated from the name: lowercase, alphanumeric, and hyphens only. |
| Delete Lock | Stages with variableCount > 0 cannot be deleted. |
| Slug Limit | Stage slugs are sliced to 48 characters. |
Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/settings/page.tsx:39-47, pkg/ui/src/pages/o/[org]/project/[projectSlug]/settings/page.tsx:142-148, pkg/convex/projects.ts:110-120
Project Lifecycle (Danger Zone)
Project deletion is a destructive action with strict prerequisites to prevent accidental data loss.
The diagram illustrates the safety mechanisms enforced before a project can be permanently removed.
Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/settings/page.tsx:210-230, pkg/ui/src/pages/o/[org]/project/[projectSlug]/settings/page.tsx:376-410
Project Overview and Metadata
The Overview page serves as the entry point for project identity, displaying canonical identifiers used by SDKs and the CLI.
Identity Components
- Project Name: Display name of the project.
- Project Slug: URL-friendly identifier used in routing.
- Timestamps: Human-readable creation and last updated dates formatted via
Intl.DateTimeFormat. - Roadmap: Visual indicators for upcoming features like rotation audits and deploy-time snapshots.
Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/overview/page.tsx:22-60
Summary
The Project Settings & Variables UI implements a robust, environment-aware secret management system. By utilizing an atomic drafting system for variables and strict safety checks for environment and project deletion, it ensures data integrity while maintaining high security standards through on-demand decryption. The shared project context across Overview, Variables, and Settings pages provides a cohesive experience for managing complex infrastructure configurations.