@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/LLM/preferences-settings-llm.md

@@ -0,0 +1,2781 @@
+# AdminIDE Stack Preferences System - Complete LLM Guide
+
+**Purpose:** This guide teaches how to create preferences in AdminIDE Stack, covering the complete workflow from flattened configuration keys to nested GraphQL types and database registration.
+
+**Last Updated:** January 19, 2025 | **Version:** 1.0.0
+
+---
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Architecture Overview](#architecture-overview)
+3. [Complete Implementation Guide](#complete-implementation-guide)
+4. [Mapping Rules & Patterns](#mapping-rules--patterns)
+5. [Real-World Examples](#real-world-examples)
+6. [Frontend Consumption - Practical UI Usage](#frontend-consumption---practical-ui-usage)
+7. [Testing & Validation](#testing--validation)
+8. [Best Practices](#best-practices)
+9. [Troubleshooting](#troubleshooting)
+10. [Reference](#reference)
+
+---
+
+## Quick Start
+
+### TL;DR - The 4-Step Pattern
+
+```
+1. Create flattened keys    → *-contribution.ts
+2. Create migration          → Add*ConfigurationsMigration.ts
+3. Create nested GraphQL     → preferences.graphql
+4. Bind migration            → module.ts
+```
+
+### Minimal Working Example
+
+**Step 1: Contribution (Flattened Keys)**
+
+```typescript
+// notifications-contribution.ts
+import { IConfigurationSchemaMap } from '@adminide-stack/core';
+import * as nls from '@vscode-alt/monaco-editor/esm/vs/nls';
+import { ConfigurationScope } from 'common/server';
+
+export const NotificationsContribution: IConfigurationSchemaMap = {
+    'app.notifications.email.enabled': {
+        type: 'boolean',
+        default: true,
+        description: nls.localize('appNotificationsEmailEnabled', 'Enable email notifications'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+    'app.notifications.email.frequency': {
+        type: 'string',
+        enum: ['instant', 'daily', 'weekly'],
+        default: 'daily',
+        description: nls.localize('appNotificationsEmailFrequency', 'Email notification frequency'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+};
+```
+
+**Step 2: Migration**
+
+```typescript
+// AddNotificationsConfigurationsMigration.ts
+import { IConfigurationRegistry } from '@adminide-stack/core';
+import { inject, injectable } from 'inversify';
+import type { Connection } from 'mongoose';
+import { CdmLogger } from '@cdm-logger/core';
+import { SERVER_TYPES, IRedisCacheManager } from 'common/server';
+import { BaseConfigurationsMigration } from '@adminide-stack/platform-server';
+import { NotificationsContribution } from '../preferences/settings';
+
+@injectable()
+export class AddNotificationsConfigurationsMigration extends BaseConfigurationsMigration {
+    name = 'notifications';
+
+    constructor(
+        @inject('MongoDBConnection') db: Connection,
+        @inject(SERVER_TYPES.IConfigurationRegistry) configurationRegistry: IConfigurationRegistry,
+        @inject('Logger') logger: CdmLogger.ILogger,
+        @inject(SERVER_TYPES.IRedisCacheManager) redisCacheManager: IRedisCacheManager,
+    ) {
+        super(db, configurationRegistry, redisCacheManager, logger);
+    }
+
+    get id() {
+        return `${AddNotificationsConfigurationsMigration.name}_20250119`;
+    }
+    get policies() {
+        return {};
+    }
+    get roles() {
+        return {};
+    }
+    get permissions() {
+        return {};
+    }
+    get permissionsOverride() {
+        return {};
+    }
+    get settings() {
+        return NotificationsContribution;
+    }
+}
+```
+
+**Step 3: GraphQL (Nested Structure)**
+
+```graphql
+# preferences.graphql
+
+"""
+Email notification settings
+Maps to: app.notifications.email.*
+"""
+type Preference_App_Notifications_Email {
+    """Maps to: app.notifications.email.enabled"""
+    enabled: Boolean
+
+    """Maps to: app.notifications.email.frequency"""
+    frequency: NotificationFrequency
+}
+
+enum NotificationFrequency {
+    INSTANT
+    DAILY
+    WEEKLY
+}
+
+"""
+Application notification preferences
+Maps to: app.notifications.*
+"""
+type Preference_App_Notifications {
+    email: Preference_App_Notifications_Email
+}
+
+"""
+Application preferences
+Maps to: app.*
+"""
+type Preference_App {
+    notifications: Preference_App_Notifications
+}
+
+"""
+Extend the global Preferences type
+"""
+extend type Preferences {
+    app: Preference_App
+}
+```
+
+**Step 4: Bind in Container**
+
+```typescript
+// module.ts
+import { ContainerModule, interfaces } from 'inversify';
+import { AddNotificationsConfigurationsMigration } from '../migrations';
+
+export const notificationsModule = () =>
+    new ContainerModule((bind: interfaces.Bind) => {
+        // ... other bindings ...
+
+        bind('MongodbMigration')
+            .to(AddNotificationsConfigurationsMigration)
+            .whenTargetNamed(AddNotificationsConfigurationsMigration.name);
+    });
+```
+
+---
+
+## Architecture Overview
+
+### System Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│              1. CONTRIBUTION LAYER                           │
+│  Flattened Keys: 'account.notification.primaryEmail'        │
+│  ─────────────────────────────────────────────────────────  │
+│  Files: preferences/settings/*-contribution.ts               │
+│  Format: IConfigurationSchemaMap with dot notation          │
+│  Purpose: Define configuration schema with types & defaults │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│              2. MIGRATION LAYER                              │
+│  Registers configurations to MongoDB                         │
+│  ─────────────────────────────────────────────────────────  │
+│  Files: migrations/dbMigrations/Add*Configurations*.ts      │
+│  Extends: BaseConfigurationsMigration                       │
+│  Purpose: Load settings into configuration registry         │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│              3. GRAPHQL LAYER                                │
+│  Nested Types: Preference_Account.notification.primaryEmail │
+│  ─────────────────────────────────────────────────────────  │
+│  Files: graphql/schema/preferences.graphql                  │
+│  Format: Nested type definitions                            │
+│  Purpose: Expose preferences via GraphQL API                │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│              4. DEPENDENCY INJECTION                         │
+│  Binds migration to container                                │
+│  ─────────────────────────────────────────────────────────  │
+│  Files: containers/module.ts                                │
+│  Framework: InversifyJS                                     │
+│  Purpose: Make migration discoverable & executable          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Key Components
+
+| Component        | Purpose                     | Format                              |
+| ---------------- | --------------------------- | ----------------------------------- |
+| **Contribution** | Define configuration schema | Flattened keys with metadata        |
+| **Migration**    | Register to database        | Extends BaseConfigurationsMigration |
+| **GraphQL**      | API exposure                | Nested type definitions             |
+| **DI Binding**   | Make discoverable           | InversifyJS binding                 |
+
+---
+
+## Complete Implementation Guide
+
+### Step 1: Create Configuration Contribution
+
+**Location:** `packages-modules/{module}/server/src/preferences/settings/{feature}-contribution.ts`
+
+**Purpose:** Define all configuration properties with flattened dot-notation keys.
+
+```typescript
+import { IConfigurationSchemaMap } from '@adminide-stack/core';
+import * as nls from '@vscode-alt/monaco-editor/esm/vs/nls';
+import { ConfigurationScope } from 'common/server';
+
+/**
+ * Account preferences contribution
+ * Uses flattened dot notation for all configuration keys
+ * Pattern: {module}.{section}.{subsection}.{property}
+ */
+export const AccountsContribution: IConfigurationSchemaMap = {
+    // ========================================
+    // Notification Settings
+    // ========================================
+    'account.notification.primaryEmail': {
+        type: 'string',
+        default: '',
+        description: nls.localize('accountNotificationPrimaryEmail', 'Notification Primary Email'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+    'account.notification.onChangeAccountSettings': {
+        type: 'boolean',
+        default: true,
+        description: nls.localize(
+            'notifyOnChangeAccountSettings',
+            'Notifies you when you change your account settings',
+        ),
+        scope: ConfigurationScope.APPLICATION,
+    },
+    'account.notification.billing': {
+        type: 'boolean',
+        default: true,
+        description: nls.localize('SubscribeToBillingNotifications', 'Subscribe to all billing changes'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+
+    // Nested professional information
+    'account.notification.professional.companyName': {
+        type: 'string',
+        default: '',
+        description: nls.localize('professionalCompanyName', 'Company Name'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+    'account.notification.professional.companyEmail': {
+        type: 'string',
+        default: '',
+        description: nls.localize('professionalCompanyEmail', 'Company Email'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+    'account.notification.professional.companyPhone': {
+        type: 'string',
+        default: '',
+        description: nls.localize('professionalCompanyPhone', 'Company Phone'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+
+    // ========================================
+    // Default Settings
+    // ========================================
+    'account.default.organization': {
+        type: 'string',
+        default: '',
+        description: nls.localize('accountDefaultOrganization', 'Default organization for your account'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+    'account.default.language': {
+        type: 'string',
+        default: 'en',
+        description: nls.localize('accountDefaultLanguage', 'Preferred language'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+    'account.default.timezone': {
+        type: 'string',
+        default: 'UTC',
+        description: nls.localize('accountDefaultTimezone', 'Default timezone'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+};
+
+/**
+ * Organization preferences contribution
+ */
+export const OrganizationContribution: IConfigurationSchemaMap = {
+    'organization.notification.notifyOrgManagersOnUserJoined': {
+        type: 'boolean',
+        default: false,
+        description: nls.localize('notifyOrgManagersOnUserJoined', 'Notify organization manager about new member'),
+        scope: ConfigurationScope.WINDOW,
+    },
+    'organization.notification.notifyOrgOwnerOnUserJoined': {
+        type: 'boolean',
+        default: false,
+        description: nls.localize('notifyOrgOwnerOnUserJoined', 'Notify owner about new member'),
+        scope: ConfigurationScope.WINDOW,
+    },
+    'organization.teams.visibility': {
+        type: 'string',
+        enum: ['private', 'public'],
+        default: 'private',
+        enumDescriptions: [
+            nls.localize(
+                'project.team.shareType.private',
+                'Only people you give access to will be able to view this team',
+            ),
+            nls.localize('project.team.shareType.public', 'Anyone on the internet can view the team.'),
+        ],
+        description: nls.localize('organizationTeamsVisibility', 'Teams Visibility'),
+        scope: ConfigurationScope.RESOURCE,
+    },
+};
+```
+
+**Configuration Properties:**
+
+| Property           | Type               | Required | Description                                                 |
+| ------------------ | ------------------ | -------- | ----------------------------------------------------------- |
+| `type`             | string             | Yes      | Data type: 'string', 'boolean', 'number', 'array', 'object' |
+| `default`          | any                | Yes      | Default value for the setting                               |
+| `description`      | string             | Yes      | Human-readable description (use nls.localize)               |
+| `scope`            | ConfigurationScope | Yes      | Where the setting applies                                   |
+| `enum`             | array              | No       | Allowed values for the setting                              |
+| `enumDescriptions` | array              | No       | Descriptions for each enum value                            |
+
+**Configuration Scopes:**
+
+| Scope                  | Use Case                        | Example                  |
+| ---------------------- | ------------------------------- | ------------------------ |
+| `APPLICATION`          | User-specific settings          | Email preferences, theme |
+| `WINDOW`               | Workspace/Organization settings | Org notifications        |
+| `RESOURCE`             | Project/Team specific           | Project visibility       |
+| `LANGUAGE_OVERRIDABLE` | Per-language settings           | Code formatting          |
+| `MACHINE`              | System-wide settings            | Installation path        |
+| `MACHINE_OVERRIDABLE`  | System with user override       | Proxy settings           |
+
+---
+
+### Step 2: Export Contributions
+
+**Location:** `packages-modules/{module}/server/src/preferences/settings/index.ts`
+
+```typescript
+import { TeamsContribution } from './teams-contribution';
+import { AccountsContribution } from './accounts-contribution';
+import { OrganizationContribution } from './organization-contribution';
+import { GlobalContribution } from './global-contribution';
+import { UiLayoutContribution } from './ui-layout-contribution';
+
+/**
+ * Combine all setting contributions
+ * These will be merged and registered in the migration
+ */
+export const SettingsContributions = [
+    TeamsContribution,
+    AccountsContribution,
+    OrganizationContribution,
+    GlobalContribution,
+];
+
+// Export special contributions separately if they need different handling
+export { UiLayoutContribution };
+```
+
+**Main Export:**
+
+```typescript
+// preferences/index.ts
+export * from './settings';
+export * from './roles';
+export * from './policies';
+```
+
+---
+
+### Step 3: Create Migration Script
+
+**Location:** `packages-modules/{module}/server/src/migrations/dbMigrations/Add{Module}ConfigurationsMigration.ts`
+
+```typescript
+import { IConfigurationRegistry } from '@adminide-stack/core';
+import { inject, injectable } from 'inversify';
+import type { Connection } from 'mongoose';
+import { CdmLogger } from '@cdm-logger/core';
+import { SERVER_TYPES, IRedisCacheManager, ContributionSchemaId, ContributionFragmentName } from 'common/server';
+import { BaseConfigurationsMigration, ISchemaConfiguration, ISchemaOverride } from '@adminide-stack/platform-server';
+import {
+    AccountPermissionsContribution,
+    AccountRolesContribution,
+    PoliciesContribution,
+    SettingsContributions,
+    AccountRolesPermissionOverwrite,
+    UiLayoutContribution,
+} from '../../preferences';
+
+/**
+ * Migration to register all account-related configurations
+ *
+ * This migration:
+ * 1. Registers settings, permissions, roles, and policies
+ * 2. Loads them into the configuration registry (MongoDB)
+ * 3. Provides up/down methods for migration control
+ *
+ * @injectable Marks this class for dependency injection
+ */
+@injectable()
+export class AddAccountsConfigurationsMigration extends BaseConfigurationsMigration {
+    /**
+     * Module name - used for namespacing configurations
+     * Must match the module identifier in the system
+     */
+    name = 'account';
+
+    constructor(
+        @inject('MongoDBConnection') db: Connection,
+        @inject(SERVER_TYPES.IConfigurationRegistry) configurationRegistry: IConfigurationRegistry,
+        @inject('Logger') logger: CdmLogger.ILogger,
+        @inject(SERVER_TYPES.IRedisCacheManager) redisCacheManager: IRedisCacheManager,
+    ) {
+        super(db, configurationRegistry, redisCacheManager, logger);
+    }
+
+    /**
+     * Unique ID for this migration
+     *
+     * Format: {ClassName}_{YYYYMMDD}
+     * IMPORTANT: Never reuse migration IDs, always update the date
+     */
+    get id() {
+        return `${AddAccountsConfigurationsMigration.name}_20250719`;
+    }
+
+    /**
+     * Policy configurations
+     * Define access policies for resources
+     *
+     * @returns Merged policy contributions
+     */
+    get policies() {
+        return PoliciesContribution.reduce(
+            (acc, curr) => ({
+                ...acc,
+                ...curr,
+            }),
+            {},
+        );
+    }
+
+    /**
+     * Role configurations
+     * Define available roles in the system
+     *
+     * Example structure:
+     * {
+     *   'account:admin': { description: 'Account Administrator', ... },
+     *   'account:user': { description: 'Regular User', ... }
+     * }
+     */
+    get roles() {
+        return AccountRolesContribution;
+    }
+
+    /**
+     * Permission configurations
+     * Define granular permissions
+     *
+     * Example structure:
+     * {
+     *   'account.read': { description: 'Read account data', ... },
+     *   'account.write': { description: 'Modify account data', ... }
+     * }
+     */
+    get permissions() {
+        return AccountPermissionsContribution;
+    }
+
+    /**
+     * Settings configurations
+     * Merge all setting contributions into a single object
+     *
+     * This combines:
+     * - AccountsContribution
+     * - OrganizationContribution
+     * - TeamsContribution
+     * - GlobalContribution
+     */
+    get settings() {
+        return SettingsContributions.reduce(
+            (acc, curr) => ({
+                ...acc,
+                ...curr,
+            }),
+            {},
+        );
+    }
+
+    /**
+     * Permission overrides
+     * Override default permissions for specific roles
+     *
+     * Example structure:
+     * {
+     *   'account:admin': {
+     *     'account.read': true,
+     *     'account.write': true,
+     *     'account.delete': true
+     *   }
+     * }
+     */
+    get permissionsOverride() {
+        return AccountRolesPermissionOverwrite;
+    }
+
+    /**
+     * Additional schema configurations
+     * Use this to add custom schemas beyond the standard ones
+     * (settings, policies, permissions, roles)
+     *
+     * @returns Array of additional schema configurations
+     */
+    protected getAdditionalSchemaConfigurations(): ISchemaConfiguration[] {
+        return [
+            this.addSchemaConfiguration(
+                ContributionFragmentName.Settings,
+                ContributionSchemaId.UiLayout,
+                UiLayoutContribution,
+                {
+                    priority: 50,
+                    condition: () => true, // Always enable UI Layout
+                },
+            ),
+        ];
+    }
+
+    /**
+     * Additional schema overrides
+     * Use this to override schemas with custom values
+     *
+     * @returns Array of schema overrides
+     */
+    protected getAdditionalSchemaOverrides(): ISchemaOverride[] {
+        return [
+            this.addSchemaOverride(
+                ContributionSchemaId.UiLayout,
+                {}, // No overrides needed for UI Layout
+                { priority: 50 },
+            ),
+        ];
+    }
+}
+```
+
+**Migration Lifecycle:**
+
+```typescript
+// Migration is automatically discovered and executed
+// Up: migration.up() - Registers configurations
+// Down: migration.down() - Deregisters configurations and clears cache
+```
+
+---
+
+### Step 4: Create GraphQL Schema
+
+**Location:** `packages-modules/{module}/server/src/graphql/schema/preferences.graphql`
+
+**Purpose:** Define nested GraphQL types that map to flattened configuration keys.
+
+```graphql
+# ============================================
+# SYSTEM EXTENSIONS
+# ============================================
+
+"""
+Extend the system contribution names
+Add your module name here
+"""
+extend enum SystemContributionExtensionNames {
+    account
+    organization
+}
+
+# ============================================
+# ACCOUNT PREFERENCES
+# Flattened: account.*
+# ============================================
+
+"""
+Professional account information
+Maps to flattened keys: account.notification.professional.*
+"""
+type Preference_Account_Professional {
+    """
+    Company name
+    Flattened key: account.notification.professional.companyName
+    """
+    companyName: String
+
+    """
+    Company email address
+    Flattened key: account.notification.professional.companyEmail
+    """
+    companyEmail: String
+
+    """
+    Company phone number
+    Flattened key: account.notification.professional.companyPhone
+    """
+    companyPhone: String
+
+    """
+    Company website URL
+    Flattened key: account.notification.professional.companyWebsite
+    """
+    companyWebsite: String
+}
+
+"""
+Account notification preferences
+Maps to flattened keys: account.notification.*
+"""
+type Preference_Account_Notification {
+    """
+    Primary email for notifications
+    Flattened key: account.notification.primaryEmail
+    """
+    primaryEmail: String
+
+    """
+    Notify on account settings changes
+    Flattened key: account.notification.onChangeAccountSettings
+    """
+    onChangeAccountSettings: Boolean
+
+    """
+    Subscribe to billing notifications
+    Flattened key: account.notification.billing
+    """
+    billing: Boolean
+
+    """
+    Professional information (nested object)
+    Maps to: account.notification.professional.*
+    """
+    professional: Preference_Account_Professional
+}
+
+"""
+Account default settings
+Maps to flattened keys: account.default.*
+"""
+type Preference_Account_Default {
+    """
+    Preferred language
+    Flattened key: account.default.language
+    """
+    language: String
+
+    """
+    Default timezone
+    Flattened key: account.default.timezone
+    """
+    timezone: String
+
+    """
+    Default organization ID
+    Flattened key: account.default.organization
+    """
+    organization: String
+}
+
+"""
+Root account preferences
+Maps to flattened keys: account.*
+"""
+type Preference_Account {
+    """
+    Account roles (array)
+    Flattened key: account.roles
+    """
+    roles: [String]
+
+    """
+    Whether account is soft-deleted
+    Flattened key: account.isDeleted
+    """
+    isDeleted: Boolean
+
+    """
+    Whether account is verified
+    Flattened key: account.isVerified
+    """
+    isVerified: Boolean
+
+    """
+    Default settings
+    Maps to: account.default.*
+    """
+    default: Preference_Account_Default
+
+    """
+    Notification settings
+    Maps to: account.notification.*
+    """
+    notification: Preference_Account_Notification
+}
+
+# ============================================
+# ORGANIZATION PREFERENCES
+# Flattened: organization.*
+# ============================================
+
+"""
+Organization notification preferences
+Maps to flattened keys: organization.notification.*
+"""
+type Pref_Org_Notification {
+    """
+    Notify managers when new user joins
+    Flattened key: organization.notification.notifyOrgManagersOnUserJoined
+    """
+    notifyOrgManagersOnUserJoined: Boolean
+
+    """
+    Notify owner when new user joins
+    Flattened key: organization.notification.notifyOrgOwnerOnUserJoined
+    """
+    notifyOrgOwnerOnUserJoined: Boolean
+}
+
+"""
+Team preferences
+Maps to flattened keys: organization.teams.*
+"""
+type Preference_Teams {
+    """
+    Team visibility setting
+    Flattened key: organization.teams.visibility
+    """
+    visibility: TeamVisibility
+
+    """
+    How new members can join the team
+    """
+    joinMethod: TeamJoinMethod
+
+    """
+    Invite code for link-based joining
+    """
+    inviteCode: String
+}
+
+"""
+Organization-level preferences
+Groups organization.* preferences
+"""
+type OrganizationPreferences {
+    """
+    Notification settings
+    Maps to: organization.notification.*
+    """
+    notification: Pref_Org_Notification
+
+    """
+    Team settings
+    Maps to: organization.teams.*
+    """
+    teams: Preference_Teams
+}
+
+# ============================================
+# EXTEND BASE PREFERENCES TYPE
+# ============================================
+
+"""
+Extend the global Preferences type
+This is the root query type for all preferences
+Each module extends this with its own preferences
+"""
+extend type Preferences {
+    """
+    Account-specific preferences
+    Contains all account.* settings from AccountsContribution
+    """
+    account: Preference_Account
+
+    """
+    Organization-specific preferences
+    Contains all organization.* settings from OrganizationContribution
+    """
+    organization: OrganizationPreferences
+}
+
+# ============================================
+# INPUT TYPES (for mutations)
+# ============================================
+
+"""
+Input type for updating professional information
+"""
+input Preference_Account_ProfessionalInput {
+    companyName: String
+    companyEmail: String
+    companyPhone: String
+    companyWebsite: String
+}
+
+"""
+Input type for updating notification preferences
+"""
+input Preference_Account_NotificationInput {
+    primaryEmail: String
+    onChangeAccountSettings: Boolean
+    billing: Boolean
+    professional: Preference_Account_ProfessionalInput
+}
+
+"""
+Input type for updating default settings
+"""
+input Preference_Account_DefaultInput {
+    language: String
+    timezone: String
+    organization: String
+}
+
+"""
+Input type for updating account preferences
+"""
+input Preference_AccountInput {
+    default: Preference_Account_DefaultInput
+    notification: Preference_Account_NotificationInput
+}
+
+"""
+Input type for updating organization notification preferences
+"""
+input Pref_Org_NotificationInput {
+    notifyOrgManagersOnUserJoined: Boolean
+    notifyOrgOwnerOnUserJoined: Boolean
+}
+
+"""
+Input type for updating team preferences
+"""
+input Preference_TeamsInput {
+    visibility: TeamVisibility
+    joinMethod: TeamJoinMethod
+    inviteCode: String
+}
+
+"""
+Input type for updating organization preferences
+"""
+input OrganizationPreferencesInput {
+    notification: Pref_Org_NotificationInput
+    teams: Preference_TeamsInput
+}
+
+# ============================================
+# ENUMS
+# ============================================
+
+enum TeamVisibility {
+    PRIVATE
+    PUBLIC
+}
+
+enum TeamJoinMethod {
+    INVITE_ONLY
+    LINK
+    AUTO
+}
+```
+
+---
+
+### Step 5: Register in DI Container
+
+**Location:** `packages-modules/{module}/server/src/containers/module.ts`
+
+```typescript
+import { ContainerModule, interfaces } from 'inversify';
+import {
+    AddAccountsRoleMigration,
+    AddStrategyPrefixToAliasesMigration,
+    MigrateOrganizationMembersToCollection,
+    AddOrganizationRolesMigration,
+    AddTeamRolesAndRenameMembersMigration,
+    AddAccountsConfigurationsMigration,
+    MigrateTeamsToNewSchema,
+    DropTeamsIndexMigration,
+} from '../migrations';
+
+export const accountsModule: (settings: any, pubsub) => interfaces.ContainerModule = (settings) =>
+    new ContainerModule((bind: interfaces.Bind, unbind: interfaces.Unbind) => {
+        // ... other bindings (repositories, services, data loaders) ...
+
+        // =============================================
+        // REGISTER MIGRATIONS
+        // =============================================
+
+        // Configuration Migration - MUST be registered
+        bind('MongodbMigration')
+            .to(AddAccountsConfigurationsMigration)
+            .whenTargetNamed(AddAccountsConfigurationsMigration.name);
+
+        // Other migrations
+        bind('MongodbMigration').to(AddAccountsRoleMigration).whenTargetNamed(AddAccountsRoleMigration.name);
+
+        bind('MongodbMigration').to(AddOrganizationRolesMigration).whenTargetNamed(AddOrganizationRolesMigration.name);
+
+        // ... more migrations ...
+    });
+```
+
+**Key Points:**
+
+- Use `bind('MongodbMigration')` as the service identifier
+- Use `.whenTargetNamed()` with migration class name
+- Migrations are automatically discovered and executed by the system
+
+---
+
+## Mapping Rules & Patterns
+
+### Flattened to Nested Conversion
+
+| Flattened Key (TypeScript)      | GraphQL Nested Path                        | GraphQL Type                      |
+| ------------------------------- | ------------------------------------------ | --------------------------------- |
+| `account.notification.email`    | `Preference_Account.notification.email`    | `Preference_Account_Notification` |
+| `account.default.organization`  | `Preference_Account.default.organization`  | `Preference_Account_Default`      |
+| `organization.teams.visibility` | `OrganizationPreferences.teams.visibility` | `Preference_Teams`                |
+| `app.settings.ui.theme`         | `Preference_App.settings.ui.theme`         | `Preference_App_Settings_Ui`      |
+
+### Type Naming Convention
+
+**Pattern:** `Preference_{Module}_{Section}_{Subsection}`
+
+**Examples:**
+
+```graphql
+# Simple: account.notification.email
+type Preference_Account_Notification {
+    email: String
+}
+
+# Nested: account.notification.professional.companyName
+type Preference_Account_Notification_Professional {
+    companyName: String
+}
+type Preference_Account_Notification {
+    professional: Preference_Account_Notification_Professional
+}
+
+# Deep nesting: app.settings.editor.formatting.indentSize
+type Preference_App_Settings_Editor_Formatting {
+    indentSize: Int
+}
+```
+
+### Conversion Algorithm
+
+```typescript
+/**
+ * Convert flattened key to GraphQL path
+ *
+ * @param flatKey - Flattened key (e.g., 'account.notification.email')
+ * @returns GraphQL path (e.g., 'Preference_Account.notification.email')
+ */
+function flattenedToGraphQL(flatKey: string): string {
+    const parts = flatKey.split('.');
+    const typeName = `Preference_${parts.map(capitalize).join('_')}`;
+    const path = parts.join('.');
+    return `${typeName} => ${path}`;
+}
+
+// Example:
+flattenedToGraphQL('account.notification.email');
+// Returns: "Preference_Account_Notification_Email => account.notification.email"
+```
+
+---
+
+## Real-World Examples
+
+### Example 1: Billing Module
+
+**Contribution:**
+
+```typescript
+// billing-contribution.ts
+export const BillingContribution: IConfigurationSchemaMap = {
+    'billing.payment.defaultMethod': {
+        type: 'string',
+        enum: ['credit_card', 'bank_transfer', 'paypal'],
+        default: 'credit_card',
+        description: nls.localize('billingDefaultPaymentMethod', 'Default payment method'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+    'billing.payment.autoPay': {
+        type: 'boolean',
+        default: false,
+        description: nls.localize('billingAutoPay', 'Enable automatic payments'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+    'billing.notification.invoiceEmail': {
+        type: 'string',
+        default: '',
+        description: nls.localize('billingInvoiceEmail', 'Email for invoice notifications'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+    'billing.notification.sendReminders': {
+        type: 'boolean',
+        default: true,
+        description: nls.localize('billingSendReminders', 'Send payment reminders'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+    'billing.subscription.plan': {
+        type: 'string',
+        enum: ['free', 'pro', 'enterprise'],
+        default: 'free',
+        description: nls.localize('billingSubscriptionPlan', 'Subscription plan'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+};
+```
+
+**Migration:**
+
+```typescript
+// AddBillingConfigurationsMigration.ts
+@injectable()
+export class AddBillingConfigurationsMigration extends BaseConfigurationsMigration {
+    name = 'billing';
+
+    constructor(
+        @inject('MongoDBConnection') db: Connection,
+        @inject(SERVER_TYPES.IConfigurationRegistry) configurationRegistry: IConfigurationRegistry,
+        @inject('Logger') logger: CdmLogger.ILogger,
+        @inject(SERVER_TYPES.IRedisCacheManager) redisCacheManager: IRedisCacheManager,
+    ) {
+        super(db, configurationRegistry, redisCacheManager, logger);
+    }
+
+    get id() {
+        return `${AddBillingConfigurationsMigration.name}_20250119`;
+    }
+    get policies() {
+        return {};
+    }
+    get roles() {
+        return {};
+    }
+    get permissions() {
+        return {};
+    }
+    get permissionsOverride() {
+        return {};
+    }
+
+    get settings() {
+        return BillingContribution;
+    }
+}
+```
+
+**GraphQL:**
+
+```graphql
+# billing.graphql
+
+enum PaymentMethod {
+    CREDIT_CARD
+    BANK_TRANSFER
+    PAYPAL
+}
+
+enum SubscriptionPlan {
+    FREE
+    PRO
+    ENTERPRISE
+}
+
+type Preference_Billing_Payment {
+    """
+    Maps to: billing.payment.defaultMethod
+    """
+    defaultMethod: PaymentMethod
+
+    """
+    Maps to: billing.payment.autoPay
+    """
+    autoPay: Boolean
+}
+
+type Preference_Billing_Notification {
+    """
+    Maps to: billing.notification.invoiceEmail
+    """
+    invoiceEmail: String
+
+    """
+    Maps to: billing.notification.sendReminders
+    """
+    sendReminders: Boolean
+}
+
+type Preference_Billing_Subscription {
+    """
+    Maps to: billing.subscription.plan
+    """
+    plan: SubscriptionPlan
+}
+
+type Preference_Billing {
+    payment: Preference_Billing_Payment
+    notification: Preference_Billing_Notification
+    subscription: Preference_Billing_Subscription
+}
+
+extend type Preferences {
+    billing: Preference_Billing
+}
+```
+
+**Query Example:**
+
+```graphql
+query GetBillingPreferences {
+    preferences {
+        billing {
+            payment {
+                defaultMethod
+                autoPay
+            }
+            notification {
+                invoiceEmail
+                sendReminders
+            }
+            subscription {
+                plan
+            }
+        }
+    }
+}
+```
+
+### Example 2: Project Management with Deep Nesting
+
+**Contribution:**
+
+```typescript
+// project-contribution.ts
+export const ProjectContribution: IConfigurationSchemaMap = {
+    // Three levels deep
+    'project.settings.access.defaultVisibility': {
+        type: 'string',
+        enum: ['private', 'public', 'team'],
+        default: 'private',
+        description: nls.localize('projectDefaultVisibility', 'Default project visibility'),
+        scope: ConfigurationScope.RESOURCE,
+    },
+    'project.settings.access.allowExternalCollaborators': {
+        type: 'boolean',
+        default: false,
+        description: nls.localize('projectAllowExternal', 'Allow external collaborators'),
+        scope: ConfigurationScope.RESOURCE,
+    },
+    'project.settings.notifications.emailOnUpdate': {
+        type: 'boolean',
+        default: true,
+        description: nls.localize('projectEmailOnUpdate', 'Email on project updates'),
+        scope: ConfigurationScope.RESOURCE,
+    },
+    'project.settings.notifications.digestFrequency': {
+        type: 'string',
+        enum: ['instant', 'daily', 'weekly', 'never'],
+        default: 'daily',
+        description: nls.localize('projectDigestFrequency', 'Notification digest frequency'),
+        scope: ConfigurationScope.RESOURCE,
+    },
+    'project.defaults.template': {
+        type: 'string',
+        default: '',
+        description: nls.localize('projectDefaultTemplate', 'Default project template'),
+        scope: ConfigurationScope.APPLICATION,
+    },
+};
+```
+
+**GraphQL:**
+
+```graphql
+# project.graphql
+
+enum ProjectVisibility {
+    PRIVATE
+    PUBLIC
+    TEAM
+}
+
+enum DigestFrequency {
+    INSTANT
+    DAILY
+    WEEKLY
+    NEVER
+}
+
+type Preference_Project_Settings_Access {
+    """
+    Maps to: project.settings.access.defaultVisibility
+    """
+    defaultVisibility: ProjectVisibility
+
+    """
+    Maps to: project.settings.access.allowExternalCollaborators
+    """
+    allowExternalCollaborators: Boolean
+}
+
+type Preference_Project_Settings_Notifications {
+    """
+    Maps to: project.settings.notifications.emailOnUpdate
+    """
+    emailOnUpdate: Boolean
+
+    """
+    Maps to: project.settings.notifications.digestFrequency
+    """
+    digestFrequency: DigestFrequency
+}
+
+type Preference_Project_Settings {
+    access: Preference_Project_Settings_Access
+    notifications: Preference_Project_Settings_Notifications
+}
+
+type Preference_Project_Defaults {
+    """
+    Maps to: project.defaults.template
+    """
+    template: String
+}
+
+type Preference_Project {
+    settings: Preference_Project_Settings
+    defaults: Preference_Project_Defaults
+}
+
+extend type Preferences {
+    project: Preference_Project
+}
+```
+
+### Example 3: Multiple Contributions in One Module
+
+**Index File:**
+
+```typescript
+// preferences/settings/index.ts
+import { AccountsContribution } from './accounts-contribution';
+import { OrganizationContribution } from './organization-contribution';
+import { TeamsContribution } from './teams-contribution';
+import { ProfileContribution } from './profile-contribution';
+
+export const SettingsContributions = [
+    AccountsContribution,
+    OrganizationContribution,
+    TeamsContribution,
+    ProfileContribution,
+];
+```
+
+**Migration:**
+
+```typescript
+// Automatically merges all contributions
+get settings() {
+    return SettingsContributions.reduce(
+        (acc, curr) => ({
+            ...acc,
+            ...curr,
+        }),
+        {},
+    );
+}
+```
+
+---
+
+## Frontend Consumption - Practical UI Usage
+
+### Overview
+
+The preferences system provides two hooks for consuming configurations in React components:
+
+1. **`useSettingsLoader`** - Uses data pre-loaded via Remix loader (faster, no GraphQL call)
+2. **`useSettings`** - Makes a GraphQL call to fetch settings (flexible, not pre-loaded)
+
+### Hook 1: useSettingsLoader (Recommended for Performance)
+
+**Purpose:** Access pre-loaded configurations that were fetched during Remix route loading.
+
+**Requirements:**
+
+- Must configure `configurations` in the route definition (compute.ts)
+- Data is available immediately without GraphQL calls
+- Best for frequently accessed preferences
+
+#### Configuration in Route (Required)
+
+**File:** `packages-modules/{module}/browser/src/modules/{feature}/compute.ts`
+
+```typescript
+import { IMenuPosition, IRouteModule } from '@common-stack/core';
+import { PreDefineAccountPermissions } from '@adminide-stack/core/lib/modules/account-api/enums/index.js';
+import { ConfigCollectionName, ConfigFragmentName } from 'common';
+
+export const accountPageStore: IRouteModule[] = [
+    {
+        name: 'menu.account_settings',
+        key: 'account-settings',
+        path: `${ORG_STD_ROUTES.USER_BASE_PATH}/account-settings`,
+        tab: 'Settings',
+        auth: true,
+        authority: [PreDefineAccountPermissions.viewSettings],
+        extraPermissions: [PreDefineAccountPermissions.editSettings],
+        component: () => import('./components/Settings/AccountsSettings'),
+
+        // ============================================
+        // CONFIGURE WHICH SETTINGS TO PRE-LOAD
+        // ============================================
+
+        // Option 1: Load ALL configurations
+        configurations: ['*'],
+
+        // Option 2: Load specific top-level keys only
+        // configurations: ['account', 'organization', 'billing'],
+
+        extraParams: {
+            resourceParams: {
+                resourceType: ConfigCollectionName.Accounts,
+                resourceId: '$params.orgName',
+                organization: '$params.orgName',
+                fragment: ConfigFragmentName.Settings,
+            },
+        },
+    },
+];
+```
+
+**Configuration Options:**
+
+| Value                         | Behavior                     | Use Case                             |
+| ----------------------------- | ---------------------------- | ------------------------------------ |
+| `['*']`                       | Load all configurations      | Settings pages with many preferences |
+| `['account']`                 | Load only `account.*` keys   | Page only uses account preferences   |
+| `['account', 'organization']` | Load multiple top-level keys | Page uses multiple modules           |
+| Not set or `[]`               | No pre-loading               | Use `useSettings` instead            |
+
+#### Usage in Components
+
+**Complete Key - Get Final Value:**
+
+```typescript
+import React from 'react';
+import { useSettingsLoader } from '@adminide-stack/platform-client';
+
+export const NotificationSettings = () => {
+    // Get a specific string value with full key path
+    const { data: primaryEmail, loading, error, updateConfiguration } = useSettingsLoader({
+        configKey: 'account.notification.primaryEmail',
+    });
+
+    // data type: string (inferred from flattened key)
+    console.log(primaryEmail); // "user@example.com"
+
+    const handleUpdateEmail = async (newEmail: string) => {
+        await updateConfiguration({
+            value: { 'account.notification.primaryEmail': newEmail },
+            target: 'user',
+        });
+    };
+
+    if (loading) return <div>Loading...</div>;
+    if (error) return <div>Error: {error.message}</div>;
+
+    return (
+        <div>
+            <h3>Primary Email</h3>
+            <input
+                type="email"
+                value={primaryEmail || ''}
+                onChange={(e) => handleUpdateEmail(e.target.value)}
+            />
+        </div>
+    );
+};
+```
+
+**Higher-Level Key - Get Object:**
+
+```typescript
+import React from 'react';
+import { useSettingsLoader } from '@adminide-stack/platform-client';
+
+export const InvitationPage = ({ decoded }) => {
+    // Get entire notification object with partial key
+    const { data: notification, loading, error } = useSettingsLoader({
+        configKey: 'organization.notification',
+    });
+
+    // data type: IOrganizationNotificationValues (inferred)
+    // notification = {
+    //   notifyOrgManagersOnUserJoined: true,
+    //   notifyOrgOwnerOnUserJoined: false
+    // }
+
+    const acceptInvitation = () => {
+        accept({
+            variables: {
+                id: decoded.invitationId,
+                notification, // Pass entire object to mutation
+            },
+        });
+    };
+
+    if (loading) return <div>Loading...</div>;
+
+    return (
+        <div>
+            <h3>Invitation for {decoded.orgName}</h3>
+            <p>Manager notifications: {notification?.notifyOrgManagersOnUserJoined ? 'Yes' : 'No'}</p>
+            <p>Owner notifications: {notification?.notifyOrgOwnerOnUserJoined ? 'Yes' : 'No'}</p>
+            <button onClick={acceptInvitation}>Accept</button>
+        </div>
+    );
+};
+```
+
+**Complete Example with All Features:**
+
+```typescript
+import React, { useState } from 'react';
+import { useSettingsLoader } from '@adminide-stack/platform-client';
+
+export const AccountSettingsPage = () => {
+    // Get entire account preferences object
+    const {
+        data: accountPrefs,
+        loading,
+        error,
+        updateConfiguration,
+        preferencesInput
+    } = useSettingsLoader({
+        configKey: 'account',
+    });
+
+    // accountPrefs type: Preference_Account
+    // accountPrefs = {
+    //   notification: {
+    //     primaryEmail: "user@example.com",
+    //     billing: true,
+    //     onChangeAccountSettings: true,
+    //     professional: {
+    //       companyName: "Acme Corp",
+    //       companyEmail: "info@acme.com"
+    //     }
+    //   },
+    //   default: {
+    //     organization: "my-org",
+    //     language: "en",
+    //     timezone: "UTC"
+    //   }
+    // }
+
+    const [email, setEmail] = useState(accountPrefs?.notification?.primaryEmail || '');
+
+    const handleSave = async () => {
+        try {
+            await updateConfiguration({
+                value: {
+                    'account.notification.primaryEmail': email,
+                    'account.notification.billing': true,
+                },
+                target: 'user',
+            });
+            console.log('Settings updated successfully');
+        } catch (err) {
+            console.error('Failed to update settings:', err);
+        }
+    };
+
+    if (loading) return <div>Loading preferences...</div>;
+    if (error) return <div>Error: {error.message}</div>;
+
+    return (
+        <div>
+            <h2>Account Settings</h2>
+
+            {/* Access nested values */}
+            <section>
+                <h3>Notification Settings</h3>
+                <div>
+                    <label>Primary Email:</label>
+                    <input
+                        type="email"
+                        value={email}
+                        onChange={(e) => setEmail(e.target.value)}
+                    />
+                </div>
+                <div>
+                    <label>
+                        <input
+                            type="checkbox"
+                            checked={accountPrefs?.notification?.billing}
+                        />
+                        Billing Notifications
+                    </label>
+                </div>
+            </section>
+
+            {/* Access professional info */}
+            <section>
+                <h3>Professional Information</h3>
+                <p>Company: {accountPrefs?.notification?.professional?.companyName || 'Not set'}</p>
+                <p>Email: {accountPrefs?.notification?.professional?.companyEmail || 'Not set'}</p>
+            </section>
+
+            {/* Access default settings */}
+            <section>
+                <h3>Default Settings</h3>
+                <p>Organization: {accountPrefs?.default?.organization}</p>
+                <p>Language: {accountPrefs?.default?.language}</p>
+                <p>Timezone: {accountPrefs?.default?.timezone}</p>
+            </section>
+
+            <button onClick={handleSave}>Save Changes</button>
+        </div>
+    );
+};
+```
+
+**Type Safety & Autocomplete:**
+
+```typescript
+import { useSettingsLoader } from '@adminide-stack/platform-client';
+import type { IConfigurationsFlattenedKeys, GetFlattenedValue } from 'common';
+
+export const TypeSafeComponent = () => {
+    // TypeScript provides autocomplete for all flattened keys
+    const { data } = useSettingsLoader({
+        configKey: 'account.notification.primaryEmail', // Autocomplete available!
+        //        ^-- Type: IConfigurationsFlattenedKeys
+    });
+
+    // Return type is automatically inferred
+    // data type: string (from 'account.notification.primaryEmail' configuration)
+
+    // Get partial object with type inference
+    const { data: notification } = useSettingsLoader({
+        configKey: 'organization.notification',
+        //        ^-- Autocomplete shows: organization.notification.notifyOrgManagersOnUserJoined
+        //                                organization.notification.notifyOrgOwnerOnUserJoined
+    });
+
+    // notification type: { notifyOrgManagersOnUserJoined?: boolean, notifyOrgOwnerOnUserJoined?: boolean }
+};
+```
+
+### Hook 2: useSettings (For Non-Pre-loaded Settings)
+
+**Purpose:** Fetch settings via GraphQL when they're not pre-loaded in the route.
+
+**Use Cases:**
+
+- Dynamic components not tied to specific routes
+- Modal dialogs or popups
+- Components that need settings on-demand
+- When you don't want to pre-load all settings
+
+#### Usage
+
+```typescript
+import React from 'react';
+import { useSettings } from '@adminide-stack/platform-client';
+import { URI } from '@adminide-stack/core';
+
+export const DynamicSettingsComponent = ({ resourceUri }: { resourceUri: string }) => {
+    const {
+        data,           // The specific value from configKey
+        settings,       // All settings object
+        pageSettings,   // Complete page settings with metadata
+        loading,
+        error,
+        updateConfiguration
+    } = useSettings({
+        resourceUri: resourceUri as URI,
+        options: {
+            configKey: 'organization.notification.notifyOrgOwnerOnUserJoined',
+        },
+    });
+
+    // data type: boolean (the value of the specific key)
+    console.log(data); // true or false
+
+    // settings: complete settings object
+    console.log(settings); // { account: {...}, organization: {...}, ... }
+
+    const handleToggle = async () => {
+        await updateConfiguration({
+            value: {
+                'organization.notification.notifyOrgOwnerOnUserJoined': !data
+            },
+            target: 'organization',
+        });
+    };
+
+    if (loading) return <div>Loading...</div>;
+    if (error) return <div>Error: {error.message}</div>;
+
+    return (
+        <div>
+            <label>
+                <input
+                    type="checkbox"
+                    checked={data || false}
+                    onChange={handleToggle}
+                />
+                Notify Owner on User Joined
+            </label>
+        </div>
+    );
+};
+```
+
+**Get Complete Settings Object:**
+
+```typescript
+export const CompleteSettingsView = ({ resourceUri }: { resourceUri: string }) => {
+    // Don't provide configKey to get all settings
+    const { settings, loading } = useSettings({
+        resourceUri: resourceUri as URI,
+        options: {
+            // No configKey = get all settings
+        },
+    });
+
+    // settings contains all configuration data
+    console.log(settings?.account?.notification?.primaryEmail);
+    console.log(settings?.organization?.teams?.visibility);
+
+    return (
+        <div>
+            <h2>All Settings</h2>
+            <pre>{JSON.stringify(settings, null, 2)}</pre>
+        </div>
+    );
+};
+```
+
+### Comparison: useSettingsLoader vs useSettings
+
+| Feature                    | useSettingsLoader                  | useSettings                |
+| -------------------------- | ---------------------------------- | -------------------------- |
+| **Data Source**            | Remix loader (pre-loaded)          | GraphQL query (on-demand)  |
+| **Performance**            | ⚡ Instant (no network call)       | 🔄 Network call required   |
+| **Configuration Required** | ✅ Yes (`configurations` in route) | ❌ No route config needed  |
+| **Use Case**               | Route-based pages                  | Dynamic components, modals |
+| **Type Safety**            | ✅ Full autocomplete               | ✅ Full autocomplete       |
+| **Cache**                  | Loader cache                       | Apollo cache               |
+| **Updates**                | Via updateConfiguration            | Via updateConfiguration    |
+
+### Update Configuration Pattern
+
+Both hooks provide `updateConfiguration` method with the same API:
+
+```typescript
+const { updateConfiguration } = useSettingsLoader({ configKey: 'account' });
+// or
+const { updateConfiguration } = useSettings({ resourceUri, options: {} });
+
+// Update single value
+await updateConfiguration({
+    value: {
+        'account.notification.primaryEmail': 'new@email.com',
+    },
+    target: 'user', // or 'organization', 'team', etc.
+});
+
+// Update multiple values
+await updateConfiguration({
+    value: {
+        'account.notification.primaryEmail': 'new@email.com',
+        'account.notification.billing': true,
+        'account.default.timezone': 'America/New_York',
+    },
+    target: 'user',
+    updateOverrides: {
+        resource: 'org://my-org/settings',
+    },
+});
+```
+
+### Real-World Examples
+
+#### Example 1: Settings Page with Pre-loaded Data
+
+**Route Configuration:**
+
+```typescript
+// compute.ts
+{
+    key: 'account-settings',
+    path: '/settings/account',
+    component: () => import('./AccountSettings'),
+    configurations: ['account', 'organization'], // Pre-load these keys
+}
+```
+
+**Component:**
+
+```typescript
+// AccountSettings.tsx
+import { useSettingsLoader } from '@adminide-stack/platform-client';
+
+export const AccountSettings = () => {
+    // All data is pre-loaded, no GraphQL call
+    const { data: account } = useSettingsLoader({ configKey: 'account' });
+    const { data: org } = useSettingsLoader({ configKey: 'organization' });
+
+    return (
+        <div>
+            <h2>Account Settings</h2>
+            <p>Email: {account?.notification?.primaryEmail}</p>
+            <p>Org Notifications: {org?.notification?.notifyOrgOwnerOnUserJoined ? 'On' : 'Off'}</p>
+        </div>
+    );
+};
+```
+
+#### Example 2: Modal with Dynamic Settings
+
+**No route configuration needed:**
+
+```typescript
+// NotificationModal.tsx
+import { useSettings } from '@adminide-stack/platform-client';
+
+export const NotificationModal = ({ isOpen, orgUri }) => {
+    // Makes GraphQL call when modal opens
+    const { data: notifyOwner, updateConfiguration } = useSettings({
+        resourceUri: orgUri,
+        options: {
+            configKey: 'organization.notification.notifyOrgOwnerOnUserJoined',
+        },
+        skip: !isOpen, // Don't fetch until modal opens
+    });
+
+    if (!isOpen) return null;
+
+    return (
+        <div className="modal">
+            <h3>Notification Settings</h3>
+            <label>
+                <input
+                    type="checkbox"
+                    checked={notifyOwner || false}
+                    onChange={async (e) => {
+                        await updateConfiguration({
+                            value: {
+                                'organization.notification.notifyOrgOwnerOnUserJoined': e.target.checked
+                            },
+                            target: 'organization',
+                        });
+                    }}
+                />
+                Notify owner when users join
+            </label>
+        </div>
+    );
+};
+```
+
+#### Example 3: Invitation Page (From Your Codebase)
+
+```typescript
+import React from 'react';
+import { useSettingsLoader } from '@adminide-stack/platform-client';
+import { useAcceptOrganizationInvitationMutation } from 'common/graphql';
+
+export const InvitationPage = ({ decoded }) => {
+    // Pre-loaded via route configuration
+    const { data: notification } = useSettingsLoader({
+        configKey: 'organization.notification',
+    });
+
+    const [accept] = useAcceptOrganizationInvitationMutation();
+
+    const acceptInvitation = () => {
+        // Pass entire notification object to mutation
+        accept({
+            variables: {
+                id: decoded.invitationId,
+                notification, // { notifyOrgManagersOnUserJoined, notifyOrgOwnerOnUserJoined }
+            },
+        });
+    };
+
+    return (
+        <div>
+            <h2>Join {decoded.orgName}?</h2>
+            <p>Invited by: {decoded.invitedBy}</p>
+            <button onClick={acceptInvitation}>Accept Invitation</button>
+        </div>
+    );
+};
+```
+
+### Best Practices for Frontend
+
+1. **Use `useSettingsLoader` for route-based pages:**
+
+    ```typescript
+    // ✅ Good: Pre-load in route
+    configurations: ['account', 'organization'];
+    ```
+
+2. **Use `useSettings` for dynamic components:**
+
+    ```typescript
+    // ✅ Good: Modal that appears conditionally
+    const { data } = useSettings({ resourceUri, options: { configKey: '...' }, skip: !isOpen });
+    ```
+
+3. **Get objects for related settings:**
+
+    ```typescript
+    // ✅ Good: Get object when you need multiple related values
+    const { data: notification } = useSettingsLoader({
+        configKey: 'organization.notification',
+    });
+
+    // ❌ Bad: Multiple calls for related values
+    const { data: notify1 } = useSettingsLoader({
+        configKey: 'organization.notification.notifyOrgOwnerOnUserJoined',
+    });
+    const { data: notify2 } = useSettingsLoader({
+        configKey: 'organization.notification.notifyOrgManagersOnUserJoined',
+    });
+    ```
+
+4. **Configure route with minimal keys:**
+
+    ```typescript
+    // ✅ Good: Only load what you need
+    configurations: ['account']; // Page only uses account settings
+
+    // ❌ Bad: Load everything when you only need one module
+    configurations: ['*']; // Loads all settings unnecessarily
+    ```
+
+5. **Use skip option to defer loading:**
+    ```typescript
+    // ✅ Good: Don't fetch until needed
+    const { data } = useSettings({
+        resourceUri,
+        options: { configKey: '...' },
+        skip: !shouldFetch,
+    });
+    ```
+
+### Type Definitions Reference
+
+```typescript
+// Hook signatures
+function useSettingsLoader<K extends IConfigurationsFlattenedKeys, R = IPreferences>(
+    settingsVariable: ISettingsLoaderVariable<K>,
+): ISettingsLoaderResponse<K, GetFlattenedValue<R, K>>;
+
+function useSettings<T = any>(
+    variables: IPageSettingsConfigKeyVariable,
+): {
+    data: T;
+    settings: any;
+    pageSettings: any;
+    loading: boolean;
+    error: any;
+    updateConfiguration: (params) => Promise<any>;
+};
+
+// Variable types
+interface ISettingsLoaderVariable<K> {
+    configKey: K; // Autocomplete available
+    skip?: boolean;
+}
+
+interface IPageSettingsConfigKeyVariable {
+    resourceUri: URI | string;
+    options?: {
+        configKey?: string;
+    };
+    skip?: boolean;
+}
+```
+
+---
+
+## Testing & Validation
+
+### Unit Tests for Migration
+
+```typescript
+// AddAccountsConfigurationsMigration.test.ts
+import { Container } from 'inversify';
+import { AddAccountsConfigurationsMigration } from './AddAccountsConfigurationsMigration';
+
+describe('AddAccountsConfigurationsMigration', () => {
+    let migration: AddAccountsConfigurationsMigration;
+    let container: Container;
+
+    beforeEach(() => {
+        container = new Container();
+        // Mock dependencies
+        container.bind('MongoDBConnection').toConstantValue(mockConnection);
+        container.bind(SERVER_TYPES.IConfigurationRegistry).toConstantValue(mockRegistry);
+        container.bind('Logger').toConstantValue(mockLogger);
+        container.bind(SERVER_TYPES.IRedisCacheManager).toConstantValue(mockCache);
+
+        migration = container.resolve(AddAccountsConfigurationsMigration);
+    });
+
+    it('should have correct migration id with date', () => {
+        expect(migration.id).toBe('AddAccountsConfigurationsMigration_20250719');
+        expect(migration.id).toMatch(/_\d{8}$/);
+    });
+
+    it('should have module name', () => {
+        expect(migration.name).toBe('account');
+    });
+
+    it('should merge all settings contributions', () => {
+        const settings = migration.settings;
+
+        // Check AccountsContribution keys
+        expect(settings).toHaveProperty('account.notification.primaryEmail');
+        expect(settings).toHaveProperty('account.default.organization');
+
+        // Check OrganizationContribution keys
+        expect(settings).toHaveProperty('organization.notification.notifyOrgOwnerOnUserJoined');
+
+        // Check TeamsContribution keys
+        expect(settings).toHaveProperty('organization.teams.visibility');
+    });
+
+    it('should have valid configuration schema', () => {
+        const settings = migration.settings;
+
+        Object.entries(settings).forEach(([key, config]) => {
+            expect(config).toHaveProperty('type');
+            expect(config).toHaveProperty('default');
+            expect(config).toHaveProperty('description');
+            expect(config).toHaveProperty('scope');
+        });
+    });
+
+    it('should register configurations successfully', async () => {
+        const spy = jest.spyOn(mockRegistry, 'registerConfiguration');
+
+        await migration.up();
+
+        expect(spy).toHaveBeenCalled();
+        expect(spy.mock.calls.length).toBeGreaterThan(0);
+    });
+
+    it('should deregister configurations on down', async () => {
+        const spy = jest.spyOn(mockRegistry, 'deregisterConfigurations');
+
+        await migration.down();
+
+        expect(spy).toHaveBeenCalled();
+    });
+
+    it('should clear cache on down', async () => {
+        const spy = jest.spyOn(mockCache, 'del');
+
+        await migration.down();
+
+        expect(spy).toHaveBeenCalled();
+    });
+});
+```
+
+### GraphQL Schema Tests
+
+```graphql
+# test-preferences.graphql
+
+# Test query to verify all nested structures
+query TestCompletePreferences {
+    preferences {
+        account {
+            notification {
+                primaryEmail
+                onChangeAccountSettings
+                billing
+                professional {
+                    companyName
+                    companyEmail
+                    companyPhone
+                    companyWebsite
+                }
+            }
+            default {
+                organization
+                language
+                timezone
+            }
+            roles
+            isDeleted
+            isVerified
+        }
+        organization {
+            notification {
+                notifyOrgOwnerOnUserJoined
+                notifyOrgManagersOnUserJoined
+            }
+            teams {
+                visibility
+                joinMethod
+                inviteCode
+            }
+        }
+    }
+}
+
+# Test mutation
+mutation UpdateAccountPreferences($input: Preference_AccountInput!) {
+    updateAccountPreferences(input: $input) {
+        account {
+            notification {
+                primaryEmail
+                billing
+            }
+            default {
+                organization
+            }
+        }
+    }
+}
+```
+
+### Integration Tests
+
+```typescript
+// test-preferences-integration.ts
+import { gql } from 'apollo-server-express';
+import { createTestClient } from 'apollo-server-testing';
+
+describe('Preferences Integration', () => {
+    let testClient;
+
+    beforeAll(async () => {
+        // Setup test server
+        testClient = createTestClient(server);
+    });
+
+    it('should query nested preferences', async () => {
+        const query = gql`
+            query {
+                preferences {
+                    account {
+                        notification {
+                            primaryEmail
+                        }
+                    }
+                }
+            }
+        `;
+
+        const { data } = await testClient.query({ query });
+
+        expect(data.preferences.account.notification).toBeDefined();
+        expect(data.preferences.account.notification.primaryEmail).toBeDefined();
+    });
+
+    it('should update preferences', async () => {
+        const mutation = gql`
+            mutation ($input: Preference_AccountInput!) {
+                updateAccountPreferences(input: $input) {
+                    account {
+                        notification {
+                            primaryEmail
+                        }
+                    }
+                }
+            }
+        `;
+
+        const { data } = await testClient.mutate({
+            mutation,
+            variables: {
+                input: {
+                    notification: {
+                        primaryEmail: 'test@example.com',
+                    },
+                },
+            },
+        });
+
+        expect(data.updateAccountPreferences.account.notification.primaryEmail).toBe('test@example.com');
+    });
+});
+```
+
+### Manual Testing Commands
+
+```bash
+# Run migrations
+npm run migrate:up
+
+# Rollback migrations
+npm run migrate:down
+
+# Test GraphQL schema
+npm run test:graphql
+
+# Run integration tests
+npm run test:integration
+
+# Check MongoDB for registered configurations
+mongo
+> use your_database
+> db.configuration_registry.find({ 'context.extensionId': 'account' })
+```
+
+---
+
+## Best Practices
+
+### 1. Naming Conventions
+
+**Contributions:**
+
+- Format: `{Feature}Contribution`
+- Examples: `AccountsContribution`, `BillingContribution`, `ProjectContribution`
+
+**Migrations:**
+
+- Format: `Add{Module}ConfigurationsMigration`
+- Examples: `AddAccountsConfigurationsMigration`, `AddBillingConfigurationsMigration`
+
+**GraphQL Types:**
+
+- Format: `Preference_{Module}_{Section}_{Subsection}`
+- Examples: `Preference_Account_Notification`, `Preference_Billing_Payment`
+
+**Flattened Keys:**
+
+- Format: `{module}.{section}.{property}`
+- Examples: `account.notification.email`, `billing.payment.method`
+- Max depth: 4 levels (recommended)
+
+### 2. Configuration Schema Best Practices
+
+```typescript
+// ✅ GOOD: Clear, specific, with localization
+'account.notification.primaryEmail': {
+    type: 'string',
+    default: '',
+    description: nls.localize('accountNotificationPrimaryEmail', 'Notification Primary Email'),
+    scope: ConfigurationScope.APPLICATION,
+}
+
+// ❌ BAD: No localization, vague description
+'account.email': {
+    type: 'string',
+    default: '',
+    description: 'Email',
+    scope: ConfigurationScope.APPLICATION,
+}
+
+// ✅ GOOD: Enum with descriptions
+'billing.payment.method': {
+    type: 'string',
+    enum: ['credit_card', 'paypal', 'bank_transfer'],
+    enumDescriptions: [
+        nls.localize('paymentCreditCard', 'Pay with credit or debit card'),
+        nls.localize('paymentPaypal', 'Pay with PayPal account'),
+        nls.localize('paymentBank', 'Direct bank transfer'),
+    ],
+    default: 'credit_card',
+    description: nls.localize('billingPaymentMethod', 'Preferred payment method'),
+    scope: ConfigurationScope.APPLICATION,
+}
+```
+
+### 3. GraphQL Schema Best Practices
+
+```graphql
+# ✅ GOOD: Clear documentation with mapping
+"""
+Account notification preferences
+Maps to flattened keys: account.notification.*
+"""
+type Preference_Account_Notification {
+    """
+    Primary email for notifications
+    Flattened key: account.notification.primaryEmail
+    """
+    primaryEmail: String
+}
+
+# ❌ BAD: No documentation
+type Preference_Account_Notification {
+    primaryEmail: String
+}
+
+# ✅ GOOD: Use enums for restricted values
+enum PaymentMethod {
+    CREDIT_CARD
+    BANK_TRANSFER
+    PAYPAL
+}
+
+type Preference_Billing_Payment {
+    defaultMethod: PaymentMethod
+}
+
+# ❌ BAD: Use String without restriction
+type Preference_Billing_Payment {
+    defaultMethod: String
+}
+```
+
+### 4. Migration Best Practices
+
+```typescript
+// ✅ GOOD: Date-based versioning
+get id() {
+    return `${AddAccountsConfigurationsMigration.name}_20250119`;
+}
+
+// ❌ BAD: No versioning
+get id() {
+    return AddAccountsConfigurationsMigration.name;
+}
+
+// ✅ GOOD: Merge multiple contributions
+get settings() {
+    return SettingsContributions.reduce(
+        (acc, curr) => ({
+            ...acc,
+            ...curr,
+        }),
+        {},
+    );
+}
+
+// ❌ BAD: Return single contribution
+get settings() {
+    return AccountsContribution; // Missing other contributions
+}
+```
+
+### 5. Scope Selection Guidelines
+
+| Setting Type       | Recommended Scope      | Example                            |
+| ------------------ | ---------------------- | ---------------------------------- |
+| User preferences   | `APPLICATION`          | Theme, language, email             |
+| Workspace settings | `WINDOW`               | Org notifications, team defaults   |
+| Resource settings  | `RESOURCE`             | Project visibility, access control |
+| Format overrides   | `LANGUAGE_OVERRIDABLE` | Per-language formatting            |
+| System config      | `MACHINE`              | Installation paths, system proxy   |
+
+### 6. Key Hierarchy Guidelines
+
+```typescript
+// ✅ GOOD: Logical hierarchy (max 4 levels)
+'account.notification.email.frequency';
+'organization.teams.access.defaultVisibility';
+'project.settings.editor.formatting';
+
+// ❌ BAD: Too deep (5+ levels)
+'app.user.account.settings.notification.email.delivery.frequency';
+
+// ❌ BAD: Inconsistent structure
+'account.notificationEmail'; // Should be: account.notification.email
+'accountNotificationFrequency'; // Should be: account.notification.frequency
+```
+
+### 7. Documentation Best Practices
+
+```typescript
+/**
+ * Account preferences contribution
+ *
+ * Defines user-level account settings including:
+ * - Notification preferences
+ * - Default organization
+ * - Professional information
+ *
+ * All settings use ConfigurationScope.APPLICATION as they are user-specific.
+ *
+ * @example
+ * // Accessing in code:
+ * const email = configService.getValue('account.notification.primaryEmail');
+ *
+ * // In GraphQL:
+ * query {
+ *   preferences {
+ *     account {
+ *       notification {
+ *         primaryEmail
+ *       }
+ *     }
+ *   }
+ * }
+ */
+export const AccountsContribution: IConfigurationSchemaMap = {
+    // ... settings
+};
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### Issue 1: Settings not appearing in database
+
+**Symptoms:**
+
+- Migration runs successfully but settings don't appear in configuration registry
+- GraphQL queries return null for preferences
+
+**Solutions:**
+
+1. Check migration binding:
+
+    ```typescript
+    // Verify in module.ts
+    bind('MongodbMigration')
+        .to(AddAccountsConfigurationsMigration)
+        .whenTargetNamed(AddAccountsConfigurationsMigration.name);
+    ```
+
+2. Verify migration execution:
+
+    ```bash
+    # Check logs for migration execution
+    npm run migrate:up -- --verbose
+    ```
+
+3. Check MongoDB:
+
+    ```javascript
+    // Connect to MongoDB
+    db.configuration_registry.find({ 'context.extensionId': 'account' });
+    ```
+
+4. Verify contribution export:
+    ```typescript
+    // In settings/index.ts
+    export const SettingsContributions = [
+        AccountsContribution, // Must be included
+        // ...
+    ];
+    ```
+
+#### Issue 2: GraphQL type doesn't match flattened keys
+
+**Symptoms:**
+
+- GraphQL queries fail with "Cannot query field"
+- Type structure doesn't align with configuration keys
+
+**Solution:**
+Review the mapping systematically:
+
+```typescript
+// Flattened key
+'account.notification.professional.companyName'
+
+// Should map to GraphQL (split on dots):
+// 1. account → Preference_Account
+// 2. notification → Preference_Account_Notification
+// 3. professional → Preference_Account_Professional
+// 4. companyName → companyName: String
+
+type Preference_Account_Professional {
+    companyName: String  // ✅ Correct
+}
+```
+
+#### Issue 3: Cache not clearing after migration
+
+**Symptoms:**
+
+- Old preference values persist after migration
+- Changes don't reflect in queries
+
+**Solutions:**
+
+1. Verify Redis connection:
+
+    ```typescript
+    // Check redisCacheManager injection
+    @inject(SERVER_TYPES.IRedisCacheManager)
+    redisCacheManager: IRedisCacheManager,
+    ```
+
+2. Manually clear cache:
+
+    ```bash
+    # Connect to Redis
+    redis-cli
+    > FLUSHDB
+    ```
+
+3. Check cache clearing in down():
+    ```typescript
+    async down() {
+        await this.dropCache(); // Must be called
+        // ... deregister configurations
+    }
+    ```
+
+#### Issue 4: Migration fails with "No matching bindings"
+
+**Symptoms:**
+
+```
+Error: No matching bindings found for serviceIdentifier: Symbol(IConfigurationRegistry)
+```
+
+**Solution:**
+Ensure all dependencies are properly injected:
+
+```typescript
+constructor(
+    @inject('MongoDBConnection') db: Connection,
+    @inject(SERVER_TYPES.IConfigurationRegistry) configurationRegistry: IConfigurationRegistry,
+    @inject('Logger') logger: CdmLogger.ILogger,
+    @inject(SERVER_TYPES.IRedisCacheManager) redisCacheManager: IRedisCacheManager,
+) {
+    super(db, configurationRegistry, redisCacheManager, logger);
+}
+```
+
+#### Issue 5: Enum values not matching
+
+**Symptoms:**
+
+- GraphQL returns enum values in wrong case
+- Enum validation fails
+
+**Solution:**
+Ensure consistency between TypeScript and GraphQL:
+
+```typescript
+// TypeScript contribution
+enum: ['private', 'public'] // lowercase
+
+// GraphQL enum - convert to UPPERCASE
+enum TeamVisibility {
+    PRIVATE  # Maps to 'private'
+    PUBLIC   # Maps to 'public'
+}
+```
+
+#### Issue 6: Nested objects not saving
+
+**Symptoms:**
+
+- Top-level preferences save, but nested objects don't persist
+- Mutations succeed but queries return null for nested fields
+
+**Solution:**
+Ensure complete input type hierarchy:
+
+```graphql
+# Need complete chain of input types
+input Preference_Account_ProfessionalInput {
+    companyName: String
+}
+
+input Preference_Account_NotificationInput {
+    professional: Preference_Account_ProfessionalInput # Must include nested
+}
+
+input Preference_AccountInput {
+    notification: Preference_Account_NotificationInput # Must include parent
+}
+```
+
+---
+
+## Reference
+
+### File Structure
+
+```
+packages-modules/{module-name}/
+├── server/
+│   ├── src/
+│   │   ├── preferences/
+│   │   │   ├── index.ts                          # Export all preferences
+│   │   │   ├── settings/
+│   │   │   │   ├── index.ts                      # Export settings contributions
+│   │   │   │   ├── {feature}-contribution.ts     # Flattened keys
+│   │   │   │   └── ...
+│   │   │   ├── roles/
+│   │   │   │   └── index.ts                      # Role definitions
+│   │   │   └── policies/
+│   │   │       └── index.ts                      # Policy definitions
+│   │   ├── migrations/
+│   │   │   └── dbMigrations/
+│   │   │       └── Add{Module}ConfigurationsMigration.ts
+│   │   ├── graphql/
+│   │   │   └── schema/
+│   │   │       ├── preferences.graphql           # Nested types
+│   │   │       └── ...
+│   │   └── containers/
+│   │       └── module.ts                         # DI binding
+```
+
+### Quick Reference Table
+
+| Component          | File Location                            | Key Pattern                 | Export Format             |
+| ------------------ | ---------------------------------------- | --------------------------- | ------------------------- |
+| **Contribution**   | `preferences/settings/*-contribution.ts` | `module.section.property`   | `IConfigurationSchemaMap` |
+| **Settings Index** | `preferences/settings/index.ts`          | N/A                         | `SettingsContributions[]` |
+| **Migration**      | `migrations/dbMigrations/Add*.ts`        | N/A                         | `@injectable() class`     |
+| **GraphQL Types**  | `graphql/schema/preferences.graphql`     | `Preference_Module_Section` | GraphQL SDL               |
+| **DI Binding**     | `containers/module.ts`                   | N/A                         | InversifyJS binding       |
+
+### Configuration Scope Reference
+
+```typescript
+export enum ConfigurationScope {
+    APPLICATION = 1, // User-specific settings
+    WINDOW = 2, // Workspace/Organization settings
+    RESOURCE = 3, // Project/Team/Resource settings
+    LANGUAGE_OVERRIDABLE = 4, // Can be overridden per language
+    MACHINE = 5, // System-wide settings
+    MACHINE_OVERRIDABLE = 6, // System settings with user override
+}
+```
+
+### Common Imports
+
+```typescript
+// Contributions
+import { IConfigurationSchemaMap } from '@adminide-stack/core';
+import * as nls from '@vscode-alt/monaco-editor/esm/vs/nls';
+import { ConfigurationScope } from 'common/server';
+
+// Migrations
+import { IConfigurationRegistry } from '@adminide-stack/core';
+import { inject, injectable } from 'inversify';
+import type { Connection } from 'mongoose';
+import { CdmLogger } from '@cdm-logger/core';
+import { SERVER_TYPES, IRedisCacheManager, ContributionSchemaId, ContributionFragmentName } from 'common/server';
+import { BaseConfigurationsMigration, ISchemaConfiguration, ISchemaOverride } from '@adminide-stack/platform-server';
+
+// DI Container
+import { ContainerModule, interfaces } from 'inversify';
+```
+
+### Useful Commands
+
+```bash
+# Development
+npm run dev                    # Start development server
+npm run build                  # Build the project
+
+# Migrations
+npm run migrate:up             # Run all pending migrations
+npm run migrate:down           # Rollback last migration
+npm run migrate:status         # Check migration status
+
+# Testing
+npm run test                   # Run all tests
+npm run test:unit              # Run unit tests
+npm run test:integration       # Run integration tests
+npm run test:graphql           # Test GraphQL schema
+
+# Database
+npm run db:seed                # Seed database
+npm run db:reset               # Reset database
+
+# Debugging
+npm run migrate:up -- --verbose      # Verbose migration output
+npm run test -- --watch              # Watch mode for tests
+```
+
+### GraphQL Query Examples
+
+```graphql
+# Get all preferences
+query GetAllPreferences {
+    preferences {
+        account {
+            notification {
+                primaryEmail
+                billing
+            }
+            default {
+                organization
+            }
+        }
+        organization {
+            notification {
+                notifyOrgOwnerOnUserJoined
+            }
+        }
+    }
+}
+
+# Get specific preference section
+query GetAccountNotifications {
+    preferences {
+        account {
+            notification {
+                primaryEmail
+                onChangeAccountSettings
+                billing
+            }
+        }
+    }
+}
+
+# Update preferences
+mutation UpdatePreferences($input: Preference_AccountInput!) {
+    updateAccountPreferences(input: $input) {
+        account {
+            notification {
+                primaryEmail
+            }
+        }
+    }
+}
+```
+
+### MongoDB Queries
+
+```javascript
+// Find all configurations for a module
+db.configuration_registry.find({
+    'context.extensionId': 'account',
+});
+
+// Find specific configuration
+db.configuration_registry.findOne({
+    'node.id': 'account.notification.primaryEmail',
+});
+
+// Check migration status
+db.migrations.find().sort({ executedAt: -1 });
+
+// Clear configuration cache
+db.configuration_cache.deleteMany({});
+```
+
+---
+
+## Summary Checklist
+
+When creating new preferences, ensure you:
+
+### Configuration Phase
+
+- [ ] Create `{feature}-contribution.ts` with flattened keys
+- [ ] Use proper naming: `module.section.property`
+- [ ] Add type, default, description, and scope for each key
+- [ ] Use `nls.localize()` for all descriptions
+- [ ] Export in `settings/index.ts`
+- [ ] Add to `SettingsContributions` array
+
+### Migration Phase
+
+- [ ] Create migration extending `BaseConfigurationsMigration`
+- [ ] Set unique migration ID with date: `{ClassName}_YYYYMMDD`
+- [ ] Implement all required getters
+- [ ] Merge contributions in `settings` getter
+- [ ] Add `@injectable()` decorator
+
+### GraphQL Phase
+
+- [ ] Create nested types matching flattened structure
+- [ ] Follow naming: `Preference_{Module}_{Section}`
+- [ ] Add GraphQL descriptions with flattened key mappings
+- [ ] Create corresponding input types for mutations
+- [ ] Extend base `Preferences` type
+- [ ] Define necessary enums
+
+### Integration Phase
+
+- [ ] Bind migration in `module.ts` with `whenTargetNamed()`
+- [ ] Ensure all dependencies are injected
+- [ ] Add to module exports if needed
+
+### Testing Phase
+
+- [ ] Write unit tests for migration
+- [ ] Test GraphQL schema with queries
+- [ ] Verify database registration
+- [ ] Test cache clearing
+- [ ] Run integration tests
+
+### Frontend Integration Phase
+
+- [ ] Configure `configurations` in route (compute.ts)
+- [ ] Choose between `useSettingsLoader` (pre-loaded) or `useSettings` (on-demand)
+- [ ] Test with complete keys for specific values
+- [ ] Test with partial keys for nested objects
+- [ ] Verify type autocomplete works
+- [ ] Test `updateConfiguration` mutation
+- [ ] Handle loading and error states
+
+### Documentation Phase
+
+- [ ] Document flattened keys with examples
+- [ ] Add JSDoc to contribution
+- [ ] Document GraphQL type mappings
+- [ ] Document frontend usage patterns
+- [ ] Update module README if needed
+
+---
+
+## Additional Resources
+
+- **TypeScript Configuration**: `@adminide-stack/core` package
+- **Base Migration**: `packages/adminide-platform/server/src/migrations/BaseConfigurationService.ts`
+- **GraphQL Base Types**: Search for base `Preferences` type in schema files
+- **InversifyJS Docs**: https://inversify.io/
+- **MongoDB Docs**: https://docs.mongodb.com/
+
+---
+
+**Document Version:** 1.0.0  
+**Last Updated:** January 19, 2025  
+**Maintained By:** AdminIDE Stack Team