Organization Management System
Relevant source files
The following files were used as context for generating this wiki page:
The Organization Management System in Barekey is a multi-tenant architecture designed to manage developer teams and their associated projects. It leverages Clerk for core authentication and organization data, while integrating with Convex for backend persistence and project-level scoping. In this system, only organizations (teams) can own projects; individual users do not own projects directly.
The system facilitates a "workspace" model where users can switch between different organization contexts. Each workspace provides isolated access to projects, members, billing, and settings. A robust slug policy ensures that all organization identifiers are URL-friendly and unique.
Sources: AGENTS.md:46-51, pkg/ui/src/pages/o/select/page.tsx:106-112
Core Architecture
The system utilizes a hybrid approach where Clerk serves as the primary authority for organization memberships, roles, and profiles, while Convex handles the application-specific metadata and project relationships.
Authentication and Context
The frontend SPA uses the Clerk React SDK and ConvexProviderWithClerk to maintain a unified session. Organization context is typically derived from the URL slug (/o/:orgSlug) and validated against the active Clerk session.
The diagram shows how the user interface synchronizes the URL slug with the active Clerk organization to ensure backend queries are scoped correctly.
Sources: AGENTS.md:33-40, pkg/ui/src/pages/o/[org]/layout.tsx:180-210
Organization Lifecycle
Creation and Bootstrapping
When a user first joins the platform, the system implements an automatic "bootstrap" process. If a user has no organizations, the system generates a default organization based on their name or email.
| Feature | Description |
|---|---|
| Manual Creation | Users can create organizations via the /new?type=organization route by providing a name. |
| Auto-Bootstrap | Automatically creates an organization named "<Name>'s Organization" for new users. |
| Slug Generation | Slugs are generated using lowercase alphanumeric characters only (^[a-z0-9]+$). |
| Selection | The /o/select page allows users to choose from their current memberships. |
Sources: AGENTS.md:46-56, pkg/ui/src/pages/o/select/page.tsx:28-66, pkg/ui/src/pages/new/page.tsx:85-132
Slug Policy and Normalization
Barekey enforces a strict slug policy for organizations and projects. Slugs must match ^[a-z0-9]+$ and cannot contain hyphens, underscores, or uppercase letters. When conflicts occur, the system appends numeric suffixes directly to the base name.
Member and Access Management
Organization access is managed through three primary states: Members, Invitations, and Requests.
Membership Roles
Members within an organization are assigned specific roles which determine their level of access to workspace settings and project operations.
| Role | Badge Variant | Description |
|---|---|---|
org:admin | default | Full access to settings, billing, member removal, and project deletion. |
org:member | secondary | Standard access to view and manage projects/variables. |
| Other | outline | Restricted or custom roles. |
Sources: pkg/ui/src/components/custom/org-workspace.tsx:25-35, pkg/ui/src/pages/o/[org]/settings/page.tsx:112-115
Access Control Flow
Admins can manage the lifecycle of members and invites through the "Members" dashboard.
Workspace Components
The UI provides several specialized components for organization management:
1. OrgPageHero
A standard header used across all organization pages (Overview, Projects, Members, Billing, Settings). It displays the organization name, slug, and the user's current role badge.
Sources: pkg/ui/src/components/custom/org-workspace.tsx:75-123
2. OrgMetricCard
Displays high-level usage stats. Currently includes placeholders for Static Requests, Dynamic Requests, and Storage usage, which are intended for future usage limit tracking.
Sources: pkg/ui/src/components/custom/org-workspace.tsx:125-156
3. Organization Workspace Sidebar
The primary navigation element that includes a workspace switcher. It allows users to:
- Switch between active organizations.
- Access the "Create new workspace" flow.
- Navigate to organization-scoped pages (Overview, Projects, Members, Billing, Settings).
Sources: pkg/ui/src/pages/o/[org]/layout.tsx:313-360
Settings and Diagnostics
The settings page allows administrators to update the organization's profile and provides tools for troubleshooting.
- Profile Management: Admins can change the organization name and upload/remove the workspace logo. Changing the name may trigger a slug update flow if the user prefers a new slug based on the renamed organization.
- Advanced Diagnostics: A collapsible panel providing technical details for troubleshooting routing issues, including the Workspace ID, Workspace Role, and Route Alignment status (verifying if the URL slug matches the active session).
- Danger Zone: Allows users to leave the workspace. Re-joining requires a new invitation.
Sources: pkg/ui/src/pages/o/[org]/settings/page.tsx:135-183, pkg/ui/src/pages/o/[org]/settings/page.tsx:266-304, pkg/ui/src/pages/o/[org]/settings/page.tsx:214-235
Summary
The Organization Management System serves as the foundational multi-tenancy layer for Barekey. By strictly separating concerns between Clerk (identity/membership) and Convex (application logic/project ownership), it provides a secure environment for teams to manage secrets. The system's emphasis on slug normalization and automated bootstrapping ensures a streamlined developer experience from initial signup through team scaling.