Users Module

The Users Module provides comprehensive user management functionality including user profiles, account administration, permission management, authentication services, and user relationship management within the DashClicks platform.

Brief Overview

The Users module manages the complete user lifecycle within the DashClicks platform, handling user creation, profile management, permission systems, multi-account associations, and integration with authentication services. It supports complex user hierarchies, role-based access control, and extensive customization options.

Directory Structure

internal/api/v1/users/
├── index.js                # Module router and middleware setup
├── README.md               # Module documentation
├── constants/              # User-related constants and enums
│   ├── roles.js            # User role definitions
│   ├── permissions.js      # Permission constants
│   └── status.js           # User status definitions
├── controllers/            # Request handlers
│   ├── index.js            # Controller exports
│   ├── users.js            # User CRUD operations
│   └── config.js           # User configuration management
├── routes/                 # Route definitions
│   ├── users.js            # User management routes
│   └── config.js           # Configuration routes
├── services/               # Business logic layer
│   ├── users.js            # User business logic
│   └── config.js           # Configuration logic
├── schemas/                # Joi validation schemas
│   ├── users.js            # User validation schemas
│   └── config.js           # Configuration validation
└── tests/                  # Test suites
    ├── users.test.js       # User functionality tests
    └── config.test.js      # Configuration tests

MongoDB Collections Used

Primary Collections

• _users - Main user collection with profiles and permissions
• user.sessions - Active user sessions and authentication tokens
• user.preferences - User-specific configuration and preferences
• user.notifications - User notification settings and history
• push.tokens - Mobile device push notification tokens

Related Collections

• _accounts - Account associations and user-account relationships
• workspaces - Workspace memberships and permissions
• activities - User activity tracking and audit logs
• crm.contacts - Contact associations for CRM functionality
• user.calendars - Calendar integration and synchronization data
• user.announcements - User-specific announcement tracking

Data Flow & Workflow

User Creation Flow

graph TD
    A[User Creation Request] --> B[Validate User Data]
    B --> C[Check Email Uniqueness]
    C --> D[Hash Password]
    D --> E[Create User Record]
    E --> F[Generate Verification Token]
    F --> G[Set Default Permissions]
    G --> H[Create User Preferences]
    H --> I[Associate with Account]
    I --> J[Queue Welcome Email]
    J --> K[Queue Manager Processing]

    K --> L[Send Welcome Email]
    K --> M[Setup Default Dashboard]
    K --> N[Initialize Analytics]
    K --> O[Create Activity Log]

Permission Management Flow

graph TD
    A[Permission Update Request] --> B[Validate Permission Changes]
    B --> C[Check Authorization]
    C --> D[Update User Permissions]
    D --> E[Refresh User Sessions]
    E --> F[Update Related Services]
    F --> G[Log Permission Changes]
    G --> H[Queue Notifications]

    H --> I[Queue Manager Processing]
    I --> J[Notify Administrators]
    I --> K[Update Analytics]
    I --> L[Sync External Services]

Multi-Account Association Flow

graph TD
    A[Account Association Request] --> B[Validate Association]
    B --> C[Check Account Permissions]
    C --> D[Create Association Record]
    D --> E[Set Account-Specific Permissions]
    E --> F[Update User Context]
    F --> G[Sync Account Data]
    G --> H[Queue Background Tasks]

    H --> I[Queue Manager Processing]
    I --> J[Update CRM Associations]
    I --> K[Sync Calendar Data]
    I --> L[Update Billing Records]

Background Processing

Queue Manager Integration

The Users module utilizes Queue Manager for various background operations:

User Onboarding (QM_USER_ONBOARDING=true)

• Welcome email sequence delivery
• Account setup automation
• Default dashboard configuration
• Initial data synchronization

User Notifications (QM_USER_NOTIFICATIONS=true)

• Push notification delivery
• Email notification processing
• SMS notification handling
• Notification preference management

User Analytics (QM_USER_ANALYTICS=true)

• User activity aggregation
• Engagement metrics calculation
• Performance analytics generation
• Usage tracking and reporting

Account Synchronization (QM_ACCOUNT_SYNC=true)

• Multi-account data synchronization
• Permission propagation
• Cross-account user updates
• Account relationship maintenance

Users Submodules

The Users module can be organized into specialized submodules for comprehensive user management:

👤 User Profiles

Profile Management and Personal Information

• User profile creation and comprehensive information management
• Personal data handling with privacy and security compliance
• Profile picture and media asset management
• Contact information including multiple phone numbers and emails
• Professional information and bio management
• Profile customization and display preference settings

🔐 Authentication & Security

User Authentication and Security Management

• Password management and security policy enforcement
• Multi-factor authentication setup and verification
• Session management and token-based authentication
• Login history and security audit logging
• Password reset and account recovery workflows
• Security notification and alert management

