# Organizations & Users Management

# Organizations & Users Management

<details>
<summary>Relevant source files</summary>

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

- [src/lib/components/ui/color-picker/color-picker.svelte](src/lib/components/ui/color-picker/color-picker.svelte)
- [src/routes/(app)/system/settings/+layout.svelte](src/routes/(app)/system/settings/+layout.svelte)
- [src/routes/(app)/system/settings/organizations/+page.svelte](src/routes/(app)/system/settings/organizations/+page.svelte)
- [src/routes/(app)/system/settings/organizations/[uuid]/+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/+layout@(app).svelte)
- [src/routes/(app)/system/settings/organizations/create/+page.svelte](src/routes/(app)/system/settings/organizations/create/+page.svelte)
- [src/routes/(app)/system/settings/users/+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/[uuid]/+page.svelte)
- [src/routes/(app)/system/settings/users/create/+layout@(app).svelte](src/routes/(app)/system/settings/users/create/+layout@(app).svelte)
- [src/routes/(app)/system/settings/users/create/+page.svelte](src/routes/(app)/system/settings/users/create/+page.svelte)

</details>



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
```mermaid
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
```mermaid
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]().

---