Frontend Routing & Layouts
Relevant source files
The following files were used as context for generating this wiki page:
The Barekey frontend utilizes a nested routing architecture powered by react-router-dom. This system is designed to handle multi-tenant workspaces (Organizations) and project-specific configurations while maintaining persistent UI elements like sidebars and headers through a hierarchical layout structure.
The routing logic ensures that users are always contextualized within a specific organization or user account, automatically handling redirects to authentication or organization selection when necessary.
Core Routing Architecture
The application's route tree is defined in pkg/ui/src/router.tsx. It categorizes paths into four primary top-level segments: root/public, authentication, organizations (/o), and users (/u).
Route Structure Overview
| Path Segment | Purpose | Layout / Component |
|---|---|---|
/ | Landing/Redirect Logic | Home.Page |
/auth | Authentication Flows | Auth.Layout |
/o/:orgSlug | Organization Workspace | OrgLayout.Layout |
/u/:userSlug | User Account Management | UserLayout.Layout |
Sources: pkg/ui/src/router.tsx:1-45
Routing Flow Diagram
The following diagram illustrates how a user request is routed through the various layouts based on the URL path.
Organization Workspaces (/o/:orgSlug)
The Organization Layout acts as the primary container for the Barekey dashboard. It utilizes a SidebarProvider to wrap a collapsible navigation sidebar and a main content area (SidebarInset).
Workspace Synchronization
A critical function of the Organization Layout is ensuring the active Clerk organization matches the :orgSlug parameter in the URL. If a mismatch is detected, the layout attempts to set the active organization using setActive from Clerk's useOrganizationList hook.
- Path Tracking: It determines the
activeSegmentto highlight the correct navigation item (Overview, Projects, Members, Billing, Settings). - Access Control: If a user attempts to access an organization they do not belong to, they are redirected to a "Workspace not available" view.
Sources: pkg/ui/src/pages/o/[org]/layout.tsx:158-230
Navigation and Breadcrumbs
The layout dynamically generates breadcrumbs and navigation titles based on the current route segments.
- Nav Items: Defined as a constant array containing labels, icons, and path segments.
- Sidebar: Features an organization switcher allowing users to jump between workspaces or create a new one.
Sources: pkg/ui/src/pages/o/[org]/layout.tsx:55-63, pkg/ui/src/pages/o/[org]/layout.tsx:340-370
Project-Scoped Routing
Nested within the Organization Layout is the Project Layout (pkg/ui/src/pages/o/[org]/project/[projectSlug]/layout.tsx). This layout provides a sub-navigation bar specifically for project-level tasks: Variables, Overview, and Settings.
Project Context
The Project Layout provides a ProjectRouteContext via the Outlet component, making essential project metadata available to all sub-pages.
export type ProjectRouteContext = {
orgSlug: string;
projectSlug: string;
projectName: string;
createdAtMs: number;
updatedAtMs: number;
};
Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/layout.tsx:32-38, pkg/ui/src/pages/o/[org]/project/[projectSlug]/layout.tsx:143-152
Navigation Logic
The project sub-navigation uses NavLink with specific logic to determine the active tab based on the current URL segment. It defaults to the "Variables" segment if no sub-path is provided.
Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/layout.tsx:49-55
User Account Layout (/u/:userSlug)
The User Layout provides a dedicated space for user-specific settings and overviews. Similar to the Organization Layout, it includes a sidebar and handles redirects if the :userSlug in the URL does not match the slug of the currently authenticated user.
- Sidebar Integration: Uses
SidebarProviderandSidebarInset. - Slug Enforcement: If a user navigates to a mismatched slug, they are redirected to their canonical user URL:
/u/${currentUser.slug}/overview.
Sources: pkg/ui/src/pages/u/user/layout.tsx:35-65
Authentication & Guarding
Barekey uses a combination of Clerk authentication and Convex authorization to guard routes.
- Auth Guarding: Components like
Home.PagecheckisSignedInfrom Clerk. If false, the user is redirected to/auth/sso. - Convex Sync: The
useEnsureCurrentUserRecordhook is used across layouts to ensure a corresponding user record exists in the Convex database. - Default Redirects:
- Root (
/) redirects to the active organization's overview. - If no organization is active, it redirects to
/o/select.
- Root (
Sources: pkg/ui/src/pages/home/page.tsx:21-36, pkg/ui/src/pages/o/select/page.tsx:84-86
Selection & Creation
The /o/select page handles organization selection and "bootstrapping" for new users, offering a mechanism to create a default organization if none exist.
Sources: pkg/ui/src/pages/o/select/page.tsx:40-82
Summary
The frontend routing system is designed for deep nesting, allowing Barekey to scale from simple account overviews to complex project-level secret management. By utilizing hierarchical layouts, the application maintains a consistent navigation state (sidebars, breadcrumbs, and org-context) while enabling granular control over individual sub-modules.