🔒 Permissions & Access Control

Role-Based Access Control System

• Dynamic permission assignment and scope management
• Role definition and hierarchical permission inheritance
• Account-specific permission overrides and customization
• API access control and rate limiting
• Feature toggle management based on user permissions
• Permission audit trail and compliance reporting

🏢 Account Associations

Multi-Account User Management

• Multi-account user association and relationship management
• Account switching and context management
• Cross-account data synchronization and consistency
• Account-specific user configuration and preferences
• Team collaboration and shared workspace management
• Account hierarchy navigation and access management

⚙️ User Configuration

Preferences and Settings Management

• User preference configuration and customization options
• Notification settings and communication preferences
• UI/UX customization and theme preferences
• Time zone and localization settings
• Integration settings and third-party connections
• Data export and privacy control settings

API Endpoints Overview

Method	Endpoint	Description
GET	/v1/users	Get users with filtering and pagination
POST	/v1/users	Create new user account
GET	/v1/users/profile	Get current user profile
GET	/v1/users/:id	Get specific user details
PUT	/v1/users/:id	Update user information
DELETE	/v1/users/:id	Delete user account
POST	/v1/users/search	Search users by criteria
GET	/v1/users/:id/associated	Get user associations
PUT	/v1/users/:id/scope	Update user permissions
POST	/v1/users/:id/phone	Add phone number to user
PUT	/v1/users/:id/phone/:phoneId	Update phone number
PUT	/v1/users/email	Update user email
DELETE	/v1/users/email	Remove user email
PUT	/v1/users/:id/announcement/:announcementId	Update announcement status
GET	/v1/users/calendars	Get user calendar integrations
POST	/v1/users/recovery	Account recovery process
POST	/v1/users/push-token	Add push notification token
DELETE	/v1/users/push-token	Remove push notification token
GET	/v1/users/config	Get user configuration
PUT	/v1/users/config	Update user configuration

Core User Management Components

User Profile Management

User Information

• Complete user profile creation and management
• Personal and professional information tracking
• Contact details and communication preferences
• Profile customization and personalization settings
• User avatar and profile image management
• Multi-language and timezone preferences

Account Administration

• User account lifecycle management
• Account activation and deactivation processes
• User role assignment and management
• Account hierarchy and organization structure
• Multi-account user management
• Account transfer and migration capabilities

Authentication & Security

User Authentication

• Secure user authentication and session management
• Multi-factor authentication (MFA) support
• Password management and security policies
• Account recovery and password reset processes
• Login activity tracking and security monitoring
• Device management and trusted device registration

Permission Management

• Role-based access control (RBAC) system
• Granular permission assignment and management
• Scope-based authorization and access control
• Dynamic permission evaluation and enforcement
• Permission inheritance and delegation
• Audit trail for permission changes

Communication & Notifications

Contact Management

• User contact information and communication channels
• Phone number management and verification
• Email address management and validation
• Communication preference configuration
• Contact synchronization and integration
• Multi-channel communication support

Notification System

• Push notification token management
• Notification preference configuration
• Real-time notification delivery
• Notification history and tracking
• Channel-specific notification settings
• Integration with external notification services

User Relationships & Integration

User Associations

• User relationship mapping and management
• Team membership and collaboration tracking
• Cross-account user associations
• User hierarchy and reporting relationships
• Project and task assignment tracking
• Integration with CRM and project systems

Calendar Integration

• Calendar service integration and synchronization
• Meeting and appointment management
• Availability tracking and scheduling
• Calendar sharing and collaboration
• Event notification and reminder system
• Multi-calendar support and management

Service Methods & Functionality

User Management Services

getUsers() - User retrieval

• Retrieves users with comprehensive filtering options
• Supports account-specific and cross-account filtering
• Includes user status and permission information
• Provides pagination and advanced sorting capabilities
• Returns user list with relationship and activity data

createUser() - User creation

• Creates new user accounts with validation
• Handles user profile setup and initialization
• Sets up user permissions and role assignments
• Configures communication preferences and settings
• Returns created user with account and permission details

updateUser() - User modification

• Updates user profile and account information
• Handles permission changes and role modifications
• Modifies communication preferences and settings
• Updates user relationships and associations
• Returns updated user with change tracking

deleteUser() - User removal

• Safely deactivates or removes user accounts
• Handles user data migration and reassignment
• Manages user relationship cleanup and transfer
• Archives user data for compliance and auditing
• Returns deletion confirmation and status details

Profile Services

profile() - User profile retrieval

• Retrieves comprehensive user profile information
• Includes personal and professional details
• Provides communication preferences and settings
• Returns profile customization and preference data
• Includes activity history and engagement metrics

updateProfile() - Profile modification

