Copy page

Frontend

Organizations & Users Management

Organizations & Users Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/components/ui/color-picker/color-picker.svelte
• src/routes/(app)/system/settings/+layout.svelte
• src/routes/(app)/system/settings/organizations/+page.svelte
• src/routes/(app)/system/settings/organizations/[uuid]/+page.svelte
• src/routes/(app)/system/settings/organizations/create/+layout@(app).svelte
• src/routes/(app)/system/settings/organizations/create/+page.svelte
• src/routes/(app)/system/settings/users/+page.svelte
• src/routes/(app)/system/settings/users/[uuid]/+page.svelte
• src/routes/(app)/system/settings/users/create/+layout@(app).svelte
• src/routes/(app)/system/settings/users/create/+page.svelte

This section documents the management interfaces for Organizations and User Profiles within the System Settings module. These views utilize the EntityListTable for data exploration and a specialized FormPageLayout for creating and editing records.

Settings Layout & Navigation

The organizations and users modules are hosted within a shared settings layout that provides a consistent vertical tab navigation and breadcrumb trail.

• Shared Layout: The src/routes/(app)/system/settings/+layout.svelte file defines the two-pane structure: a 20% width sidebar for tab navigation and an 80% width content area for the active route src/routes/(app)/system/settings/+layout.svelte:54-74.
• Breadcrumbs: Navigation context is managed via settingsTabMenuSegment, which dynamically updates the breadcrumb based on the active sub-route src/routes/(app)/system/settings/+layout.svelte:30-38.
• Tab Management: Tabs include Profile, Organizations, Users, Security, Modules, and Templates src/routes/(app)/system/settings/+layout.svelte:21-28.

Data Synchronization Flow

Both Organizations and Users modules use a BroadcastChannel mechanism to synchronize data across browser windows (e.g., when an edit popup closes).

Channel Name	Purpose
primebrick_organizations_sync	Refreshes the organization list when a create/edit action occurs src/routes/(app)/system/settings/organizations/+page.svelte:19.
primebrick_users_sync	Refreshes the user list after profile modifications src/routes/(app)/system/settings/users/+page.svelte:19.

Sources: src/routes/(app)/system/settings/+layout.svelte:1-78, src/routes/(app)/system/settings/organizations/+page.svelte:105-115.

Organization Management

List View

The organization list page integrates the EntityListTable component. It handles its own metadata caching to optimize transitions between the list and detail views.

• Metadata Caching: Global variables globalThis.__pbOrganizationMetaCache and __pbOrganizationMetaInFlight are used to prevent redundant API calls to /api/v1/entities/organization/meta src/routes/(app)/system/settings/organizations/+page.svelte:140-155.
• Column Management: Columns are derived from the metadata, including sticky columns for primary identifiers and auditing columns for record history src/routes/(app)/system/settings/organizations/+page.svelte:89-98.

Create & Edit Forms

Organization forms use sveltekit-superforms in SPA mode with Zod validation.

• Route Pattern: Create and edit pages use the layout@(app).svelte pattern to break out of the settings tab layout and occupy the full application shell src/routes/(app)/system/settings/organizations/create/+layout@(app).svelte:1-6.
• Auto-Slug Generation: In the create form, an effect automatically generates the idp_name (slug) from the display_name if it hasn't been manually set src/routes/(app)/system/settings/organizations/create/+page.svelte:147-169.
• Branding: The ColorPicker component allows setting organization-specific branding colors src/lib/components/ui/color-picker/color-picker.svelte:12-24.

Organization Form Logic

Title: Organization Entity Flow

Code
graph TD
    subgraph "Form_Logic [src/routes/(app)/system/settings/organizations/create/+page.svelte]"
        A["createSchema (Zod)"] --> B["superForm (SPA Mode)"]
        B --> C["onUpdate()"]
        C --> D["apiFetch POST /api/v1/entities/organization"]
    end
    
    subgraph "Navigation_&_Sync"
        D --> E["notifyParentRefresh()"]
        E --> F["BroadcastChannel.postMessage('refresh')"]
        F --> G["goto /system/settings/organizations/[uuid]"]
    end

Sources: src/routes/(app)/system/settings/organizations/create/+page.svelte:63-138, src/routes/(app)/system/settings/organizations/[uuid]/+page.svelte:91-135.

User Management

User Creation & Avatars

The user creation process includes unique UI logic for avatar customization.

• Initial Color Persistence: A random avatar color is generated on mount and persisted in sessionStorage (pb:user-create:avatar-color) so it remains consistent across page refreshes until the user is created src/routes/(app)/system/settings/users/create/+page.svelte:49-59.
• Avatar Preview: Initials are reactively derived from the display_name input to provide a real-time preview of the user's avatar src/routes/(app)/system/settings/users/create/+page.svelte:191-200.
• Validation: The createSchema enforces strict rules on idpUsername (alphanumeric start/end) and password length src/routes/(app)/system/settings/users/create/+page.svelte:95-126.

Form Layout Integration

Both user and organization edit pages utilize FormPageLayout to wrap the form content. This component provides:

1. Audit Box: Displays record metadata (created by, updated by, version) via the useAuditBox logic src/routes/(app)/system/settings/users/[uuid]/+page.svelte:236-240.
2. Navigation Guards: Uses beforeNavigate and onbeforeunload to warn users about unsaved changes if the form is "tainted" src/routes/(app)/system/settings/users/[uuid]/+page.svelte:216-234.

User Management System Architecture

Title: User Profile Entity Components

Code
graph LR
    subgraph "UI_Layer"
        UL["users/+page.svelte"] -- "Uses" --> ELT["EntityListTable"]
        UC["users/create/+page.svelte"] -- "Uses" --> CP["ColorPicker"]
        UU["users/[uuid]/+page.svelte"] -- "Uses" --> FPL["FormPageLayout"]
    end

    subgraph "Data_Layer"
        ELT -- "fetch" --> API_L["GET /api/v1/entities/user_profiles"]
        FPL -- "audit" --> API_A["GET /api/v1/entities/user_profiles/[uuid]/audit"]
        UC -- "submit" --> API_C["POST /api/v1/auth/users"]
    end

    subgraph "State_Management"
        UC -- "sync" --> BC["BroadcastChannel: primebrick_users_sync"]
        BC -- "trigger" --> UL
    end

Sources: src/routes/(app)/system/settings/users/+page.svelte:108-115, src/routes/(app)/system/settings/users/create/+page.svelte:155-161, src/routes/(app)/system/settings/users/[uuid]/+page.svelte:109-115.

Implementation Details

Color Picker

The ColorPicker component supports multiple formats (hex, rgb, hsl, oklch) and handles complex color space conversions internally src/lib/components/ui/color-picker/color-picker.svelte:10-17. It uses an internal isDragging state to prevent feedback loops between external value updates and internal HSV sliders src/lib/components/ui/color-picker/color-picker.svelte:39-57.

Form Validation Refinements

A shared utility function startsAndEndsWithAlphanumeric is used across both modules to ensure that IDP-related strings (usernames, organization names) conform to backend requirements src/routes/(app)/system/settings/organizations/create/+page.svelte:36-42, src/routes/(app)/system/settings/users/create/+page.svelte:68-74.

Sources: src/lib/components/ui/color-picker/color-picker.svelte:1-240, src/routes/(app)/system/settings/organizations/create/+page.svelte:36-42.

---