• Updates user profile information and preferences
• Handles profile customization and personalization
• Modifies communication settings and preferences
• Updates user avatar and profile imagery
• Returns updated profile with change confirmation

Permission Services

updateScope() - Permission management

• Updates user permissions and role assignments
• Handles scope-based access control modifications
• Validates permission changes against business rules
• Updates permission inheritance and delegation
• Returns updated permission structure and access rights

associated() - User association management

• Retrieves user relationships and associations
• Manages team membership and collaboration tracking
• Handles cross-account user associations
• Updates user hierarchy and reporting relationships
• Returns association data with relationship details

Communication Services

addPhoneToUser() - Phone number management

• Adds phone numbers to user accounts with validation
• Handles phone number verification and confirmation
• Sets up SMS communication and notification preferences
• Configures phone-based authentication options
• Returns updated user with phone number details

updatePhone() - Phone number modification

• Updates existing phone number information
• Handles phone number verification and re-confirmation
• Modifies phone-based communication preferences
• Updates phone number status and availability
• Returns updated phone number configuration

updateEmail() - Email management

• Updates user email addresses with validation
• Handles email verification and confirmation processes
• Configures email communication preferences
• Sets up email-based authentication and recovery
• Returns updated email configuration and status

deleteEmail() - Email removal

• Removes email addresses from user accounts
• Handles email-based service disconnection
• Updates communication preferences and settings
• Manages email-based authentication removal
• Returns updated email configuration status

Notification Services

addPushToken() - Push notification setup

• Adds push notification tokens for mobile devices
• Handles device registration and token validation
• Configures push notification preferences and settings
• Sets up device-specific notification channels
• Returns push notification configuration details

removePushToken() - Push notification cleanup

• Removes push notification tokens from devices
• Handles device deregistration and cleanup
• Updates push notification preferences and settings
• Manages device-specific notification removal
• Returns push notification removal confirmation

Integration Services

calendars() - Calendar integration

• Retrieves user calendar service integrations
• Manages calendar synchronization and connectivity
• Handles calendar permission and access configuration
• Updates calendar integration settings and preferences
• Returns calendar integration status and details

recovery() - Account recovery

• Handles account recovery and password reset processes
• Validates recovery requests and user identity
• Manages multi-factor authentication for recovery
• Updates account security settings post-recovery
• Returns recovery status and next steps information

Technical Implementation Details

User Architecture

• Profile Management: Comprehensive user profile with customization options
• Permission System: Role-based access control with granular permissions
• Authentication: Multi-factor authentication with security monitoring
• Communication: Multi-channel communication with preference management
• Integration: Calendar and external service integration capabilities

Security Framework

• Access Control: Scope-based permission system with dynamic evaluation
• Authentication: Secure authentication with session management
• Audit Trail: Comprehensive audit logging for security and compliance
• Data Protection: User data encryption and privacy protection
• Recovery: Secure account recovery with identity verification

Communication System

• Multi-channel: Email, SMS, and push notification support
• Preferences: User-configurable communication preferences
• Verification: Contact information verification and validation
• Integration: External communication service integration
• Tracking: Communication history and delivery tracking

Business Logic Flow

User Creation Flow

1. Validate user information and business rules
2. Check for duplicate users and account conflicts
3. Create user account with profile initialization
4. Set up user permissions and role assignments
5. Configure communication preferences and channels
6. Send user creation notifications and welcome messages
7. Return created user with account and permission details

Permission Management Flow

1. Validate permission change requests and authorization
2. Check current user permissions and role assignments
3. Update user permissions and scope configurations
4. Handle permission inheritance and delegation changes
5. Update related user associations and relationships
6. Send permission change notifications to relevant parties
7. Return updated permission structure and access rights

Profile Update Flow

1. Validate profile update requests and data integrity
2. Check user authorization for profile modifications
3. Update user profile information and preferences
4. Handle communication preference and setting changes
5. Update user relationships and association information
6. Send profile update notifications to relevant systems
7. Return updated profile with change confirmation details

Key Features

Comprehensive User Management

• Profile Management: Complete user profile with customization options
• Account Administration: User lifecycle management with role assignments
• Permission System: Granular permission control with role-based access
• Multi-account Support: Cross-account user management and associations

Advanced Authentication

• Multi-factor Authentication: Secure authentication with multiple factors
• Session Management: Secure session handling with activity tracking
• Account Recovery: Comprehensive account recovery with identity verification
• Security Monitoring: Login activity tracking and security alerts

Communication Integration

• Multi-channel Communication: Email, SMS, and push notification support
• Preference Management: User-configurable communication preferences
• Contact Verification: Automated contact information verification
• Integration Support: External communication service integration

User Collaboration

• Team Management: User team membership and collaboration tracking
• Association Management: User relationship mapping and management
• Calendar Integration: Calendar service integration and synchronization
• Project Integration: Integration with project and task management systems