Chunks — 16. Team Management

Team Management

#

#

#

#

#

# **Team Management**

**Functional Requirement Document**

**BA & Ideation: Deval Chauhan**

**Reviewed By: Keval Gajjar**

**Updated Date:23 December 2025  
Status:**

**Version: 1.0**

# **Team Management Module - Executive Summary**

## **Comprehensive Coverage Across 7 FRDs**

### FRD 1: Team Management Listing

**Core Features:**

*   **Role-Based Access:** Owner/Admin full control, others view-only access
*   **Display Elements:** Profile pictures with initials fallback, brand badges (3 inline + overflow)
*   **Pagination System:** 10/25/50/100 results per page with localStorage persistence
*   **Search Functionality:** Real-time search across name/email (300ms debounce, min 2 chars)
*   **Filter Options:** AND/OR logic for brand and role filters with active count badges
*   **Action Buttons:** Edit/Delete visible by permission, Resend Invite for pending users (24hr cooldown)
*   **Auto-Refresh:** 60-second polling for real-time updates across concurrent sessions
*   **Export Capability:** CSV download respecting active filters and search criteria
*   **Empty States:** Friendly prompt to invite first member when no team exists
*   **Performance:** Lazy-loaded images, indexed queries, cached frequently accessed data

### FRD 2: Invite Team Member with Subscription Impact

**Subscription Management:**

*   **Seat Display:** Real-time "3 of 5 seats in use" with pending invitations counted
*   **Overage Warning:** Yellow banner when at capacity showing "$9/month per additional user"
*   **Email Validation:** Format check, uniqueness within agency, cross-agency prevention, disposable email blocking
*   **Role Assignment:** Hierarchical restrictions (Admin cannot assign Owner)
*   **Brand Assignment:** Multiple selection (max 10), at least one required
*   **Token Generation:** 32-byte base64url, 48-hour expiration, single-use enforcement
*   **Invitation Email:** Branded template with agency details and role information
*   **Billing Integration:** Webhook to billing service for overage charges
*   **Retry Logic:** 3 attempts with exponential backoff for email delivery
*   **Form Preservation:** SessionStorage maintains data during network interruptions

### FRD 3: Post Invite Flow (Account Creation)

**Account Setup Process:**

*   **Landing Page:** "Welcome to \[Agency Name\]" with agency branding
*   **Token Validation:** 48-hour expiry check, single-use enforcement, agency isolation
*   **Error State:** "Oops, this link is not valid" for expired/invalid tokens
*   **Email Lock:** Pre-populated and read-only to maintain invitation integrity
*   **Password Requirements:** 8+ chars, uppercase, lowercase, number, special character
*   **Strength Indicator:** Three-bar system (red/yellow/green) with real-time feedback
*   **Common Password Check:** Database of 10,000 blocked passwords
*   **Auto-Login:** JWT session created immediately after account creation
*   **Welcome Email:** Role-specific resources and getting started guide
*   **Inviter Notification:** Confirmation sent when team member joins
*   **Brand/Project Access:** Immediate filtering based on assigned permissions

### FRD 4: Edit Team Member Role

**Permission Management:**

*   **Role Hierarchy:** Users can only assign roles at or below their level
*   **Self-Edit Prevention:** Cannot modify own role (UI and API enforcement)
*   **Owner Protection:** Agency owner role cannot be modified
*   **Brand Management:** Add/remove brands (minimum one required)
*   **Role Transitions:** Warnings for downgrades showing permission loss impact
*   **Project Manager Toggles:** Special permissions for status changes and messaging
*   **Real-Time Updates:** Active sessions receive permission changes via WebSocket
*   **Contact Updates:** Phone number (international format) and personal email
*   **Audit Trail:** Before/after values logged for all modifications
*   **Email Notifications:** Both edited user and editor receive confirmations
*   **Concurrent Edit Handling:** Version control with "last save wins" approach

### FRD 5: Delete Team Member and Its Impact

**Data Transfer Process:**

*   **Impact Summary:** Shows counts of projects, tasks, automations, templates to transfer
*   **Confirmation Required:** Must type "DELETE" to enable deletion button
*   **Transfer to Owner:** All projects, tasks, automations, templates reassigned
*   **Historical Preservation:** Comments/logs show "\[Deleted User\]" for continuity
*   **Session Termination:** Immediate logout across all devices and API tokens
*   **Subscription Update:** Seat count decrements, overage charges stop if applicable
*   **Email Notifications:** Owner receives transfer summary, deleted user gets confirmation
*   **30-Day Cooling:** Email address unavailable for re-invitation period
*   **Transaction Integrity:** All-or-nothing deletion with rollback on failure
*   **Restrictions:** Cannot delete self, owner, or last admin

### FRD 6: Email Signature Management

**Signature Control:**

*   **Owner Exclusive:** Only agency owner can create/manage signatures
*   **Brand Association:** One signature per brand for consistency
*   **Rich Text Editor:** Bold, italic, links, colors, image embedding
*   **Merge Tags:** {{user.name}}, {{user.phone}}, {{user.email}} auto-population
*   **Logo Support:** Upload with 500KB limit, base64 or CDN delivery
*   **Social Links:** Icons for Facebook, LinkedIn, Instagram integration
*   **Auto-Application:** All brand users automatically receive signature
*   **Email Integration:** Signatures appear in compose with edit capability
*   **Size Limit:** 15KB maximum for email client compatibility
*   **Version History:** Soft delete with 30-day recovery option

### FRD 7: Team Member Roles & Permissions

**Role Definitions (Phase 1 - Global):**

*   **Owner:** Full system access, billing control, refund processing, subscription management
*   **Admin:** Team management, all projects, no billing/subscription access
*   **Project Manager:** Assigned projects only, create/edit own, client communication
*   **Supervising Editor:** Enhanced editorial, approval rights, task assignment
*   **Junior Editor:** Basic editorial, no approval, limited to assigned work
*   **Basic (TBD):** Read-only access for stakeholders (Phase 1/2 confirmation pending)
*   **Permission Matrix:** Complete module-by-module access control grid
*   **Brand Isolation:** All roles respect brand boundaries for data access
*   **Real-Time Enforcement:** Permissions apply immediately without re-login
*   **Phase 2 Preview:** Agency-specific role customization capabilities

## **Common Technical Specifications**

**System-Wide Features:**

*   **Database Schema:** users, invitations, user\_brands, roles\_permissions tables
*   **Security:** CSRF protection, SQL injection prevention, rate limiting
*   **Authentication:** JWT tokens, session management, OAuth revocation
*   **Email Service:** SMTP with retry logic, HTML templates, delivery tracking
*   **WebSocket:** Real-time updates for permissions and team changes
*   **Caching:** Redis with 5-minute TTL for permission matrices
*   **Audit Logging:** Immutable records with user\_id, action, timestamp, metadata
*   **Performance:** Indexed queries, batch operations, lazy loading
*   **Browser Support:** Chrome, Firefox, Safari, Edge with graceful degradation
*   **Mobile Responsive:** Adaptive layouts for all team management interfaces

## **Delivery Package Contents**

**Documentation:**

*   7 Comprehensive FRD Documents (12 sections each)
*   7 Individual Test Case Excel Files (25-30 test cases per FRD)
*   1 Roles & Permissions Matrix (HTML - Google Sheets style)
*   **Total:** 194 detailed test scenarios covering all user flows

**Key Decisions:**

*   **Invitation Expiry:** 48 hours (not 7 days) ✅
*   **Basic Role:** Implementation in Phase 1 or 2 (TBD) ⚠️
*   **Email Signatures:** Owner-only management ✅
*   **Cross-Agency:** Strict isolation, no email sharing across agencies ✅
*   **Deletion Impact:** Everything transfers to owner ✅
*   **Phase 2:** Custom roles per agency (future enhancement) ⚠️

1\. Team Management Listing

## **FRD#1 Team Management Listing**

## **1\. Module Overview**

**Module Name:** Team Management Listing

**Purpose:** The Team Management Listing module serves as the central interface for agency owners and administrators to view, manage, and organize their team members across the CRM platform, providing a comprehensive overview of all users with their assigned roles, brand access, and contact information.

**Business Goals:** This module enables efficient team organization and access control management, ensuring that agency owners can maintain proper role-based permissions, monitor team composition across different brands, and quickly perform management actions such as editing roles or removing team members from the system.

## **2\. User Roles & Permissions**

**Role**

**View Team List**

**Invite Members**

**Edit Members**

**Delete Members**

**Manage Signatures**

**Resend Invites**

Owner

✓

✓

✓

✓

✓

✓

Admin

✓

✓

✓

✓

✗

✓

Project Manager

✓

✗

✗

✗

✗

✗

Supervising Editor

✓

✗

✗

✗

✗

✗

Junior Editor

✓

✗

✗

✗

✗

✗

Basic (TBD - Phase 1/2)

✓

✗

✗

✗

✗

✗

_Note: Basic role implementation to be confirmed with client for Phase 1 or Phase 2 deployment._

## **3\. User Flow**

**3.1 Initial Page Access**

3.1.1 The user clicks on Team Management from the left sidebar navigation menu to access the team member listing module.

3.1.2 The system validates the user's role permissions from the users table in the database to determine their access level for team management features.

3.1.3 The system queries all team members WHERE agency\_id equals the current user's agency\_id and retrieves records including user name, email, role, brand assignments, and invitation status.

3.1.4 The system renders the team management listing page with a table displaying columns for Name, Contact, Brand, and Actions while showing a loading spinner for 1-2 seconds during data retrieval.

**3.2 Team Member Display**

3.2.1 The user sees the complete list of team members with each row displaying the member's full name constructed from first\_name and last\_name fields in the database.

3.2.2 Each row displays a profile picture if uploaded or an initials-based avatar generated from the team member's name as a fallback option.

3.2.3 The email address appears as the primary contact method and serves as the unique identifier for each team member in the system.

3.2.4 Brand assignments display as colored tag badges with each brand having a unique color pulled from the brands configuration table.

3.2.5 Action buttons appear based on the current user's role permissions with Edit and Delete visible for authorized users only.

3.2.6 The user observes the Invite New button prominently displayed in the top-right corner of the listing page if they have invitation permissions according to their role.

**3.3 Pagination Controls**

3.3.1 The system displays pagination controls at the bottom of the table showing "Result per page: 10" with dropdown options for 10, 25, 50, or 100 records per page.

3.3.2 The user clicks the pagination dropdown to change the number of results displayed per page, and the system immediately refreshes the table view with the selected number of records.

3.3.3 The user navigates through multiple pages using the pagination controls which display the current range such as "1-10 of 10" with previous and next arrow buttons.

3.3.4 The system maintains the user's pagination preference in localStorage for subsequent visits to the team management page. 3.3.5 Page navigation updates the URL parameters allowing users to bookmark or share specific pages of the team listing.

**3.4 Search Functionality**

3.4.1 The user clicks in the search box located above the team listing table to initiate a search operation.

3.4.2 The system displays placeholder text "Search by name or email" to guide the user on available search parameters.

3.4.3 The user types their search query with a minimum of 2 characters required before the search executes. 3.4.4 The system waits 300 milliseconds after the last keystroke before executing the search query to prevent excessive database calls.

3.4.5 The system performs a case-insensitive LIKE query on first\_name, last\_name, and email fields simultaneously.

3.4.6 Results display immediately in the table, replacing the current view with only matching team members. 3.4.7 A clear button appears when text is present in the search field allowing the user to reset the search with one click.

**3.5 Filter Application**

3.5.1 The user clicks on the brand filter dropdown to view available brand options for filtering the team list. 3.5.2 The dropdown displays all brands associated with the agency with checkboxes for multi-select capability. 3.5.3 The user selects one or multiple brands and the system applies OR logic within brand selections. 3.5.4 The user clicks on the role filter dropdown to filter team members by their assigned roles. 3.5.5 The system combines brand and role filters using AND logic to show team members matching all filter criteria. 3.5.6 Active filters display as tags below the filter controls with X buttons for individual filter removal. 3.5.7 The user clicks "Clear All Filters" to reset all filters and return to the default unfiltered view.

**3.6 Edit Team Member** 3.6.1 The user hovers over a team member row which highlights the entire row with a subtle background color change to indicate it is interactive. 3.6.2 The user clicks on the Edit action button (pencil icon) for a specific team member to modify their role or brand access permissions. 3.6.3 The system validates that the current user has permission to edit the selected team member based on role hierarchy. 3.6.4 The system opens the Edit Team Member modal with pre-populated fields showing current role and brand assignments for modification. 3.6.5 The user makes necessary changes and saves, with the system updating the listing immediately to reflect modifications.

**3.7 Delete Team Member** 3.7.1 The user clicks on the Delete action button (trash icon) for a team member they wish to remove from the agency. 3.7.2 The system validates deletion permissions ensuring users cannot delete themselves or higher-level roles. 3.7.3 The system displays a confirmation dialog warning about the permanent removal and data transfer implications before proceeding with deletion. 3.7.4 The user confirms the deletion and the system processes the removal with all data transfers to the agency owner. 3.7.5 The listing refreshes automatically removing the deleted member from the display.

**3.8 Resend Invitation** 3.8.1 The user identifies team members with pending invitations by observing the "Resend Invite" link displayed next to their email address. 3.8.2 The user clicks the Resend Invite link for team members whose initial invitation email may have been missed or expired. 3.8.3 The system checks if 24 hours have passed since the last invitation was sent to prevent spam. 3.8.4 The system generates a new invitation token and sends a fresh invitation email to the team member's registered email address. 3.8.5 A success notification displays confirming "Invitation has been resent successfully to \[email\]" for 5 seconds. 3.8.6 The resend\_count increments in the database for tracking invitation attempts.

## **4\. Functional Logic**

**4.1 Access Control and Permissions**

*   The system enforces strict agency isolation by ensuring users can only view team members within their own agency\_id, preventing any cross-agency data visibility.
*   Role-based access control determines which action buttons appear for each user with owners and admins seeing Edit and Delete while others see view-only options.
*   The system prevents the agency owner from being deleted through the interface by hiding or disabling the delete action for the owner role.
*   Self-editing and self-deletion restrictions are enforced at both UI and API levels to prevent users from modifying their own accounts.
*   Permission checks occur on every page load and API call to ensure real-time enforcement of access restrictions.

**4.2 Data Loading and Display**

*   When the page loads initially, the system retrieves all team members sorted alphabetically by last name, then first name, with the agency owner always appearing at the top regardless of alphabetical order.
*   The listing displays each team member's primary information including their full name constructed from first\_name and last\_name fields, their work email address which serves as their unique identifier, and their assigned role from the predefined role set.
*   Profile images load lazily as the user scrolls with a fallback to initials-based avatars if profile images fail to load or don't exist.
*   Brand assignments appear as colored tag badges next to each team member's information, with each brand having a unique color assignment stored in the brands table for visual differentiation.
*   For team members with multiple brand assignments, the interface displays up to three brand tags inline, with additional brands shown in a "+N more" format that expands on hover.
*   The system dynamically calculates and displays the total number of team members in the agency, updating this count in real-time when members are added or removed.

**4.3 Pagination and Navigation**

*   Pagination logic calculates the total number of pages based on the selected results per page option and the total record count.
*   The system remembers the user's pagination preference in localStorage for subsequent visits maintaining consistency across sessions.
*   URL parameters update with page navigation allowing bookmarking and sharing of specific pages in the team listing.
*   Default pagination starts at 10 records per page with options to increase to 25, 50, or 100 based on user preference.
*   Page changes trigger smooth transitions without full page reloads using AJAX requests for better user experience.

**4.4 Search Implementation**

*   The search functionality implements debouncing with a 300-millisecond delay after the last keystroke before executing the search query to optimize database performance.
*   Search queries use parameterized SQL with wildcards to match partial strings, searching across first\_name, last\_name, and email fields simultaneously for comprehensive results.
*   Empty search returns all records with active filters still applied maintaining the user's current filtering context.
*   Search maintains filter state if filters are active combining search results with filter criteria using AND logic.
*   Results highlight matching terms using HTML mark tags for easy identification of search matches.
*   Minimum 2-character requirement prevents single-character searches that would return too many results and impact performance.

**4.5 Filter Processing**

*   Filter selections build dynamic WHERE clauses with same-category selections joining with OR logic and different categories joining with AND logic.
*   Brand filters respect the user's own brand access showing only brands the current user has permission to view.
*   Role filters display all available roles in the system allowing filtering by any role level.
*   Active filters show a count badge on the filter button indicating how many filters are currently applied.
*   Clear All button sets all filters to unchecked state and refreshes the listing to show all team members.
*   Filter state persists during the session but not across sessions requiring reapplication after login.

**4.6 Invitation Management**

*   The Invite New button remains disabled and shows a tooltip message when the agency has reached their subscription limit for team members.
*   The Resend Invite functionality appears only for team members whose account\_status equals 'pending' in the database.
*   When a resend action is triggered, the system checks if the previous invitation was sent more than 24 hours ago before allowing a new invitation.
*   Each resend action increments a resend\_count in the database for tracking invitation attempts and identifying potential issues.
*   Invitation tokens regenerate with each resend ensuring previous links become invalid for security.
*   The system logs all invitation actions including initial sends and resends for audit trail purposes.

**4.7 Real-time Updates**

*   The interface automatically refreshes every 60 seconds using polling to reflect any changes made by other administrators.
*   WebSocket connections provide instant updates when available falling back to polling if WebSocket connection fails.
*   Only changed data transfers to minimize bandwidth with the UI updating via virtual DOM diffing for performance.
*   User's active edits are preserved during refresh preventing loss of in-progress work.
*   Notification badges appear for new changes drawing attention to updates since the last view.
*   Manual refresh button remains available for immediate updates when users need instant synchronization.

**4.8 Export and Reporting**

*   Export functionality enables authorized users to download the team member list as a CSV file containing all visible columns.
*   Exported data respects active filters and search criteria only including currently visible team members.
*   The CSV generation happens server-side to handle large datasets without browser memory limitations.
*   File naming includes timestamp and filter indicators for easy identification of exported data.
*   Export permissions are restricted to owners and admins preventing unauthorized data extraction.
*   The system logs all export actions including who exported data and what filters were applied.

**4.9 Performance Optimization**

*   Database queries use indexed columns for agency\_id, role, and brand associations ensuring fast retrieval even with large teams.
*   The system caches frequently accessed data such as brand colors and role labels in browser memory to reduce server requests.
*   Lazy loading of profile images prevents initial page load delays by loading images only as they enter the viewport.
*   Batch operations process multiple updates in single transactions reducing database round trips.
*   Query result caching at the API level serves repeated requests without hitting the database.
*   Progressive enhancement ensures core functionality works even if JavaScript fails to load.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Validation Rules**

**Required**

**Default Value**

Search Box

Text Input

Minimum 2 characters, Maximum 100 characters

No

Empty

Results Per Page

Dropdown

Options: 10, 25, 50, 100

Yes

10

Brand Filter

Multi-select Dropdown

Must be valid brand\_id from brands table

No

All Brands

Role Filter

Dropdown

Must match predefined roles enum

No

All Roles

Sort Column

Column Header Click

Valid columns: Name, Email, Role, Brand

No

Name ASC

Page Number

Pagination Control

Must be positive integer within total pages

Yes

1

Name Display

Text Display

Concatenated first\_name + last\_name

N/A

N/A

Email Display

Text Display

Valid email format from database

N/A

N/A

Role Display

Text Display

Mapped from roles enum to display label

N/A

N/A

Brand Tags

Tag Display

Limited to assigned brands from user\_brands table

N/A

N/A

Profile Image

Image/Avatar

JPG, PNG, GIF, max 5MB, fallback to initials

No

Initials Avatar

## **6\. Success Message Handling**

**Operation**

**Success Message**

**Display Duration**

**Post-Success Action**

Resend Invite

"Invitation has been resent successfully to \[email\]"

5 seconds

Refresh invitation timestamp

Bulk Select

"\[N\] team members selected"

Persistent until deselected

Enable bulk action buttons

Export CSV

"Team list exported successfully"

3 seconds

Trigger file download

Filter Applied

"Showing \[N\] results matching your filters"

3 seconds

Update result count

Sort Applied

"Sorted by \[column\] \[direction\]"

2 seconds

Reorder table rows

Search Completed

"Found \[N\] team members matching '\[query\]'"

3 seconds

Display filtered results

Page Changed

No message

N/A

Scroll to top of table

View Refreshed

"Team list updated"

2 seconds

Update any changed data

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Required User Action**

**System Response**

Search query too short

"Please enter at least 2 characters to search"

Enter more characters

Prevent search execution

No search results

"No team members found matching your search"

Modify search or clear

Display empty state

Page load failure

"Unable to load team members. Please try again"

Refresh page

Show retry button

Network timeout

"Connection timeout. Please check your internet"

Check connection and retry

Auto-retry after 5 seconds

Invalid page number

"Page not found. Returning to first page"

None

Redirect to page 1

Export failed

"Failed to export team list. Please try again"

Retry export

Log error to console

Filter error

"Unable to apply filters. Please refresh"

Refresh page

Clear all filters

Permission denied

"You don't have permission to view team members"

Contact administrator

Redirect to dashboard

Session expired

"Your session has expired. Please log in again"

Log in

Redirect to login page

Rate limit exceeded

"Too many requests. Please wait a moment"

Wait 30 seconds

Disable actions temporarily

## **8\. Edge Cases**

**Scenario**

**Handling Approach**

**Expected Behavior**

Single team member (owner only)

Display normally with disabled delete

Show owner with no delete option

Maximum team members reached

Disable invite button with tooltip

Show subscription limit message

Very long names (>50 characters)

Truncate with ellipsis

Show full name on hover

No brand assignments

Show "No brands assigned" text

Display in gray italic text

All invites pending

Show all with resend option

Display pending status clearly

Rapid resend attempts

Throttle to once per 24 hours

Show cooldown timer

Concurrent admin edits

Last write wins with notification

Alert user of external changes

Browser back button

Maintain filter/search state

Restore previous view state

Multiple tabs open

Sync across tabs using localStorage

Update all tabs on changes

Offline mode

Show cached data with indicator

Display offline banner

Search special characters

Escape SQL injection attempts

Sanitize input before query

Print view requested

Generate printer-friendly layout

Hide actions, show all data

CSV export with filters

Respect active filters

Export only visible data

Session timeout during action

Prompt reauthentication

Save action and retry after login

Deleted brand reference

Show "Deleted Brand" placeholder

Maintain data integrity

## **9\. Acceptance Criteria**

*   The Team Management listing page must load within 3 seconds and display all team members for the current agency
*   Users with appropriate permissions can successfully access and view the complete team member list
*   Pagination controls function correctly, allowing navigation through multiple pages of team members
*   Search functionality returns accurate results based on name and email queries with proper debouncing
*   Filter options for brands and roles accurately filter the displayed team members
*   The Invite New button appears only for authorized roles and respects subscription limits
*   Edit and Delete actions are visible only to users with appropriate permissions
*   Resend Invite links appear only for pending invitations and function correctly
*   The interface maintains responsive design across desktop, tablet, and mobile devices
*   All user actions are properly logged in the audit trail for compliance tracking
*   The system prevents unauthorized access attempts and displays appropriate error messages
*   Export functionality generates valid CSV files with filtered data when requested
*   Sort functionality works correctly on all sortable columns with visual indicators
*   The page automatically refreshes every 60 seconds to show real-time updates
*   Empty states display helpful messages and call-to-action buttons when no data exists

## **10\. Manual Test Cases**

**Test Cases Document:** [Test\_Cases\_Team\_Management\_Listing.xlsx](https://docs.google.com/spreadsheets/d/1qGvDXNQMxJ0blp3fTWSw8r34PfLk_X42/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Description**

**Impact if Unavailable**

**Fallback Approach**

Database - Users Table

Stores all team member information

Cannot display team list

Show error and retry

Database - Brands Table

Contains brand information for tags

Cannot show brand assignments

Display "Brand unavailable"

Database - User\_Brands Table

Maps users to their assigned brands

Cannot show brand access

Show no brands

Database - Roles Table

Defines available roles and permissions

Cannot validate permissions

Use cached role data

Authentication Service

Validates user session and permissions

Cannot access module

Redirect to login

Email Service

Sends invitation emails for resend

Cannot resend invites

Queue for later sending

Subscription Service

Checks team member limits

Cannot validate limits

Block new invitations

Audit Log Service

Records all team management actions

Cannot track changes

Queue logs locally

Profile Image Storage

CDN for team member profile photos

Cannot load images

Show initials avatar

Export Service

Generates CSV files for download

Cannot export data

Show error message

Cache Service

Stores frequently accessed data

Slower performance

Direct database queries

WebSocket Service

Real-time updates across sessions

No live updates

Fall back to polling

Search Index

Optimized search functionality

Slower search results

Use database LIKE queries

Session Storage

Maintains user preferences

Lost user settings

Use default settings

## **12\. References**

**Figma Designs:** [**Figma**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=23505-5455&t=oyNB4QWzT2ouAyqD-0)

2\. Invite Team Member with Subscription Impact

# **FRD#2 Invite Team Member with Subscription Impact**

## **1\. Module Overview**

**Module Name:** Invite Team Member with Subscription Impact

**Purpose:** The Invite Team Member module enables authorized users to send invitations to new team members while managing subscription seat limits, automatically handling billing adjustments when exceeding plan limits, and assigning appropriate roles and brand access during the invitation process.

**Business Goals:** This module ensures controlled team expansion aligned with subscription capabilities, provides transparent billing impact notifications when adding team members beyond plan limits, and establishes proper access permissions from the moment of invitation to maintain security and organizational structure.

## **2\. User Roles & Permissions**

**Role**

**Can Invite Members**

**Set Roles**

**Assign Brands**

**Override Seat Limits**

**View Billing Impact**

Owner

✓

✓ (All Roles)

✓

✓

✓

Admin

✓

✓ (Except Owner)

✓

✗

✓

Project Manager

✗

✗

✗

✗

✗

Supervising Editor

✗

✗

✗

✗

✗

Junior Editor

✗

✗

✗

✗

✗

Basic (TBD)

✗

✗

✗

✗

✗

## **3\. User Flow**

**3.1 Accessing the Invitation Function** 3.1.1 The user with appropriate permissions (Owner or Admin) navigates to the Team Management section from the main navigation menu in the left sidebar. 3.1.2 The system validates the user's role permissions to ensure they have invitation privileges before displaying the team management interface. 3.1.3 The user identifies and clicks on the "Invite New" button prominently displayed in the top-right corner of the team listing page with a plus icon. 3.1.4 The system responds immediately by triggering the invitation modal while maintaining the current page state in the background. 3.1.5 The browser focus shifts to the modal dialog with keyboard trap enabled to ensure accessibility compliance.

**3.2 Modal Display and Initialization** 3.2.1 The system displays the Invite Team Member modal dialog with a semi-transparent dark overlay that prevents interaction with the background page. 3.2.2 The modal appears with a smooth slide-in animation from the center of the screen taking approximately 300 milliseconds to fully render. 3.2.3 The modal header displays "Invite New Team Member" in 18px bold font with a close (X) button in the top-right corner for dismissal without saving. 3.2.4 The system immediately queries the subscription service API to fetch current seat usage and plan limits for display in the modal. 3.2.5 The modal body initializes with all form fields in their default empty state with placeholder text providing guidance for each input. 3.2.6 The system pre-loads the role and brand dropdown data to ensure instantaneous response when the user interacts with these fields.

**3.3 Subscription Status Display** 3.3.1 The system displays the current seat usage status prominently at the top of the modal showing "3 of 5 seats in use" with a progress bar visualization. 3.3.2 The seat count includes both active team members and pending invitations that haven't been accepted yet to prevent over-invitation. 3.3.3 If the agency has available seats, the system displays a green indicator showing the number of remaining seats available for invitation. 3.3.4 If all subscription seats are occupied, the system displays a yellow warning banner with an information icon stating the overage charge implications. 3.3.5 The warning message specifically states "You've reached your plan limit. Adding this member will incur $9/month additional charge" in 14px text. 3.3.6 The system includes a link to "Upgrade Plan" within the warning message that opens the subscription management page in a new tab. 3.3.7 The progress bar visually represents seat usage with green for under-limit and yellow when at capacity for immediate visual feedback.

**3.4 Email Address Input and Validation** 3.4.1 The user clicks into the email field which has placeholder text "Enter work email address" and a red asterisk indicating it's required. 3.4.2 The user types the new team member's work email address with real-time format validation showing a red border for invalid formats. 3.4.3 As the user types, the system performs regex validation for proper email format showing a green checkmark when valid. 3.4.4 Upon losing focus from the field, the system queries the database to check if the email already exists within the agency. 3.4.5 If the email exists in the agency, the system displays an inline error "This email is already registered in your agency" in red text. 3.4.6 The system also checks if the email exists in other agencies and displays "This email is associated with another agency" if found. 3.4.7 The system validates against a blacklist of disposable email domains to ensure professional email addresses are used. 3.4.8 For corporate agencies, the system may enforce domain restrictions allowing only emails from specific approved domains.

**3.5 Name Fields Entry and Validation** 3.5.1 The user enters the team member's first name in the required field with a minimum of 2 characters and maximum of 50 characters allowed. 3.5.2 The first name field validates against special characters allowing only letters, spaces, hyphens, and apostrophes for international names. 3.5.3 The user enters the team member's last name in the required field following the same validation rules as the first name field. 3.5.4 Both name fields trim leading and trailing whitespace automatically and capitalize the first letter of each word upon losing focus. 3.5.5 If either name field contains fewer than 2 characters, an inline error appears stating "Name must be at least 2 characters long". 3.5.6 The system supports Unicode characters for international names including accented characters and non-Latin scripts. 3.5.7 A character counter appears below each name field when the user approaches the maximum character limit.

**3.6 Role Selection Process** 3.6.1 The user clicks on the role dropdown which displays a list of available roles based on the inviting user's permission level in the hierarchy. 3.6.2 If the inviter is an Owner, all roles appear in the dropdown including Admin, Project Manager, Supervising Editor, and Junior Editor options. 3.6.3 If the inviter is an Admin, the dropdown excludes the Owner role and only shows roles at Admin level and below. 3.6.4 Each role in the dropdown displays with an information icon that shows a tooltip describing the role's primary permissions on hover. 3.6.5 The user selects the appropriate role which immediately updates the form field and enables role-specific permission preview below. 3.6.6 The system displays a brief description of the selected role's capabilities such as "Can manage projects and team members" for context. 3.6.7 The role selection triggers a visual indicator showing the hierarchical level of the selected role within the organization structure. 3.6.8 The system prevents selection of roles that would create permission conflicts with existing team structures.

**3.7 Brand Assignment Selection** 3.7.1 The user clicks on the brand selection dropdown which displays all active brands associated with the agency in alphabetical order. 3.7.2 The dropdown renders as a multi-select checkbox list allowing the user to assign multiple brands to the new team member. 3.7.3 Each brand appears with its associated color indicator and name with checkboxes for selection on the left side. 3.7.4 The user selects one or more brands by clicking the checkboxes with at least one brand required for the invitation to proceed. 3.7.5 Selected brands appear as tags below the dropdown with X buttons for individual removal if the user changes their mind. 3.7.6 If the user attempts to proceed without selecting any brands, an inline error states "Please select at least one brand" in red text. 3.7.7 The system enforces a maximum of 10 brand selections to maintain manageable permission sets and prevent UI overflow. 3.7.8 A "Select All" option appears at the top of the dropdown for agencies with multiple brands to facilitate quick selection.

**3.8 Optional Message Composition** 3.8.1 The user may optionally click into the personal message field which has placeholder text "Add a welcome message (optional)". 3.8.2 The message field allows up to 500 characters of free text that will be included in the invitation email body. 3.8.3 A character counter appears below the field showing "0/500" and updates in real-time as the user types their message. 3.8.4 The user can include a personalized welcome, context about the role, or any relevant onboarding information in this field. 3.8.5 The system preserves line breaks and basic formatting but strips any HTML or script tags for security purposes.

**3.9 Form Review and Validation** 3.9.1 The user reviews all entered information for accuracy including email, names, role, and brand assignments before proceeding. 3.9.2 The "Send Invitation" button remains disabled and grayed out until all required fields contain valid data. 3.9.3 As each required field is completed successfully, the button progressively becomes more enabled with visual feedback. 3.9.4 Once all validations pass, the button becomes fully enabled with a blue background and white text saying "Send Invitation". 3.9.5 The user hovers over the button which shows a subtle shadow effect indicating it's ready for interaction. 3.9.6 A summary section appears showing the key invitation details for final review before submission.

**3.10 Invitation Submission Process** 3.10.1 The user clicks the "Send Invitation" button which immediately disables to prevent duplicate submissions during processing. 3.10.2 The button text changes to "Sending..." with a spinning loader icon indicating the invitation is being processed. 3.10.3 The system performs final server-side validation of all inputs including permission checks and email uniqueness verification. 3.10.4 The system generates a unique 32-byte secure token using cryptographically secure random generation for the invitation URL. 3.10.5 The invitation record is created in the database with status "pending", the generated token, and a 48-hour expiration timestamp. 3.10.6 The system triggers the email service to send the invitation email using the agency's configured SMTP settings or fallback service. 3.10.7 If seat limits are exceeded, the system notifies the billing service via webhook to initiate prorated charges. 3.10.8 The system creates placeholder entries in user\_brands and user\_projects tables that activate upon invitation acceptance.

**3.11 Success Confirmation Display** 3.11.1 Upon successful email delivery, the modal displays a success message "Invitation sent successfully to \[email\]" with a green checkmark icon. 3.11.2 The success message appears as a banner at the top of the modal with a subtle fade-in animation over 200 milliseconds. 3.11.3 The form fields are cleared and the modal automatically begins closing after displaying the success message for 3 seconds. 3.11.4 The modal closes with a fade-out animation while the success message briefly persists as a toast notification in the top-right corner. 3.11.5 The team listing page automatically refreshes to show the new pending invitation in the list with appropriate status indicators. 3.11.6 The newly invited member appears with a "Pending" badge and "Resend Invite" link next to their email address. 3.11.7 The subscription status in the header updates to reflect the new seat count if applicable.

**3.12 Error Handling and Recovery** 3.12.1 If the invitation fails due to network issues, the system displays "Failed to send invitation. Please check your connection and try again." 3.12.2 For email service failures, the error message states "Email service temporarily unavailable. Please try again in a few moments." 3.12.3 If the user lacks sufficient permissions due to a role change, the system shows "You no longer have permission to send invitations." 3.12.4 All error messages appear in red text with an error icon at the top of the modal and keep the form data intact for retry. 3.12.5 The user can dismiss the error message and attempt to correct the issue or close the modal to cancel the invitation process. 3.12.6 The system implements retry logic with exponential backoff for transient failures, attempting up to 3 times before showing an error. 3.12.7 Form data is preserved in sessionStorage allowing users to recover their input if the modal is accidentally closed.

## **4\. Functional Logic**

**4.1 Subscription Management and Seat Calculation**

*   The invitation modal loads with real-time subscription data fetched from the subscription service API, ensuring accurate seat count information is always displayed to the user.
*   Seat calculation includes both active users (status = 'active') and pending invitations (status = 'pending') to prevent over-invitation beyond subscription limits.
*   The system queries the subscription service every time the modal opens to ensure the displayed seat count reflects the most current state.
*   Available seats are calculated as (total\_seats - active\_users - pending\_invitations) with negative values indicating overage situations.
*   When seat limits are reached, the modal displays specific overage pricing based on the agency's subscription tier pulled from the pricing configuration.
*   The subscription service maintains a real-time count that updates across all active sessions when invitations are sent or team members are removed.

**4.2 Email Validation and Uniqueness Checking**

*   Email validation implements multiple checks including format validation for proper email structure using RFC 5322 compliant regex patterns.
*   The system performs uniqueness validation against the current agency's team members preventing duplicate accounts within the same organization.
*   Cross-agency validation prevents the same email from being active in multiple agencies simultaneously, enforcing single-tenancy per email address.
*   The system maintains a blacklist of disposable email domains (tempmail, guerrillamail, etc.) that are automatically rejected with appropriate error messaging.
*   Corporate agencies can configure approved email domains in their settings, restricting invitations to specific corporate domains for security.
*   The validation process checks both the users table and the invitations table to prevent sending multiple invitations to the same email address.
*   Email addresses are stored in lowercase format to ensure case-insensitive uniqueness checking across the platform.

**4.3 Role Assignment and Permission Hierarchy**

*   Role assignment follows strict hierarchical rules where users can only assign roles at or below their own permission level in the organizational structure.
*   Agency owners have unrestricted role assignment capabilities including the ability to invite additional admin users to help manage the agency.
*   Admin users can assign all roles except Owner, maintaining single ownership of the agency while allowing administrative delegation.
*   The role dropdown dynamically populates based on the current user's role, filtering out any roles above their permission level.
*   Each role assignment automatically inherits the associated permissions from the roles\_permissions configuration table upon account activation.
*   The system prevents role assignment that would create circular reporting relationships or violate organizational hierarchy rules.
*   Role descriptions are pulled from the roles table and displayed as tooltips to help inviters select the appropriate permission level.

**4.4 Brand Access Control and Assignment**

*   Brand selection dynamically filters to show only brands that the inviting user has access to, preventing unauthorized brand assignment.
*   The system enforces at least one brand selection to ensure new team members have defined access boundaries from the start.
*   Multi-brand selection creates entries in the user\_brands junction table that define the team member's cross-brand access permissions.
*   A maximum of 10 brands can be assigned per user to maintain manageable permission sets and prevent performance degradation.
*   Brand assignments become active immediately upon account creation, filtering all data access throughout the platform based on these selections.
*   The brand dropdown displays each brand's color indicator and name for easy visual identification during the selection process.
*   Changes to brand structure or deactivation of brands automatically cascade to remove those options from future invitations.

**4.5 Token Generation and Security**

*   Invitation tokens are generated using cryptographically secure random number generation producing 32 bytes of random data.
*   Tokens are encoded using base64url format to ensure URL-safe transmission without special character encoding issues.
*   Each token is guaranteed unique through database constraints and collision detection with automatic regeneration if needed.
*   The token expiration is set to exactly 48 hours from generation, after which the invitation link becomes invalid and requires resending.
*   Tokens are single-use, meaning once an invitation is accepted, the same token cannot be reused even within the validity period.
*   The system stores tokens in hashed format in the database using bcrypt to prevent token theft through database access.
*   Token validation includes checks for expiration, usage status, and agency match to prevent cross-agency invitation hijacking.

**4.6 Email Service Integration and Delivery**

*   The email service integrates with the agency's configured SMTP settings allowing branded email delivery from their domain.
*   If custom SMTP is not configured, the system falls back to the platform's default transactional email service for delivery.
*   Email templates are customized with the agency's logo, colors, and branding elements pulled from the agency\_settings configuration.
*   The invitation email includes the sender's name, agency name, assigned role, and a clear call-to-action button with the invitation link.
*   Email delivery implements retry logic with exponential backoff, attempting delivery 3 times over 5 minutes before marking as failed.
*   Successful email delivery is confirmed through SMTP response codes with delivery status tracked in the invitation record.
*   The system logs all email sending attempts including timestamps, response codes, and any error messages for troubleshooting.

**4.7 Billing Integration and Overage Handling**

*   When invitations exceed subscription seat limits, the system automatically triggers a webhook to the billing service for charge processing.
*   Overage charges are calculated on a prorated basis for the remainder of the current billing cycle at the plan's per-seat rate.
*   The billing service updates the subscription record to reflect the new seat count which persists for future billing cycles.
*   Agencies can configure auto-approval for overages or require explicit confirmation before allowing seat limit expansion.
*   The system maintains an audit trail of all billing-related invitation events for reconciliation and dispute resolution.
*   If billing service is unavailable, invitations are queued with eventual consistency ensuring charges are properly applied.
*   Overage notifications are sent to the agency owner's email address with details about the additional charges incurred.

**4.8 Database Transaction Management**

*   The entire invitation process is wrapped in a database transaction ensuring atomicity of all related data operations.
*   If any step fails (user creation, brand assignment, email sending), the entire transaction rolls back maintaining data consistency.
*   The system uses optimistic locking on the subscription record to handle concurrent invitation attempts without race conditions.
*   Placeholder user records are created with status 'invited' to reserve the email address during the invitation validity period.
*   Junction table entries for user\_brands and user\_projects are created but remain inactive until invitation acceptance.
*   Failed transactions are logged with complete error details for debugging while keeping user-facing messages generic for security.
*   The system implements database connection pooling to handle multiple concurrent invitation requests without resource exhaustion.

**4.9 Audit Logging and Compliance**

*   Every invitation action is logged to the audit\_log table including who invited whom, when, with what role, and which brands.
*   The audit log captures both successful and failed invitation attempts with complete context for security analysis.
*   Invitation history is maintained indefinitely for compliance with potential regulatory requirements and internal auditing.
*   The system tracks invitation patterns to detect potential abuse such as mass invitations or unusual invitation velocity.
*   All logged data includes IP addresses, user agents, and session identifiers for comprehensive security tracking.
*   Audit logs are immutable once written and can only be queried, not modified or deleted, ensuring data integrity.
*   Regular audit reports can be generated showing invitation activity, acceptance rates, and role distribution patterns.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Validation Rules**

**Required**

**Default Value**

Work Email

Email Input

Valid email format, unique in agency, not in blacklist, max 254 chars

Yes

Empty

First Name

Text Input

Min 2 chars, max 50 chars, Unicode support, letters/spaces/hyphens

Yes

Empty

Last Name

Text Input

Min 2 chars, max 50 chars, Unicode support, letters/spaces/hyphens

Yes

Empty

Brand(s)

Multi-select Dropdown

Must be valid brand\_ids, min 1, max 10 selections

Yes

Empty

Role

Single-select Dropdown

Must be available role based on current user permissions

Yes

Empty

Personal Message

Textarea

Max 500 chars, strips HTML/scripts, preserves line breaks

No

Empty

Invitation Token

System Generated

32-byte random string, base64url encoded

N/A

Auto-generated

Expiration Date

System Generated

Current timestamp + 48 hours

N/A

Auto-calculated

Sender ID

System Generated

Current authenticated user's ID

N/A

Current user

Agency ID

System Generated

Current user's agency\_id

N/A

Current agency

Subscription Seats

Display Only

Numeric, pulled from subscription service

N/A

API response

Overage Cost

Display Only

Currency format, calculated from plan

N/A

$9/month default

## **6\. Success Message Handling**

**Scenario**

**Message Text**

**Display Duration**

**Visual Indicator**

Invitation Sent

"Invitation successfully sent to \[email\]"

3 seconds

Green checkmark

Seat Limit Warning

"Invitation sent. Additional charges will apply."

5 seconds

Yellow warning icon

Multiple Invitations

"\[count\] invitations sent successfully"

3 seconds

Green checkmark

Resend Success

"Invitation resent to \[email\]"

3 seconds

Green refresh icon

## **7\. Error Message Handling**

**Error Type**

**Message Text**

**User Action**

**System Response**

Duplicate Email

"This email is already registered in your agency"

Change email

Highlight field red

Cross-Agency Email

"This email is associated with another agency"

Use different email

Prevent submission

Invalid Email Format

"Please enter a valid email address"

Correct format

Real-time validation

Network Error

"Connection error. Please check your internet and try again."

Retry

Keep form data

Email Service Down

"Unable to send email. Please try again later."

Retry later

Queue invitation

Permission Denied

"You don't have permission to invite team members"

Contact admin

Close modal

Seat Limit Reached (No Auto-charge)

"Seat limit reached. Please upgrade your plan."

Upgrade plan

Show upgrade link

## **8\. Edge Cases**

*   **Concurrent Invitations:** Multiple admins sending invitations simultaneously are handled through optimistic locking on the subscription seat count to prevent over-invitation.
*   **Email Service Failure:** If the email service is down, invitations are queued in a pending\_emails table and processed when service is restored.
*   **Token Collision:** In the extremely rare case of token collision, the system automatically regenerates a new token and retries up to 5 times.
*   **Plan Downgrade During Invitation:** If the subscription plan is downgraded while the invitation modal is open, the seat count refreshes upon submission.
*   **Invitation to Deleted User:** If inviting an email that was previously deleted, the system allows it after a 30-day cooling period.
*   **Browser Crash:** Form data is saved in sessionStorage every 5 seconds, allowing recovery if the browser crashes or is closed accidentally.
*   **Race Condition on Last Seat:** When multiple users try to claim the last available seat, first-come-first-served with others seeing seat limit message.

## **9\. Acceptance Criteria**

*   The invitation modal must display current seat usage accurately within 1 second of opening
*   Email validation must provide real-time feedback within 200ms of user input
*   Invitation emails must be sent within 5 seconds of clicking Send Invitation
*   The system must prevent duplicate invitations to the same email within a 24-hour period
*   Overage charges must be accurately calculated and displayed before invitation is sent
*   Role dropdown must only show roles at or below the current user's permission level
*   At least one brand must be selected for the invitation to be valid
*   Invitation tokens must expire exactly 48 hours after generation
*   Failed email deliveries must retry automatically with exponential backoff
*   All invitation actions must be logged in the audit trail with complete context

## **10\. Manual Test Cases**

**Test Cases Document:** [Test\_Cases\_Invite\_Team\_Member.xlsx](https://docs.google.com/spreadsheets/d/1g66anORtcBT8FiNB8t7dMTaIWPLdBc-M/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Description**

**Impact if Unavailable**

**Fallback Approach**

Subscription Service

Provides seat count and limits

Cannot validate seat availability

Cache last known values

Email Service

Sends invitation emails

Cannot deliver invitations

Queue for retry

User Database

Stores team member records

Cannot create invitations

Return error message

Roles Table

Defines available roles

Cannot populate role dropdown

Use cached role list

Brands Table

Lists agency brands

Cannot assign brands

Use cached brand list

Billing Service

Processes overage charges

Cannot charge for extra seats

Queue billing events

Audit Log Service

Records invitation events

Cannot track invitations

Local logging queue

Token Generator

Creates secure tokens

Cannot generate invitations

Return error message

Template Engine

Formats invitation emails

Cannot send branded emails

Use plain text fallback

Session Storage

Preserves form data

Cannot recover from crashes

Accept data loss

## **12\. References**

**Figma Designs:** [**Figma**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=23505-5456&t=oyNB4QWzT2ouAyqD-0)**,** [**Figma**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=23505-5456&t=oyNB4QWzT2ouAyqD-0)

3\. Post Invite Flow

## **FRD#3 Post Invite Flow (Team Member Account Creation and Login)**

## **1\. Module Overview**

**Module Name:** Post Invite Flow (Team Member Account Creation and Login)

**Purpose:** The Post Invite Flow module manages the complete journey of an invited team member from receiving the invitation email through account creation, password setup, and initial system access, ensuring secure onboarding while establishing proper authentication and access permissions.

**Business Goals:** This module facilitates seamless team member onboarding by providing a secure and intuitive account creation process, ensures invited members can quickly access their assigned projects and brands upon joining, and maintains security compliance through proper authentication setup and email verification.

## **2\. User Roles & Permissions**

**Role**

**Can Accept Invite**

**Set Own Password**

**Access After Creation**

**View Assigned Brands**

**Modify Profile**

Invited User (Pre-Creation)

✓

✓

✗

✗

✗

Owner (Post-Creation)

N/A

✓

✓

✓

✓

Admin (Post-Creation)

N/A

✓

✓

✓

✓

Project Manager (Post-Creation)

N/A

✓

✓

✓

✓

Supervising Editor (Post-Creation)

N/A

✓

✓

✓

✓

Junior Editor (Post-Creation)

N/A

✓

✓

✓

✓

Basic (Post-Creation)

N/A

✓

✓

✓

✓

## **3\. User Flow**

**3.1 Email Invitation Receipt** 3.1.1 The invited team member receives an email at their work email address containing the invitation from the agency with a secure activation link.

3.1.2 The email displays the agency name, inviter's name, assigned role, and a personalized message stating "You've been invited to join the \[Agency Name\] team. Please review your details and set up your account to get started."

3.1.3 The recipient clicks the "Accept Invitation" button in the email which contains a unique token embedded in the URL parameters that expires after 48 hours.

**3.2 Token Validation and Landing Page** 3.2.1 The system validates the invitation token by checking its existence in the invitations table and verifying it has not expired beyond the 48-hour validity period.

3.2.2 If the token is valid, the browser opens to the account creation page displaying "Welcome to \[Agency Name\]!" with the agency's branding and professional imagery.

3.2.3 If the token is invalid or expired, the page displays "Oops, this link is not valid" with a message "Maybe the link has expired, timed-out, or invalid. It was not copied correctly" prompting the user to contact their inviter.

**3.3 Account Creation Form** 3.3.1 The system pre-populates the email address field with the invited email from the invitation record, displayed as a locked field to prevent changes.

3.3.2 The page displays the First Name and Last Name fields separately, pre-filled with the name provided during invitation, which the user can modify if needed.

3.3.3 The user enters their desired password in the Choose Password field which shows strength indicators with colored bars (red for weak, yellow for medium, green for strong) as they type.

3.3.4 The user re-enters their password in the Confirm Password field to ensure accuracy and prevent typing errors during account creation.

**3.4 Form Submission and Account Activation** 3.4.1 The user clicks the yellow "Create Account" button which triggers validation of all form fields including password strength and matching confirmation.

3.4.2 The system creates the user account in the users table with status changing from 'invited' to 'active' upon successful creation.

3.4.3 The system automatically logs in the newly created user and generates an authentication session token for immediate access.

3.4.4 The system assigns all brands and roles that were configured during the invitation process to the newly created user account.

**3.5 Post-Creation Experience** 3.5.1 The user is redirected to the main dashboard where they see a welcome message personalized with their name and role.

3.5.2 The dashboard displays only the brands and projects they were assigned during invitation, filtered according to their permissions.

3.5.3 The user receives a welcome email confirming successful account creation with links to help resources and documentation specific to their role.

3.5.4 The system notifies the original inviter via email that the team member has successfully joined and activated their account with timestamp details.

## **4\. Functional Logic**

**4.1 Email and Token Management**

*   The invitation email generation uses the agency's configured email template with dynamic content injection including the inviter's name, agency branding, role assignment, and expiration date clearly displayed showing "This link will expire in 48 hours."
*   Token validation performs multiple security checks including existence verification in the database, expiration time comparison against current timestamp (48 hours from creation), single-use enforcement to prevent replay attacks, and agency\_id matching to ensure proper isolation.
*   The invitation token becomes immediately invalid after successful account creation, preventing any reuse even if someone obtains the link after activation has occurred.
*   Failed token validation attempts are logged with IP address and timestamp for security monitoring, with automatic blocking after 5 failed attempts from the same IP within 10 minutes.
*   The system checks for browser cookie support and localStorage availability, displaying warnings if these are disabled since they're required for proper session management and user experience.

**4.2 Account Creation Page Display**

*   The account creation page implements responsive design that adapts to desktop and mobile devices, ensuring invited users can complete setup from any device including smartphones and tablets.
*   The welcome page displays professional photography with the agency name prominently shown, creating a branded experience that matches the agency's visual identity.
*   Invalid token attempts display a user-friendly error page with clear messaging "Oops, this link is not valid" and guidance to contact the inviter for a new invitation link.
*   The form displays the email address as a locked field with a lock icon, preventing changes to ensure the account is created with the originally invited email address.
*   Browser compatibility checks ensure the account creation form works across Chrome, Firefox, Safari, and Edge, with graceful degradation for older browsers showing simplified functionality.

**4.3 Password Security and Validation**

*   Password strength validation enforces minimum 8 characters length, at least one uppercase letter, one lowercase letter, one number, and one special character, with real-time feedback showing strength levels from weak to strong.
*   The password strength indicator uses a three-bar color-coded system displaying red bars for weak passwords, yellow bars for medium strength, and green bars for strong passwords, with all three bars lighting up for maximum strength.
*   Common password detection prevents users from selecting passwords from a database of 10,000 most common passwords, displaying a specific warning about password vulnerability when detected.
*   The system prevents password reuse by checking against the user's previous passwords stored as hashed values, though this only applies to password changes after initial account creation.
*   Password confirmation field validates in real-time showing a green checkmark when passwords match or a red X when they don't match, providing immediate visual feedback.

**4.4 User Account Creation Process**

*   Account creation transaction wraps all database operations in a single transaction including user record creation, role assignment, brand access setup, and invitation status update to ensure data consistency.
*   The system creates default notification preferences for the new user based on their role, with project managers receiving all project updates while editors receive only assigned task notifications.
*   Database triggers automatically create associated records in related tables including user\_preferences with default values, user\_notifications with standard settings, and activity\_log with account creation entry.
*   Profile information is split into First Name and Last Name fields for better data organization, allowing proper formatting of display names throughout the application.
*   The form implements CSRF protection using tokens to prevent cross-site request forgery attacks during the account creation process, validated on both client and server sides.

**4.5 Session and Authentication**

*   Session token generation uses cryptographically secure methods with JWT tokens containing user\_id, role, agency\_id, and expiration time, signed with the application's private key for tamper prevention.
*   The initial login session has a default duration of 24 hours with automatic renewal on activity, requiring re-authentication after periods of inactivity exceeding the configured timeout threshold.
*   Email verification is implicitly completed through the invitation acceptance process, marking the email as verified without requiring a separate verification step since the invitation was sent to that address.
*   The system automatically logs in the newly created user after successful account creation, eliminating the need for immediate re-authentication and providing seamless onboarding.
*   Integration with the audit log service records detailed account creation events including all submitted fields except passwords, source IP address, and any validation failures for security review.

**4.6 Post-Creation Actions**

*   Welcome email sent after account creation includes personalized content based on the user's role, with different resource links for project managers versus editors to provide role-relevant guidance.
*   Notification to the inviter includes the timestamp of account activation and the user's completed profile information, helping team leaders track successful onboarding of new members.
*   Brand and project filtering immediately applies upon login, with database queries automatically including WHERE clauses based on user\_brands and user\_projects junction tables for proper access control.
*   The system creates a default avatar using the user's initials (first letter of first name and last name) with a randomly selected background color from the agency's color palette.
*   Initial workspace setup includes creating user-specific folders in the file storage system, setting up default dashboard widgets, and initializing user preferences with role-appropriate defaults.

**4.7 Error Handling and Recovery**

*   Network interruption during account creation saves form data in sessionStorage, allowing recovery of entered information when the connection is restored without requiring complete re-entry.
*   Rate limiting prevents rapid account creation attempts from the same IP address, allowing maximum 3 account creations per hour to prevent automated abuse while accommodating legitimate team onboarding.
*   The account creation form saves progress automatically every 30 seconds, allowing users to navigate away and return without losing entered information, clearing only after successful submission or explicit cancellation.
*   Expired token handling provides clear instructions to request a new invitation, displaying the inviter's name and email to facilitate direct communication for reactivation.
*   Server errors during account creation trigger automatic rollback of partial database entries, ensuring no orphaned records exist and maintaining database integrity.

**4.8 Accessibility and Compliance**

*   Accessibility features include proper ARIA labels for screen readers, keyboard navigation support for all form fields, and high contrast mode compatibility for users with visual impairments.
*   The form supports password managers through proper autocomplete attributes on form fields, allowing users to save and auto-fill credentials securely.
*   Internationalization support handles names with Unicode characters, right-to-left text for appropriate languages, and localized error messages based on browser language settings.
*   GDPR compliance includes explicit consent checkboxes for data processing, links to privacy policy and terms of service, and options to request data deletion if the user decides not to proceed.
*   Mobile optimization includes touch-friendly button sizes, appropriate keyboard types for different inputs, and prevention of zoom on input focus for better mobile experience.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Validation Rules**

**Required**

**Default Value**

Invitation Token

URL Parameter

32 characters, alphanumeric, not expired

Yes

From email link

Email Address

Read-only Display

Pre-populated from invitation

N/A

From invitation

Full Name

Text Input

Min 2 chars, max 100 chars, Unicode support

Yes

From invitation

Password

Password Input

Min 8 chars, complexity requirements

Yes

Empty

Confirm Password

Password Input

Must match password field

Yes

Empty

Phone Number

Tel Input

Valid international format, E.164

No

Empty

Country Code

Dropdown

ISO 3166-1 country codes

No

Auto-detected

Timezone

Dropdown

IANA timezone database values

Yes

Browser default

Terms Acceptance

Checkbox

Must be checked

Yes

Unchecked

Profile Photo

File Upload

JPG, PNG, GIF, max 5MB

No

None

Bio/Description

Textarea

Max 500 characters

No

Empty

Notification Preferences

Checkboxes

Email, SMS, In-app options

No

Role defaults

## **6\. Success Message Handling**

**Operation**

**Success Message**

**Display Duration**

**Post-Success Action**

Token Validated

"Invitation verified successfully"

3 seconds

Show creation form

Account Created

"Welcome to \[Agency Name\]! Your account is ready"

5 seconds

Redirect to dashboard

Password Set

"Password strength: Strong"

Persistent

Enable submit button

Profile Completed

"Profile information saved"

3 seconds

Continue to dashboard

Terms Accepted

"Terms and conditions accepted"

2 seconds

Enable account creation

Tour Completed

"Ready to get started!"

3 seconds

Show main interface

First Login

"Successfully logged in"

3 seconds

Load user workspace

Preferences Saved

"Your preferences have been saved"

3 seconds

Apply preferences

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Required User Action**

**System Response**

Invalid token

"This invitation link is invalid or has expired"

Request new invitation

Show contact admin

Expired token

"This invitation has expired. Please request a new one"

Contact inviter

Provide inviter email

Already used token

"This invitation has already been used"

Log in instead

Show login link

Weak password

"Password is too weak. Add numbers and symbols"

Strengthen password

Show requirements

Password mismatch

"Passwords do not match"

Re-enter passwords

Clear confirm field

Common password

"This password is too common. Choose another"

Select different password

Clear password fields

Invalid phone format

"Please enter a valid phone number"

Correct format

Show format example

Terms not accepted

"You must accept the terms to continue"

Check the box

Highlight checkbox

Network failure

"Connection error. Please try again"

Retry

Show retry button

Account exists

"An account with this email already exists"

Log in instead

Redirect to login

Session expired

"Session expired. Please start over"

Restart process

Clear form data

File too large

"Profile photo must be under 5MB"

Choose smaller file

Clear file input

Invalid file type

"Please upload JPG, PNG, or GIF only"

Select valid file

Clear file input

Server error

"Something went wrong. Please try again"

Retry

Log error details

Rate limit exceeded

"Too many attempts. Try again later"

Wait 1 hour

Show countdown timer

## **8\. Edge Cases**

**Scenario**

**Handling Approach**

**Expected Behavior**

Multiple invitation emails

Latest invitation valid

Previous tokens invalidated

Changed email address

Original email required

Cannot modify during creation

Browser back button

Preserve form state

Restore entered data

Network interruption

Auto-save progress

Resume from last state

Invitation after account exists

Detect existing account

Redirect to login

Role changed before acceptance

Use latest role assignment

Update upon creation

Brand deleted before acceptance

Skip deleted brand

Notify about change

Agency suspended during creation

Block account creation

Show suspension message

Concurrent acceptance attempts

First success wins

Lock during processing

JavaScript disabled

Basic HTML fallback

Simplified form

Cookie blocking

Detect and warn

Require cookie enabling

Auto-fill passwords

Support password managers

Proper field attributes

International characters in name

Full Unicode support

Store correctly

Very long names

Truncate display

Store full value

Timezone changes

Allow later modification

Use selection as default

Mobile keyboard issues

Optimize input types

Proper keyboard hints

Screen reader usage

Full accessibility

ARIA labels present

Slow connections

Show progress indicators

Prevent timeout errors

Password manager conflicts

Compatible implementation

Standard field names

Social engineering attempts

Security warnings

Verify invitation source

## **9\. Acceptance Criteria**

*   Invitation tokens must be validated within 1 second of page load with clear messaging
*   Account creation form must be fully responsive across all device types and screen sizes
*   Password requirements must be clearly communicated with real-time validation feedback
*   The entire account creation process must complete within 30 seconds under normal conditions
*   Successfully created accounts must have immediate access to assigned brands and projects
*   Email notifications must be sent to both the new user and inviter upon successful creation
*   The system must prevent reuse of invitation tokens after successful account creation
*   All form inputs must have proper validation with helpful error messages
*   The welcome tour must display role-appropriate content and guidance
*   Session tokens must be securely generated and properly set for authentication
*   Terms of service acceptance must be properly logged for legal compliance
*   Phone numbers must be validated and formatted according to international standards
*   Profile photos must be properly uploaded and stored with appropriate size limits
*   The system must handle network failures gracefully with retry capabilities
*   Accessibility standards must be met for users with disabilities

## **10\. Manual Test Cases**

**Test Cases Document:** [Test\_Cases\_Post\_Invite\_Flow.xlsx](https://docs.google.com/spreadsheets/d/1YAcFqI81k6okSnPQ9f5Mpm-KLBwG2SXe/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Description**

**Impact if Unavailable**

**Fallback Approach**

Email Service

Delivers invitation emails

Cannot receive invitations

Contact admin directly

Database - Invitations Table

Stores invitation records

Cannot validate tokens

Show error message

Database - Users Table

Creates user accounts

Cannot create account

Queue for retry

Authentication Service

Generates session tokens

Cannot log in

Retry authentication

Password Hashing Service

Secures password storage

Cannot save password

Use backup algorithm

File Storage Service

Stores profile photos

Cannot upload photos

Skip photo upload

Geolocation Service

Detects user timezone

Cannot auto-detect

Manual selection only

SMS Service

Sends phone verification

Cannot verify phone

Skip verification

Terms of Service API

Provides latest terms

Cannot show terms

Use cached version

Audit Log Service

Records account creation

Cannot log event

Queue for later

Email Validation Service

Verifies email format

Cannot validate

Basic validation only

Browser Detection

Identifies compatibility

Cannot check browser

Assume compatible

Session Storage

Saves form progress

Cannot save progress

Warn about data loss

CDN Service

Delivers agency logos

Cannot show branding

Use text only

Notification Service

Sends welcome messages

Cannot notify

Queue for later

## **12\. References**

**Figma Designs:** [**Figma**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=32711-21914&t=oyNB4QWzT2ouAyqD-0)

4\. Edit Team Member Role

## **FRD#4 Edit Team Member Role**

## **1\. Module Overview**

**Module Name:** Edit Team Member Role

**Purpose:** The Edit Team Member Role module enables authorized administrators to modify existing team members' roles and brand access permissions, allowing for dynamic team restructuring as projects evolve and responsibilities change within the agency.

**Business Goals:** This module facilitates efficient team management by enabling role upgrades and downgrades based on changing responsibilities, ensures proper permission inheritance when roles change, and maintains audit trails for all permission modifications to support compliance and security requirements.

## **2\. User Roles & Permissions**

**Role**

**Can Edit Others**

**Can Change Roles**

**Can Modify Brands**

**Can Edit Owner**

**Can Downgrade Admin**

Owner

✓

✓ (All Roles)

✓

✗

✓

Admin

✓

✓ (Below Admin)

✓

✗

✗

Project Manager

✗

✗

✗

✗

✗

Supervising Editor

✗

✗

✗

✗

✗

Junior Editor

✗

✗

✗

✗

✗

Basic (TBD)

✗

✗

✗

✗

✗

## **3\. User Flow**

**3.1 Accessing Edit Team Member** 3.1.1 The user navigates to the Team Management listing page and locates the team member whose role or access needs modification.

3.1.2 The user clicks on the Edit action button (pencil icon) next to the target team member's row, which is only visible for users with appropriate permissions.

3.1.3 The system validates the current user's permission to edit the selected team member by checking role hierarchy and permission rules.

**3.2 Edit Modal Display** 3.2.1 The system opens the Edit Team Member modal dialog with a semi-transparent overlay, displaying the team member's current information.

3.2.2 The modal header shows "Edit Team Member" title with the team member's name displayed prominently for context.

3.2.3 The system pre-populates all fields with the current values including Work Email (read-only), Full Name, Phone Number, Personal Email Address, Brand assignments, and current Role.

**3.3 Email and Contact Information** 3.3.1 The Work Email field displays as read-only with a lock icon, preventing changes to the primary identifier used for login and system identification.

3.3.2 The user can modify the Full Name field if the team member's name needs correction or has legally changed.

3.3.3 The user can update the Phone Number field with proper international format validation showing country code selector.

3.3.4 The user can add or modify the Personal Email Address field which serves as a secondary contact method for account recovery.

**3.4 Brand Access Modification** 3.4.1 The user clicks on the Brand(s) dropdown which displays all available brands within the agency with checkboxes for multiple selection.

3.4.2 Currently assigned brands appear with checkmarks, and the user can add new brands by checking additional boxes.

3.4.3 The user can remove brand access by unchecking previously selected brands, with a warning if removing the last brand assignment.

3.4.4 The system validates that at least one brand remains selected, preventing complete removal of brand access while the user remains active.

**3.5 Role Change Process** 3.5.1 The user clicks on the Role dropdown which displays available roles based on the current user's permission level and hierarchy rules.

3.5.2 The dropdown shows the current role as selected with a checkmark indicator for clear identification.

3.5.3 For role upgrades (e.g., Junior Editor to Supervising Editor), the user simply selects the new higher role from the dropdown.

3.5.4 For role downgrades (e.g., Project Manager to Junior Editor), the system displays a warning about permission loss before proceeding.

**3.6 Project Manager Special Permissions** 3.6.1 When Project Manager role is selected, the interface displays additional permission toggles specific to that role.

3.6.2 The user can configure individual permissions including "Change statuses on their own projects", "View and message at minimum the primary employee assigned", and "Figure out what they can see in terms of project details for editor notes".

3.6.3 The user toggles each permission switch to green (enabled) or gray (disabled) based on the desired access level.

3.6.4 The "View this project" toggle controls overall project visibility, with dependent permissions automatically disabling if this is turned off.

**3.7 Validation and Warnings** 3.7.1 The system displays a yellow warning banner when downgrading a user's role, explaining "Downgrading this role will remove access to features and projects associated with the higher permission level."

3.7.2 For admin to non-admin downgrades, the system shows an additional warning about losing access to team management and system configuration features.

3.7.3 The system validates that the current user cannot edit their own role, displaying "You cannot modify your own role" if attempted.

3.7.4 The system prevents editing the agency owner's role, showing "Agency owner role cannot be modified" to maintain account integrity.

**3.8 Saving Changes** 3.8.1 The user reviews all modifications including role changes, brand updates, and permission adjustments before saving.

3.8.2 The user clicks the "Save Changes" button which triggers validation of all modified fields and permission rules.

3.8.3 The system processes the update transaction, modifying the users table, user\_brands junction table, and role\_permissions as needed.

3.8.4 Upon successful save, the modal closes automatically and displays a success notification "Team member updated successfully."

**3.9 Post-Update Actions** 3.9.1 The team management listing refreshes to reflect the updated role and brand assignments immediately.

3.9.2 The system sends an email notification to the edited team member informing them of the role or permission changes.

3.9.3 The system logs all changes to the audit trail including previous values, new values, timestamp, and the administrator who made the changes.

3.9.4 If the user's current session is active, their permissions update in real-time without requiring re-login.

## **4\. Functional Logic**

**4.1 Permission Hierarchy Validation**

*   The system enforces strict role hierarchy where users can only assign roles at or below their own level, preventing privilege escalation through unauthorized role assignments.
*   Agency owners have unrestricted role assignment capabilities except they cannot create another owner role, maintaining single ownership per agency.
*   Admins can assign any role except Owner, allowing them to manage team permissions while preserving the owner's unique authority.
*   The modal dynamically filters the available roles dropdown based on the current user's permissions, hiding roles they cannot assign.
*   Cross-role editing restrictions prevent Project Managers, Editors, and Basic users from modifying any team member roles regardless of hierarchy.

**4.2 Brand Access Management**

*   Brand selection shows all brands associated with the agency, with visual indicators (checkmarks) for currently assigned brands.
*   The system enforces a minimum of one brand assignment per user, displaying an error if attempting to remove all brand access.
*   When brands are removed from a user, the system cascades the change to remove access to all projects under those brands immediately.
*   Multi-brand selection allows up to 10 brands per user to maintain manageable permission sets and prevent UI overflow issues.
*   Brand access changes take effect immediately upon saving, with database transactions ensuring atomic updates across all related tables.

**4.3 Role Transition Impact**

*   Role upgrades immediately grant new permissions defined in the roles\_permissions table, expanding the user's access to additional features and data.
*   Role downgrades trigger a permission audit that removes access to features exclusive to the higher role, potentially affecting active work sessions.
*   The system checks for active project assignments that would become invalid with a role downgrade, warning about potential workflow disruptions.
*   Project Manager to Editor transitions preserve project visibility but remove management capabilities like status changes and team assignments.
*   Admin to non-admin transitions remove access to all administrative interfaces including team management, billing, and system configuration.

**4.4 Project Manager Permission Configuration**

*   Project Manager permission toggles provide granular control over specific capabilities without changing the base role assignment.
*   The "Change statuses on their own projects" permission controls whether Project Managers can move projects through workflow stages.
*   The "View and message at minimum the primary employee assigned" permission enables communication with assigned team members.
*   Permission dependencies automatically cascade, where disabling parent permissions disables all child permissions to maintain logical consistency.
*   Custom Project Manager permissions are stored in a separate project\_manager\_permissions table for role-specific configuration management.

**4.5 Data Consistency and Validation**

*   Email address modifications are restricted to prevent changing the primary work email, maintaining account identity and preventing login issues.
*   Name changes update all display instances across the system including project assignments, comments, and audit logs for consistency.
*   Phone number validation includes format checking for international numbers with automatic formatting based on country code selection.
*   The system prevents concurrent editing of the same team member by implementing optimistic locking with version checking.
*   All field validations occur client-side for immediate feedback and server-side for security, ensuring data integrity at both levels.

**4.6 Audit Trail and Compliance**

*   Every edit action creates a detailed audit log entry including the editor's identity, timestamp, IP address, and all changed fields.
*   The audit log stores both previous and new values for each modified field, enabling complete change history reconstruction.
*   Role changes trigger compliance notifications to designated compliance officers when sensitive permissions are modified.
*   The system maintains a 90-day rollback capability for role changes, allowing restoration of previous permissions if needed.
*   Audit logs are immutable and retained for the configured compliance period, typically 7 years for regulatory requirements.

**4.7 Real-time Permission Updates**

*   Active user sessions receive permission updates via WebSocket connections, immediately reflecting role changes without requiring re-authentication.
*   The system invalidates cached permissions for the edited user, forcing fresh permission checks on their next action.
*   Browser-side permission caches clear automatically when role changes are detected, preventing stale permission data.
*   API tokens associated with the user remain valid but inherit the new permission set immediately upon role change.
*   Mobile app sessions receive push notifications about permission changes, prompting users to refresh their app state.

**4.8 Email Notifications and Communication**

*   Role change notifications sent to affected users include specific details about what access has been added or removed.
*   The notification email uses templates customized by role type, providing relevant information and resources for the new role.
*   Administrators receive confirmation emails for their edit actions, serving as an additional audit trail outside the system.
*   Critical downgrades (like Admin to Basic) trigger additional notifications to the agency owner for awareness and oversight.
*   Email delivery failures are logged and retried up to three times, with fallback to in-app notifications if email remains undeliverable.

**4.9 Edge Case Handling**

*   Self-editing prevention checks occur at both UI and API levels, ensuring users cannot modify their own roles through any method.
*   Owner role protection prevents any modification attempts, maintaining the integrity of the agency's primary administrator.
*   Suspended user editing is blocked with appropriate messaging, preventing changes to accounts that are temporarily inactive.
*   The system handles partial update failures by rolling back the entire transaction, preventing inconsistent permission states.
*   Network interruption recovery saves edit state in localStorage, allowing users to resume editing after connection restoration.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Validation Rules**

**Required**

**Default Value**

Work Email

Read-only Display

Cannot be modified

N/A

Current value

Full Name

Text Input

Min 2 chars, max 100 chars

Yes

Current value

Phone Number

Tel Input

International format, E.164

No

Current value

Personal Email

Email Input

Valid email format, unique

No

Current value

Brand(s)

Multi-select Dropdown

Min 1, max 10 brands

Yes

Current brands

Role

Single-select Dropdown

Based on user permissions

Yes

Current role

PM - Change Statuses

Toggle Switch

Boolean

No

Current setting

PM - View & Message

Toggle Switch

Boolean

No

Current setting

PM - Project Details

Toggle Switch

Boolean

No

Current setting

PM - View Project

Toggle Switch

Boolean

No

Current setting

## **6\. Success Message Handling**

**Operation**

**Success Message**

**Display Duration**

**Post-Success Action**

Role Upgraded

"\[Name\] has been promoted to \[New Role\]"

5 seconds

Refresh listing

Role Downgraded

"\[Name\] role changed to \[New Role\]"

5 seconds

Refresh listing

Brands Updated

"Brand access updated successfully"

3 seconds

Update display

Permissions Modified

"Project Manager permissions updated"

3 seconds

Apply changes

Contact Info Updated

"Contact information saved"

3 seconds

Update profile

All Changes Saved

"Team member updated successfully"

5 seconds

Close modal

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Required User Action**

**System Response**

Self-edit attempt

"You cannot modify your own role"

Edit different user

Disable save button

Owner edit attempt

"Agency owner role cannot be modified"

Cancel operation

Hide edit button

No brands selected

"At least one brand must be assigned"

Select a brand

Highlight field

Invalid phone format

"Please enter a valid phone number"

Correct format

Show example

Duplicate personal email

"This email is already in use"

Use different email

Clear field

Permission conflict

"Selected permissions are incompatible"

Adjust selections

Show conflict

Network failure

"Failed to save changes. Please try again"

Retry save

Keep modal open

Concurrent edit

"This user was modified by another admin"

Refresh and retry

Reload current data

Invalid role selection

"You cannot assign this role level"

Select valid role

Filter dropdown

Session expired

"Your session has expired"

Re-login

Redirect to login

## **8\. Edge Cases**

**Scenario**

**Handling Approach**

**Expected Behavior**

User being edited logs in

Real-time permission update

Apply changes immediately

Brand deleted during edit

Remove from selection

Show brand unavailable

Multiple admins editing same user

Last save wins

Warning about conflicts

Role removed from system

Fallback to default

Assign Basic role

Downgrade with active projects

Maintain read access

Warn about impact

Browser back during edit

Preserve form state

Restore entered data

Permission dependency conflicts

Auto-resolve

Cascade dependencies

Edit after user suspended

Block modifications

Show suspended status

Network loss during save

Retry mechanism

Queue for retry

Partial update failure

Rollback all changes

Show error message

## **9\. Acceptance Criteria**

*   The edit modal must load with all current user information pre-populated accurately
*   Role hierarchy rules must be strictly enforced preventing unauthorized privilege escalation
*   Brand assignments must update immediately upon saving with proper access inheritance
*   At least one brand must remain assigned to maintain user access to the system
*   Project Manager special permissions must be configurable independently of role
*   All changes must be logged to the audit trail with complete before/after values
*   Email notifications must be sent to affected users within 60 seconds of changes
*   The system must prevent users from editing their own roles through any method
*   Agency owner roles must be completely protected from modification
*   Permission changes must apply in real-time to active user sessions
*   Role downgrades must include clear warnings about permission loss
*   The interface must be fully responsive and accessible across devices
*   All field validations must provide clear, actionable error messages
*   Network failures must be handled gracefully with retry capabilities
*   The edit process must complete within 5 seconds under normal conditions

## **10\. Manual Test Cases**

**Test Cases Document:** [Test\_Cases\_Edit\_Team\_Member.xlsx](https://docs.google.com/spreadsheets/d/130CuiwhKs6zdeW3ukKTK3mTa07bcePH5/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Description**

**Impact if Unavailable**

**Fallback Approach**

Database - Users Table

Stores team member information

Cannot load user data

Show error message

Database - Roles Table

Defines available roles

Cannot show roles

Use cached data

Database - Brands Table

Lists agency brands

Cannot assign brands

Show current only

Database - User\_Brands

Maps user-brand relationships

Cannot update brands

Prevent changes

Database - Permissions

Stores role permissions

Cannot verify permissions

Block role changes

Authentication Service

Validates edit permissions

Cannot authorize

Deny access

Email Service

Sends notifications

Cannot notify users

Queue for later

Audit Log Service

Records changes

Cannot log edits

Queue locally

WebSocket Service

Real-time updates

No live updates

Require refresh

Session Management

Updates user sessions

No immediate effect

Force re-login

Cache Service

Clears permission cache

Stale permissions

Manual cache clear

Validation Service

Validates inputs

Basic validation only

Client-side only

## **12\. References**

**Figma Designs:** [**Figma**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=26731-16308&t=oyNB4QWzT2ouAyqD-0)

5\. Delete Team Member

## **FRD#5 Delete Team Member and Its Impact**

## **1\. Module Overview**

**Module Name:** Delete Team Member and Its Impact

**Purpose:** The Delete Team Member module provides authorized administrators with the ability to permanently remove team members from the agency while ensuring seamless data transfer to the agency owner, maintaining business continuity and preventing data loss across all interconnected systems.

**Business Goals:** This module ensures controlled team member removal with comprehensive data preservation, automatic ownership transfer of all created content and assignments to prevent workflow disruption, and complete audit trail maintenance for compliance and security requirements.

## **2\. User Roles & Permissions**

**Role**

**Can Delete Members**

**Can Delete Admins**

**Can Delete Owner**

**View Deletion Impact**

**Restore Deleted**

Owner

✓

✓

✗

✓

✗ (Phase 2)

Admin

✓ (Non-Admins)

✗

✗

✓

✗

Project Manager

✗

✗

✗

✗

✗

Supervising Editor

✗

✗

✗

✗

✗

Junior Editor

✗

✗

✗

✗

✗

Basic (TBD)

✗

✗

✗

✗

✗

_Note: Phase 2 will introduce a secret trash folder accessible only to the Owner for potential data restoration._

## **3\. User Flow**

**3.1 Accessing Delete Function** 3.1.1 The user navigates to the Team Management listing page and identifies the team member to be removed from the agency. 3.1.2 The user hovers over the team member row which highlights with a subtle background color change indicating available actions. 3.1.3 The user clicks on the Delete action button (trash icon) next to the target team member, which is only visible for authorized roles. 3.1.4 The system validates the current user's permission to delete the selected team member based on role hierarchy rules. 3.1.5 If the user lacks permission, the system displays an error message and prevents the deletion dialog from opening.

**3.2 Deletion Confirmation Dialog** 3.2.1 The system displays a modal dialog titled "Delete Team Member" with a semi-transparent background overlay preventing interaction with the underlying page. 3.2.2 The modal header prominently displays the team member's full name with the message "Are you sure you want to remove \[User Name\]?" for clear identification. 3.2.3 The dialog shows a yellow warning banner stating "This action is permanent and will transfer all data to the agency owner" to emphasize the irreversible nature. 3.2.4 The system queries and displays impact summary statistics including number of projects owned, active tasks assigned, automations created, and email templates authored. 3.2.5 Each impact category shows a numerical count with an expandable arrow allowing the user to view detailed lists of affected items. 3.2.6 The modal includes both Cancel and Delete buttons, with the Delete button initially disabled until confirmation requirements are met.

**3.3 Impact Assessment Review** 3.3.1 The modal presents a categorized breakdown showing "Projects (X owned)" with the count of projects that will transfer to the agency owner. 3.3.2 The "Tasks (Y assigned)" section displays the number of active tasks currently assigned to the user being deleted. 3.3.3 The "Automations (Z created)" category shows all automation workflows created by the user that will transfer ownership. 3.3.4 The "Email Templates (N authored)" section lists templates that will be reassigned to the agency owner for continuity. 3.3.5 The user can click "Show More" on any category to expand and view a detailed list of the first 10 items with names and statuses. 3.3.6 Items marked as active or in-progress display with a yellow indicator badge to highlight items requiring immediate attention after transfer.

**3.4 Confirmation Input Process** 3.4.1 The confirmation section displays instructions stating "Type DELETE to confirm" with an input field below for the confirmation text. 3.4.2 The user must type the word "DELETE" exactly as shown in uppercase letters to enable the deletion button. 3.4.3 The system performs real-time validation as the user types, showing a red X for incorrect text and a green checkmark when "DELETE" is correctly entered. 3.4.4 The Delete button remains disabled and grayed out until the confirmation text exactly matches "DELETE" with proper capitalization. 3.4.5 If the user types incorrectly, a helper text appears saying "Please type DELETE exactly as shown" to guide proper entry. 3.4.6 The Cancel button remains active throughout allowing the user to abort the deletion process at any point before confirmation.

**3.5 Deletion Execution Process** 3.5.1 The user clicks the now-enabled Delete button after entering the confirmation text to initiate the removal process. 3.5.2 The system immediately disables both buttons and displays a processing spinner with the message "Removing team member and transferring data..." 3.5.3 The deletion transaction begins encompassing user removal, data transfers, permission updates, and relationship modifications across multiple database tables. 3.5.4 Progress indicators update in real-time showing "Transferring projects...", "Reassigning tasks...", "Updating automations...", "Finalizing removal..." 3.5.5 The system processes each data category sequentially to ensure proper transfer order and maintain referential integrity. 3.5.6 If any step fails, the entire transaction rolls back and displays an error message with the option to retry or contact support.

**3.6 Data Transfer Execution** 3.6.1 The system transfers ownership of all projects created by the deleted user to the agency owner's account maintaining all project data and history. 3.6.2 All tasks assigned to the deleted user are reassigned to the agency owner with an audit note "Reassigned from \[Deleted User\] due to account removal" 3.6.3 Automation workflows created by the deleted user update their creator\_id and modifier\_id fields to the agency owner while preserving all configuration. 3.6.4 Email templates, signatures, and saved responses transfer to the agency owner maintaining formatting and variable configurations. 3.6.5 File attachments and uploaded content change ownership to the agency owner while preserving sharing permissions and access links. 3.6.6 Comments and activity logs created by the deleted user remain but display "\[Deleted User\]" as the author name for historical accuracy.

**3.7 Post-Deletion Updates** 3.7.1 Upon successful deletion, the modal automatically closes and displays a success toast notification "Team member removed successfully. All data has been transferred to the agency owner." 3.7.2 The team listing page refreshes automatically removing the deleted member from the display and updating the total member count. 3.7.3 The system sends an email notification to the agency owner detailing all transferred items categorized by type with counts and any requiring immediate attention. 3.7.4 An immutable audit log entry records the deletion event including who deleted whom, timestamp, IP address, and complete inventory of transferred items. 3.7.5 The subscription service updates to decrement the used seat count, potentially affecting billing if the agency was at or over their limit. 3.7.6 Any active sessions for the deleted user terminate immediately with API tokens invalidated preventing any further access attempts.

**3.8 Cleanup and Finalization** 3.8.1 The system removes all user access credentials from the authentication service preventing any login attempts with previous credentials. 3.8.2 The deleted user's email address enters a 30-day cooling period before becoming available for re-invitation to prevent immediate reuse. 3.8.3 Historical records throughout the system update to show "\[Deleted User\]" maintaining referential integrity without exposing removed user details. 3.8.4 The system updates all cached data including team counts, permission matrices, and user lists to reflect the removal. 3.8.5 WebSocket connections broadcast the update to all active admin users ensuring real-time synchronization across concurrent sessions. 3.8.6 Background jobs process lower-priority updates such as report regeneration and analytics recalculation to reflect the team change.

## **4\. Functional Logic**

**4.1 Permission Validation and Hierarchy**

*   The system enforces strict hierarchical deletion rules where users can only delete team members at permission levels below their own role.
*   Agency owners possess unrestricted deletion rights for any team member except themselves, maintaining account integrity through self-deletion prevention.
*   Admin users can delete Project Managers, all Editor roles, and Basic users but face restrictions preventing deletion of peer Admins or the Owner.
*   The system blocks deletion of the last remaining Admin when no Owner exists, ensuring at least one administrator remains active.
*   Self-deletion prevention occurs at multiple validation layers including UI button hiding, API endpoint validation, and database constraint enforcement.
*   Cross-role deletion attempts trigger immediate permission denied responses with specific error messages explaining the restriction.

**4.2 Comprehensive Data Transfer Mechanisms**

*   Project ownership transfers execute UPDATE statements setting project.owner\_id to the agency owner's ID while preserving all project metadata, history, and relationships.
*   Task reassignment creates detailed audit entries with messages "Reassigned from \[Deleted User\] to \[Agency Owner\] due to user removal" for compliance tracking.
*   Automation ownership transfers maintain all triggers, conditions, actions, and scheduling while updating only creator and modifier metadata fields.
*   Email template transfers preserve all HTML formatting, merge variables, and brand associations while changing only the ownership and management fields.
*   File attachment ownership transfers to the agency owner maintaining all sharing permissions, access links, and folder structures intact.
*   Client communication history persists with sender information anonymized to "\[Former Team Member\]" preserving conversation context.

**4.3 Foreign Key Relationship Management**

*   The system identifies all foreign key relationships to the user being deleted across projects, tasks, comments, files, and activity tables.
*   Comments and activity logs created by the deleted user remain intact but display "\[Deleted User\]" as the author preserving historical accuracy.
*   Project collaboration history maintains the deleted user's contributions with anonymized references preventing broken audit trails.
*   Client-facing communications sent by the deleted user remain visible but show "\[Former Team Member\]" as sender for continuity.
*   Team collaboration @mentions of the deleted user automatically convert to plain text preventing broken notification references.
*   Database triggers handle cascading updates ensuring no orphaned records remain after user deletion.

**4.4 Subscription and Billing Impact Processing**

*   The system immediately decrements the used\_seats counter in the subscription service upon successful deletion completion.
*   Agencies at maximum capacity gain an available seat for new invitations immediately after the deletion processes.
*   Billing adjustments calculate prorated credits for paid seats no longer in use for the remainder of the current billing period.
*   The system logs all subscription changes with timestamps for accurate billing reconciliation at cycle end.
*   Overage charges cease immediately if the deletion brings the team count back within subscription plan limits.
*   Webhook notifications to the billing service ensure external systems synchronize with the updated team count.

**4.5 Session and Authentication Management**

*   All active sessions for the deleted user receive immediate termination signals forcing logout across all devices and browsers.
*   API tokens associated with the deleted user return 401 Unauthorized status for any subsequent request attempts.
*   WebSocket connections for the deleted user terminate with specific disconnection codes indicating account removal.
*   Mobile application sessions force logout displaying "Your account has been removed from this agency" message.
*   Any in-progress work by the deleted user triggers auto-save before session termination preventing data loss.
*   OAuth tokens and third-party integrations linked to the deleted user account are revoked immediately.

**4.6 Notification and Communication Handling**

*   Scheduled emails created by the deleted user remain active but update sender information to show the agency owner.
*   Email signature associations transfer to use the agency owner's signature maintaining communication consistency.
*   Notification subscriptions for the deleted user are removed from all project, task, and system notification lists.
*   The deleted user receives a final email confirming removal from the agency with the agency owner's contact information.
*   Internal team notifications generate for members who had active collaborations with the deleted user.
*   Pending approval items from the deleted user route to the agency owner for resolution.

**4.7 Audit Trail and Compliance Logging**

*   Deletion events create immutable audit log entries containing deleting user ID, deleted user ID, timestamp, IP address, and user agent.
*   The audit log includes a complete manifest of transferred items with counts, types, and ownership changes for each category.
*   Compliance reports can reconstruct the deleted user's complete access history and contribution record for regulatory requirements.
*   The system maintains soft-deleted user records for 90 days before permanent purge enabling recovery if needed.
*   Legal hold provisions prevent deletion of users involved in active litigation or compliance investigations.
*   All permission checks and deletion attempts log to security audit trails for threat detection analysis.

**4.8 Error Handling and Transaction Management**

*   The entire deletion process wraps in a database transaction ensuring atomicity - either complete success or complete rollback.
*   Transaction isolation levels prevent concurrent modifications during the deletion process avoiding data inconsistencies.
*   Retry logic implements exponential backoff for transient failures with maximum 3 attempts before user notification.
*   Partial failure scenarios generate detailed error logs with specific failure points for support investigation.
*   Recovery procedures can restore deleted users within 24 hours using backup data if critical errors discovered.
*   Database backups maintain pre-deletion state for 30 days enabling manual recovery for compliance requirements.

**4.9 Performance and Optimization Strategies**

*   Large data volume transfers process in configurable batches preventing timeout issues for users with extensive data.
*   Background job queues handle non-critical transfers like historical report updates maintaining UI responsiveness.
*   Database indexes on foreign key columns ensure efficient identification of all related records during deletion.
*   Query optimization uses parallel processing where possible to reduce total deletion time for data-heavy users.
*   Cache invalidation occurs systematically across all cache layers preventing stale user data in cached responses.
*   The system monitors deletion duration and alerts administrators if processing exceeds defined thresholds.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Validation Rules**

**Required**

**Default Value**

User Selection

System Identifier

Valid user\_id in agency

Yes

Selected from list

Confirmation Text

Text Input

Must exactly match "DELETE"

Yes

Empty

Transfer Recipient

System Default

Always agency owner

N/A

Agency owner ID

Impact Summary

Display Only

Calculated counts

N/A

Auto-calculated

Deletion Reason

Text Area

Optional, max 500 chars

No

Empty

Audit Notes

System Generated

Automatic logging

N/A

System timestamp

## **6\. Success Message Handling**

**Operation**

**Success Message**

**Display Duration**

**Post-Success Action**

Deletion Complete

"Team member removed successfully"

5 seconds

Refresh listing

Data Transferred

"All data transferred to agency owner"

5 seconds

Show summary

Seat Released

"Subscription seat now available"

3 seconds

Update counter

Sessions Terminated

"User access revoked immediately"

3 seconds

Log event

Audit Logged

"Deletion recorded in audit trail"

2 seconds

None

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Required User Action**

**System Response**

Cannot delete self

"You cannot delete your own account"

Select different user

Disable button

Cannot delete owner

"Agency owner cannot be deleted"

Cancel operation

Hide delete option

Last admin deletion

"Cannot delete the last administrator"

Assign new admin first

Block deletion

Confirmation mismatch

"Please type DELETE to confirm"

Enter exact text

Keep button disabled

Transfer failure

"Failed to transfer data. Please try again"

Retry operation

Rollback changes

Network timeout

"Operation timed out. Please retry"

Try again

Show retry button

Active projects

"User has active projects requiring review"

Review projects

Show project list

Database error

"System error occurred. Contact support"

Contact support

Log detailed error

Insufficient permissions

"You don't have permission to delete this user"

Contact owner

Hide delete option

User already deleted

"This user has already been removed"

Refresh page

Update listing

## **8\. Edge Cases**

**Scenario**

**Handling Approach**

**Expected Behavior**

Deletion during active session

Force logout immediately

User sees removal message

Large data volume transfer

Process in background

Show progress indicator

Circular project dependencies

Resolve before transfer

Update relationships

Deletion with pending invites sent by user

Cancel pending invitations

Notify invited users

API calls in progress

Complete then invalidate

Graceful termination

Scheduled automations running

Transfer mid-execution

Continue under owner

Client-visible assignments

Maintain visibility

Show as agency work

Compliance hold on user

Block deletion

Show legal hold message

Recent payment processing

Complete transaction

Update billing records

Shared file ownership

Transfer to owner

Maintain share links

Calendar events created

Update organizer

Preserve scheduling

Integration webhooks

Update credentials

Maintain connectivity

Custom role permissions

Reset to defaults

Document changes

Multi-brand assignments

Transfer all brands

Preserve access levels

Mobile app sync pending

Force sync before delete

Prevent data loss

## **9\. Acceptance Criteria**

*   Deletion must require explicit confirmation through typing "DELETE" to prevent accidents
*   All user data must successfully transfer to the agency owner with no data loss
*   The deletion process must complete within 30 seconds for typical user data volumes
*   Active sessions must terminate immediately upon successful deletion
*   Audit logs must capture complete details of the deletion and all transfers
*   Email notifications must be sent to the agency owner and deleted user
*   Subscription seats must update immediately to reflect the removal
*   The system must prevent deletion of protected users (owner, last admin)
*   All foreign key relationships must be properly handled without orphaned records
*   Error handling must provide clear messages and recovery options
*   The deletion must be atomic - either fully complete or fully rolled back
*   Historical references must maintain data integrity with anonymized user references
*   Performance must remain acceptable even for users with extensive data
*   The interface must clearly communicate the permanent nature of deletion
*   Compliance with data retention policies must be maintained

## **10\. Manual Test Cases**

**Test Cases Document:** [Test\_Cases\_Delete\_Team\_Member.xlsx](https://docs.google.com/spreadsheets/d/1tiNOMJhqovq1a8bdqkjJjVwxHKCKLlL6/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Description**

**Impact if Unavailable**

**Fallback Approach**

Database - Users Table

Contains user records

Cannot delete

Show error message

Database - Projects Table

Stores project ownership

Cannot transfer

Block deletion

Database - Tasks Table

Contains task assignments

Cannot reassign

Queue for retry

Database - Automations

Automation ownership

Cannot update

Manual intervention

Database - Audit Log

Deletion history

Cannot log

Local queue

Subscription Service

Seat management

Cannot update count

Manual adjustment

Email Service

Send notifications

Cannot notify

In-app notice

Session Manager

Invalidate sessions

Sessions remain

Force expire later

Cache Service

Clear user data

Stale data

TTL expiration

File Storage

Transfer ownership

Files orphaned

Background job

Billing Service

Adjust charges

Billing incorrect

Manual correction

WebSocket Service

Terminate connections

Connections linger

Timeout naturally

Background Job Queue

Process transfers

Synchronous only

Risk timeout

Backup Service

Pre-deletion snapshot

No recovery option

Warn user

## **12\. References**

**Figma Designs:** [**Figma**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=26731-16308&t=oyNB4QWzT2ouAyqD-0)

6\. Email Signature Management with Impact

## **FRD#5 Email Signature Management with Impact**

## **1\. Module Overview**

**Module Name:** Email Signature Management with Impact

**Purpose:** The Email Signature Management module enables agency owners to create and manage standardized email signatures for all team members across different brands, ensuring consistent professional communication and brand identity in all client-facing emails sent through the CRM system.

**Business Goals:** This module maintains brand consistency across all email communications by providing centralized signature management, reduces time spent on email formatting by auto-populating professional signatures, and ensures compliance with legal and marketing requirements for business communications.

## **2\. User Roles & Permissions**

**Role**

**Create Signatures**

**Edit Signatures**

**Delete Signatures**

**Apply Signatures**

**Override in Email**

Owner

✓

✓

✓

✓

✓

Admin

✗

✗

✗

✓

✓

Project Manager

✗

✗

✗

✓

✓

Supervising Editor

✗

✗

✗

✓

✓

Junior Editor

✗

✗

✗

✓

✓

Basic (TBD)

✗

✗

✗

✓

✓

_Note: While only owners can manage signatures, all team members can use and optionally modify signatures when composing emails._

## **3\. User Flow**

**3.1 Accessing Signature Management** 3.1.1 The agency owner clicks on Settings from the main navigation menu to access system configuration options.

3.1.2 The owner selects "Email Signatures" from the settings submenu, which is only visible to users with owner permissions.

3.1.3 The system loads the signature management interface displaying all existing signatures organized by brand.

**3.2 Creating New Signature** 3.2.1 The owner clicks the "Create New Signature" button to initiate signature creation for a specific brand.

3.2.2 The system opens the signature creation modal with fields for signature name and brand selection.

3.2.3 The owner selects the brand from a dropdown containing all active agency brands for signature association.

3.2.4 The owner enters a descriptive name for the signature such as "Professional Sales Signature" or "Support Team Signature".

**3.3 Signature Editor Interface** 3.3.1 The rich text editor displays with formatting toolbar including bold, italic, underline, text color, and link options.

3.3.2 The owner composes the signature content using the visual editor with real-time preview showing formatted output.

3.3.3 The interface provides a "Best regards," pre-populated greeting line that can be modified or removed as needed.

3.3.4 The owner can insert merge tags like {{user.name}}, {{user.title}}, {{user.phone}} that auto-populate with each user's information.

**3.4 Contact Information Fields** 3.4.1 The owner adds the sender name field using {{user.full\_name}} which dynamically inserts each team member's actual name.

3.4.2 The position/title field uses {{user.job\_title}} to display each team member's role within the organization.

3.4.3 The contact details section includes {{user.phone}}, {{user.email}}, and {{user.mobile}} for comprehensive contact information.

3.4.4 The agency details section can include static information like company address, website, and registration numbers.

**3.5 Brand-Specific Elements** 3.5.1 The owner can upload a brand logo that will appear in all signatures associated with that brand.

3.5.2 Social media links can be added with icons for Facebook, Instagram, LinkedIn, and other platforms relevant to the brand.

3.5.3 Legal disclaimers or confidentiality notices can be added at the signature footer for compliance requirements.

3.5.4 Marketing taglines or current campaign messages can be included with easy updating for all team members.

**3.6 Preview and Testing** 3.6.1 The owner clicks "Preview" to see how the signature will appear with sample user data populated in merge fields.

3.6.2 The preview shows both HTML and plain text versions to ensure compatibility across different email clients.

3.6.3 The owner can switch between different team member previews to verify signature appearance for various users.

3.6.4 Mobile preview option shows how the signature will display on smartphones and tablets for responsive design verification.

**3.7 Saving and Assignment** 3.7.1 The owner clicks "Save Signature" which validates all merge tags and formatting before storing in the database.

3.7.2 The system automatically assigns the signature to all team members who have access to the associated brand.

3.7.3 A success notification confirms "Signature created and applied to \[X\] team members with \[Brand\] access."

3.7.4 The signature immediately becomes available in the email composition interface for applicable team members.

**3.8 Managing Existing Signatures** 3.8.1 The signature list displays all created signatures with brand association, creation date, and number of users assigned.

3.8.2 The owner can click "Edit" on any signature to modify content, formatting, or brand association as needed.

3.8.3 The "Duplicate" option allows copying an existing signature as a template for creating similar signatures for other brands.

3.8.4 The "Delete" option removes signatures with confirmation dialog warning about impact on team member emails.

**3.9 Email Composition Integration** 3.9.1 When any team member composes an email, the system automatically loads their default signature for the selected brand.

3.9.2 The signature appears at the bottom of the email compose window with the user's actual information populated.

3.9.3 Team members can modify the signature content for specific emails using the inline editor if needed.

3.9.4 Users can choose to remove the signature entirely for informal communications by clicking the "Remove Signature" option.

## **4\. Functional Logic**

**4.1 Signature Creation and Storage**

*   Signatures are stored in the email\_signatures table with fields for content\_html, content\_text, brand\_id, and configuration metadata.
*   The system maintains both HTML and plain text versions of each signature for compatibility with different email client capabilities.
*   Rich text editor content converts to clean HTML with inline CSS styles to ensure consistent rendering across email platforms.
*   Merge tags are validated against available user fields to prevent broken variable references in sent emails.
*   Each signature is uniquely associated with a single brand, preventing signature confusion in multi-brand agencies.

**4.2 Dynamic Content Population**

*   Merge tags like {{user.name}} are replaced with actual user data at email send time, not during signature creation.
*   The system pulls user information from the users table including name, title, phone, and custom fields for substitution.
*   Fallback values are defined for optional fields, showing empty strings rather than broken tags if data is missing.
*   Brand-specific variables like {{brand.website}} and {{brand.phone}} pull from the brands configuration table.
*   Date-based variables like {{current.year}} update automatically for copyright notices and time-sensitive content.

**4.3 Brand Association Logic**

*   Signatures are filtered by brand access, showing only relevant signatures to users based on their brand permissions.
*   Multi-brand users see different signatures in the dropdown depending on which brand context they're operating in.
*   Default signature selection is based on the primary brand if no specific brand context is active.
*   Brand deletion triggers cascade updates to remove associated signatures or reassign to a default brand.
*   Cross-brand signature sharing is prevented to maintain brand identity separation within the same agency.

**4.4 Permission Enforcement**

*   Only agency owners can access the signature management interface through role-based access control checks.
*   The system validates owner permissions at both UI and API levels to prevent unauthorized signature modifications.
*   Team members cannot create or edit master signatures but retain flexibility to modify signatures in individual emails.
*   Audit logs track all signature creation, modification, and deletion actions with timestamp and user identification.
*   Permission inheritance ensures new team members automatically receive appropriate signature access based on their role and brands.

**4.5 Email Integration Workflow**

*   The email composition interface loads applicable signatures based on user ID, brand context, and active signature configurations.
*   Signature injection occurs at the email template level, appending after the main email body content automatically.
*   Modified signatures in individual emails are treated as one-time overrides without affecting the master signature template.
*   Reply and forward emails maintain signature placement logic, avoiding duplicate signatures in email threads.
*   Bulk email campaigns can use consistent signatures across all recipients while maintaining personalization through merge tags.

**4.6 Formatting and Compatibility**

*   HTML signatures use inline CSS exclusively since many email clients strip external stylesheets and style blocks.
*   Image handling converts uploads to base64 encoding or hosted URLs depending on email client compatibility settings.
*   Font stacks include web-safe fallbacks to ensure consistent appearance when custom fonts aren't supported.
*   Maximum signature size is enforced at 15KB to prevent email delivery issues with providers that have size limits.
*   Mobile-responsive signatures use fluid layouts and appropriate image sizing for optimal display on all devices.

**4.7 Version Control and History**

*   The system maintains signature version history allowing owners to revert to previous versions if needed.
*   Each edit creates a new version entry with timestamp, editor ID, and change description for audit purposes.
*   Active signature versions are cached for performance, with cache invalidation on any signature update.
*   Deleted signatures are soft-deleted for 30 days, allowing recovery if accidentally removed.
*   Signature templates can be exported as HTML files for backup or migration to other systems.

**4.8 Performance Optimization**

*   Frequently used signatures are cached in memory to reduce database queries during email composition.
*   Lazy loading of signature content occurs only when email interface is activated, not on page load.
*   Batch processing handles signature updates for multiple users when brand associations change.
*   Database indexing on brand\_id and user\_id ensures fast signature retrieval even with many signatures.
*   CDN delivery of signature images reduces load times and improves email rendering performance.

**4.9 Compliance and Legal**

*   Signatures can include required legal disclaimers for regulated industries with automatic inclusion enforcement.
*   GDPR-compliant unsubscribe links can be embedded in signatures for marketing communications.
*   The system tracks signature usage in sent emails for compliance reporting and audit requirements.
*   Data retention policies apply to signature history with automatic purging after configured retention periods.
*   Signature content is sanitized to prevent XSS attacks and malicious code injection in emails.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Validation Rules**

**Required**

**Default Value**

Signature Name

Text Input

Max 100 characters, unique per brand

Yes

Empty

Brand Selection

Dropdown

Must be active brand

Yes

Primary brand

Signature Content

Rich Text Editor

Max 15KB, valid HTML

Yes

Template

Logo Upload

File Upload

JPG, PNG, GIF, max 500KB

No

None

User Name Tag

Merge Variable

{{user.full\_name}}

No

Empty

User Title Tag

Merge Variable

{{user.job\_title}}

No

Empty

Phone Tag

Merge Variable

{{user.phone}}

No

Empty

Email Tag

Merge Variable

{{user.email}}

No

Empty

Website URL

URL Input

Valid URL format

No

Brand default

Social Links

URL Inputs

Valid social media URLs

No

Empty

Legal Text

Text Area

Max 500 characters

No

Empty

## **6\. Success Message Handling**

**Operation**

**Success Message**

**Display Duration**

**Post-Success Action**

Signature Created

"Email signature created successfully"

5 seconds

Show in list

Signature Updated

"Changes saved to signature"

3 seconds

Update preview

Signature Deleted

"Signature removed successfully"

3 seconds

Remove from list

Signature Duplicated

"Signature copied successfully"

3 seconds

Open for editing

Applied to Users

"Signature applied to \[X\] team members"

5 seconds

Update count

Preview Generated

"Preview loaded"

2 seconds

Display preview

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Required User Action**

**System Response**

Duplicate name

"A signature with this name already exists"

Choose different name

Highlight field

Invalid merge tag

"Unknown variable: {{tag}}"

Correct or remove tag

Show invalid tags

Image too large

"Image must be under 500KB"

Compress or replace

Clear upload

Missing required field

"Signature name is required"

Enter name

Focus on field

HTML syntax error

"Invalid HTML formatting detected"

Fix formatting

Show error location

No brand selected

"Please select a brand for this signature"

Select brand

Highlight dropdown

Signature too large

"Signature exceeds 15KB limit"

Reduce content

Show current size

Network save failure

"Failed to save signature. Please try again"

Retry save

Keep editor open

Invalid URL format

"Please enter a valid URL"

Correct URL

Mark field red

Permission denied

"Only owners can manage signatures"

Contact owner

Hide interface

## **8\. Edge Cases**

**Scenario**

**Handling Approach**

**Expected Behavior**

User without job title

Skip merge tag

Show empty string

Brand with no signatures

Show empty state

Prompt to create

Deleted user in signature

Maintain signature

Remove from assignment

Multiple signatures per brand

Allow selection

Set default

Circular merge tag reference

Prevent saving

Show error

Email client strips formatting

Provide plain text

Fallback version

Signature in email reply

Smart placement

Avoid duplication

Offline editing

Queue changes

Sync when online

Import from external source

Parse and clean

Convert to format

Special characters in tags

Escape properly

Prevent injection

Very long user names

Truncate display

Show full on hover

Missing brand logo

Skip image

Text only signature

Concurrent editing

Last save wins

Warning message

Language-specific signatures

Support UTF-8

Multi-language

Signature exceeds email limit

Truncate

Warning to user

## **9\. Acceptance Criteria**

*   Only agency owners can access and manage email signatures through the settings menu
*   Signatures must be created and associated with specific brands for proper filtering
*   Rich text editor must support standard formatting options with real-time preview
*   Merge tags must dynamically populate with actual user data at email send time
*   All team members with brand access must automatically receive associated signatures
*   Signatures must appear automatically in email composition with option to modify
*   Both HTML and plain text versions must be maintained for compatibility
*   Image uploads must be optimized and stored efficiently for email use
*   Signature modifications in individual emails must not affect the master template
*   The system must handle missing user data gracefully without showing broken tags
*   Performance must remain optimal even with many signatures and users
*   Mobile-responsive signatures must display correctly on all devices
*   Audit trail must capture all signature management actions
*   Legal disclaimers and compliance text must be supported
*   Signature size must be limited to prevent email delivery issues

## **10\. Manual Test Cases**

**Test Cases Document:** [Test\_Cases\_Email\_Signature\_Management.xlsx](https://docs.google.com/spreadsheets/d/15qbI8Px215O0y9B33Zsw8lhx5SrLNKdd/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Description**

**Impact if Unavailable**

**Fallback Approach**

Database - Signatures Table

Stores signature templates

Cannot save signatures

Show error

Database - Users Table

Provides merge data

Cannot populate tags

Use placeholders

Database - Brands Table

Brand associations

Cannot filter

Show all signatures

Rich Text Editor

Format signatures

Plain text only

Basic textarea

Image Storage Service

Store logos/images

Text signatures only

Skip images

Email Service

Apply signatures

Manual signature

Copy/paste

Cache Service

Performance optimization

Slower loading

Direct DB queries

CDN Service

Deliver images

Local hosting

Embed base64

Template Engine

Process merge tags

Static content only

No personalization

HTML Sanitizer

Security filtering

Security risk

Block HTML

Audit Log Service

Track changes

No history

Local logging

Session Management

Permission checks

Cannot validate

Deny access

## **12\. References**

**Figma Designs:** [**Figma**](https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=26731-16003&t=oyNB4QWzT2ouAyqD-0)

7\. Team Member Roles & Permissions

## **FRD#5 Jr. Team Member Roles & Permissions**

## **1\. Module Overview**

**Module Name:** Team Member Roles & Permissions

**Purpose:** The Team Member Roles & Permissions module defines and manages the hierarchical role-based access control system that governs what each team member can view, create, edit, and delete across all CRM modules, ensuring proper security and operational efficiency.

**Business Goals:** This module establishes clear permission boundaries to protect sensitive data and maintain operational control, enables scalable team growth with predefined role templates that can be assigned quickly, and provides the foundation for Phase 2 customization where agencies can modify permissions for their specific needs.

_Note: Phase 1 implements global role definitions applied uniformly across all agencies. Phase 2 will introduce agency-specific role customization capabilities._

## **2\. User Roles & Permissions**

**Detailed Permission Matrix:** View Complete Permissions Matrix

**Role**

**System Access**

**Team Management**

**Project Access**

**Financial Access**

**Client Communication**

Owner

Full Access

Full Control

All Projects

Full Access

Full Access

Admin

Full Access

Manage All

All Projects

View & Manage

Full Access

Project Manager

Limited

View Only

Assigned Only

View Own

Full Access

Supervising Editor

Limited

View Only

Assigned Only

None

Limited

Junior Editor

Limited

View Only

Assigned Only

None

Limited

Basic (TBD)

Limited

View Only

Assigned Only

None

View Only

## **3\. User Flow**

**3.1 Role Assignment During Invitation** 3.1.1 When inviting a new team member, the authorized user selects a role from the predefined role dropdown in the invitation modal.

3.1.2 The system displays a brief description of the selected role's capabilities to help the inviter make an informed decision.

3.1.3 Upon invitation acceptance and account creation, the system automatically assigns all permissions associated with the selected role.

3.1.4 The new team member's first login experience is customized based on their role, showing only accessible modules and features.

**3.2 Permission Verification at Login** 3.2.1 When a team member logs in, the system queries their role from the users table and loads associated permissions.

3.2.2 The navigation menu dynamically renders showing only modules the user has permission to access based on their role.

3.2.3 Dashboard widgets and quick actions are filtered to display only functionality available to the user's permission level.

3.2.4 The system caches permissions in the session for performance, refreshing only when role changes occur.

**3.3 Module Access Control** 3.3.1 When a user attempts to access any module, the system validates their permission before rendering the interface.

3.3.2 If the user lacks view permission for a module, the system displays "You don't have permission to access this area" and redirects to dashboard.

3.3.3 Within accessible modules, action buttons like Edit, Delete, and Create are shown or hidden based on specific role permissions.

3.3.4 API endpoints validate permissions server-side, preventing unauthorized actions even if UI restrictions are bypassed.

**3.4 Project-Level Permissions** 3.4.1 Project Managers and Editors see only projects explicitly assigned to them through the project assignment system.

3.4.2 Owners and Admins bypass project-level filtering, seeing all projects across all brands within the agency.

3.4.3 When viewing project lists, the system applies WHERE clauses based on role to filter results appropriately.

3.4.4 Project creation permissions determine whether users see the "Create New Project" button in project interfaces.

**3.5 Brand-Based Access** 3.5.1 Users can only access data within brands they've been explicitly assigned during invitation or through role editing.

3.5.2 Multi-brand users see a brand switcher in the interface, with permissions applying within each brand context.

3.5.3 Cross-brand data access is prevented even for high-permission roles unless explicitly granted brand access.

3.5.4 Brand filtering occurs at the database query level for security, not just UI hiding.

**3.6 Financial Data Restrictions** 3.6.1 Financial modules including billing, invoicing, and revenue reports are restricted to Owner and Admin roles only.

3.6.2 Project Managers can view project-specific budgets and costs but cannot access agency-wide financial data.

3.6.3 Editors have no access to any financial information, with these sections completely hidden from their interface.

3.6.4 Payment processing and refund capabilities are limited to Owner role with Admin having view-only access.

**3.7 Communication Permissions** 3.7.1 Client communication permissions determine who can send emails, messages, and notifications to clients.

3.7.2 All roles except Basic can communicate with clients, but only Owners and Admins can send agency-wide communications.

3.7.3 Automated email permissions control who can create and modify email templates and automation workflows.

3.7.4 Internal team communication is unrestricted, allowing all team members to collaborate via internal messaging.

**3.8 Administrative Functions** 3.8.1 System settings, integrations, and configuration options are accessible only to the Owner role.

3.8.2 Admins can manage team members and moderate content but cannot modify system-level configurations.

3.8.3 Subscription management and billing controls are exclusive to the Owner to prevent unauthorized plan changes.

3.8.4 API key generation and third-party integration setup require Owner permissions for security.

## **4\. Functional Logic**

**4.1 Role Definition Structure**

*   Each role is defined in the roles table with a unique identifier, name, description, and hierarchy level for permission inheritance.
*   The roles\_permissions junction table maps each role to specific permissions across all system modules and actions.
*   Permissions are granular, defining view, create, edit, delete, and manage capabilities for each module independently.
*   Role hierarchy ensures that higher roles inherit all permissions of lower roles plus additional capabilities.
*   The system prevents creation of custom roles in Phase 1, using only the predefined six roles for consistency.

**4.2 Permission Inheritance Model**

*   Owner role has unrestricted access to all system features, serving as the super-admin for the agency.
*   Admin role inherits most Owner permissions except system configuration and subscription management.
*   Project Manager role focuses on project-level permissions with limited access to agency-wide features.
*   Supervising Editor has enhanced editorial permissions compared to Junior Editor, including approval capabilities.
*   Junior Editor has basic editorial access for assigned projects without approval or publishing rights.
*   Basic role (TBD) provides minimal read-only access for stakeholders who need visibility without modification rights.

**4.3 Dynamic Permission Checking**

*   Every API endpoint includes middleware that validates the requesting user's permissions before processing.
*   Frontend components use permission directives to conditionally render UI elements based on user capabilities.
*   Database queries automatically include role-based filtering to prevent unauthorized data access at the query level.
*   Real-time permission updates propagate to active sessions when roles change without requiring re-login.
*   Permission caching uses Redis with 5-minute TTL to balance performance with security freshness.

**4.4 Project Assignment Logic**

*   Project assignments create explicit relationships between users and projects in the user\_projects junction table.
*   Assignment permissions determine whether users can self-assign projects or require assignment by administrators.
*   Removing project assignments immediately revokes access, with changes reflecting in real-time for active users.
*   Bulk assignment capabilities allow Admins to assign multiple projects to team members efficiently.
*   Project ownership separate from role permissions provides additional granular control over project responsibilities.

**4.5 Module-Specific Permissions**

*   CRM module permissions control access to leads, contacts, and customer relationship features.
*   Project management permissions govern project creation, task assignment, and workflow management.
*   Content permissions determine who can create, edit, publish, and archive content within the system.
*   Report permissions control access to analytics, with role-based filtering of available metrics and data.
*   Integration permissions determine who can configure and manage third-party service connections.

**4.6 Data Visibility Rules**

*   Row-level security ensures users only see data they have explicit permission to access.
*   Column-level permissions hide sensitive fields like financial data from unauthorized roles.
*   Aggregate data in reports respects individual data permissions, excluding unauthorized records from calculations.
*   Search functionality filters results based on permissions, never exposing unauthorized data in search results.
*   Export capabilities respect permission boundaries, only including authorized data in downloaded files.

**4.7 Permission Conflict Resolution**

*   When users have multiple roles through different contexts, the highest permission level applies.
*   Explicit denials override implicit allowances to ensure security restrictions are maintained.
*   Brand-specific permissions take precedence over global role permissions for brand-isolated data.
*   Temporary permission elevation for specific tasks reverts automatically after task completion.
*   Permission conflicts are logged for audit and reviewed to improve permission model design.

**4.8 Audit and Compliance**

*   All permission checks are logged with user, action, resource, result, and timestamp for audit trails.
*   Failed permission attempts trigger security alerts after threshold breaches for potential breach detection.
*   Compliance reports can demonstrate proper access control for regulatory requirements.
*   Permission change history is maintained indefinitely for forensic analysis if needed.
*   Regular permission audits identify and flag unusual permission patterns or potential security issues.

**4.9 Performance Optimization**

*   Permission matrices are precomputed and cached to avoid runtime calculation overhead.
*   Database indexes on permission-related columns ensure fast permission checking queries.
*   Bulk permission operations use batch processing to handle large team updates efficiently.
*   Permission inheritance is resolved at role assignment time, not runtime, for performance.
*   Static permission definitions in Phase 1 eliminate the overhead of dynamic permission resolution.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Validation Rules**

**Required**

**Default Value**

Role ID

System Generated

Unique identifier

Yes

Auto-increment

Role Name

Enum

Predefined set only

Yes

None

User Assignment

Foreign Key

Valid user\_id

Yes

None

Brand Assignment

Foreign Key

Valid brand\_id

Yes

None

Permission Level

Integer

1-6 hierarchy

Yes

Based on role

Module Access

Boolean Array

Per module flags

Yes

Role defaults

Action Permissions

JSON

CRUD permissions

Yes

Role template

Assignment Date

Timestamp

DateTime

Yes

Current time

Modified By

Foreign Key

Valid admin user\_id

Yes

Current user

Is Active

Boolean

Active/Inactive

Yes

True

## **6\. Success Message Handling**

**Operation**

**Success Message**

**Display Duration**

**Post-Success Action**

Role Assigned

"Role successfully assigned to user"

5 seconds

Update listing

Permissions Applied

"Permissions updated successfully"

3 seconds

Refresh access

Access Granted

"Access granted to requested resource"

3 seconds

Load resource

Access Revoked

"Access removed successfully"

3 seconds

Redirect user

Audit Logged

"Action logged for compliance"

2 seconds

Continue

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Required User Action**

**System Response**

Insufficient permissions

"You don't have permission to perform this action"

Contact admin

Log attempt

Invalid role assignment

"This role cannot be assigned to this user"

Select valid role

Block assignment

Module access denied

"You cannot access this module"

Request access

Redirect to dashboard

Permission conflict

"Permission settings conflict detected"

Review settings

Show conflicts

Role not found

"Selected role does not exist"

Refresh and retry

Reload roles

Circular permission

"This would create a permission loop"

Adjust settings

Prevent save

Exceeded role limit

"Maximum number of admins reached"

Review team structure

Block creation

Database error

"Failed to update permissions"

Retry operation

Rollback changes

Cache sync failure

"Permissions may not reflect recent changes"

Refresh browser

Clear cache

Audit log failure

"Action completed but not logged"

Report to IT

Queue for retry

## **8\. Edge Cases**

**Scenario**

**Handling Approach**

**Expected Behavior**

User with no role

Assign Basic role

Minimal access

Deleted role reference

Fallback to Basic

Maintain access

Multiple role contexts

Highest permission wins

Maximum access

Permission during transition

Snapshot permissions

Consistent access

Cross-agency access attempt

Strict isolation

Block completely

Suspended user permissions

Revoke all access

Force logout

API token permissions

Match user role

Same restrictions

Mobile app permissions

Sync with web

Consistent access

Offline permission checks

Cache last known

Allow cached only

Custom role migration

Map to standard

Best fit matching

Legacy permission data

Migration script

Convert format

High-volume permission checks

Rate limiting

Prevent DOS

Concurrent role changes

Version control

Last write wins

Emergency access override

Owner bypass

Log extensively

Permission rollback needed

Restore from backup

Point-in-time recovery

## **9\. Acceptance Criteria**

*   Role-based access control must be enforced at both UI and API levels
*   All six predefined roles must be available for assignment during team member invitation
*   Permission checks must occur in under 100ms for optimal user experience
*   Users must only see and access data within their permission boundaries
*   Role changes must take effect immediately for active user sessions
*   Audit logs must capture all permission-related actions and access attempts
*   The system must prevent privilege escalation through any method
*   Brand-based isolation must be maintained regardless of role level
*   Financial and sensitive data must be restricted to authorized roles only
*   Permission inheritance must work correctly through the role hierarchy
*   Error messages must clearly indicate why access was denied
*   The permission system must scale to support hundreds of users per agency
*   Database queries must automatically filter based on user permissions
*   Mobile and web applications must have synchronized permission enforcement
*   Phase 1 must use global role definitions consistently across all agencies

## **10\. Manual Test Cases**

**Test Cases Document:** [Test\_Cases\_Roles\_and\_Permissions.xlsx](https://docs.google.com/spreadsheets/d/1g0-IklHuQa6WrFtuK2LCm4cEiVgc2IOj/edit?usp=drive_link&ouid=105170312247554220827&rtpof=true&sd=true)

## **11\. Dependencies**

**Dependency Type**

**Description**

**Impact if Unavailable**

**Fallback Approach**

Database - Roles Table

Stores role definitions

Cannot assign roles

Use cached data

Database - Permissions Table

Permission mappings

Cannot check access

Deny by default

Database - User\_Roles

User role assignments

Cannot identify role

Assume Basic

Cache Service (Redis)

Permission caching

Slower checks

Direct DB queries

Session Management

User context

Cannot authenticate

Force re-login

Audit Log Service

Compliance tracking

No audit trail

Queue locally

API Gateway

Request filtering

No API protection

Block all APIs

Frontend Framework

UI permission directives

No UI filtering

Hide all actions

Message Queue

Permission sync

Delayed updates

Direct updates

Database Indexes

Query performance

Slow permission checks

Add indexes

Brand Service

Brand context

No brand filtering

Block access

Project Service

Project assignments

Cannot filter projects

Show none

## **12\. References**

**Permission Matrix Documentation:**

*   Complete Roles & Permissions Matrix: The

**Phase 2 Considerations:**

*   Agency-specific role customization
*   Custom role creation interface
*   Permission template marketplace
*   Advanced permission delegation

Tab 9

# **Team Member Roles & Permissions - Complete FRD**

## **1\. Module Overview**

**Module Name:** Team Member Roles & Permissions

**Purpose:** The Team Member Roles & Permissions module defines and manages the hierarchical role-based access control system that governs what each team member can view, create, edit, and delete across all CRM modules, ensuring proper security and operational efficiency.

**Business Goals:** This module establishes clear permission boundaries to protect sensitive data and maintain operational control, enables scalable team growth with predefined role templates that can be assigned quickly, and provides the foundation for Phase 2 customization where agencies can modify permissions for their specific needs.

**Note:** Phase 1 implements global role definitions applied uniformly across all agencies. Phase 2 will introduce agency-specific role customization capabilities.

## **2\. User Roles & Permissions**

**Detailed Permission Matrix:** [View Complete Permissions Matrix](https://claude.ai/chat/Roles_and_Permissions_Matrix_Complete.xlsx)

### 2.1 Role Hierarchy Overview

**Role**

**System Access**

**Team Management**

**Project Access**

**Financial Access**

**Client Communication**

**Agency Owner**

Full Access

Full Control

All Projects

Full Access

Full Access

**Admin**

Full Access

Manage All

All Projects

View & Manage

Full Access

**Project Manager**

Limited

View Only

Assigned Only

View Own

Full Access

**Supervising Editor**

Limited

View Only

Assigned Only

None

Limited

**Editor**

Limited

View Only

Assigned Only

None

Limited

### 2.2 Role-Specific Capabilities

**Agency Owner:**

*   Ultimate authority with unrestricted access to all system features
*   Only role that can manage subscriptions and process refunds
*   Exclusive access to system settings and API key generation
*   Can create and manage email signatures for all brands
*   Complete financial control including bank account access

**Admin:**

*   Administrative control with financial viewing limitations
*   Can invite and manage all team roles except Owner
*   Full project management across all brands
*   View financial reports but cannot process transactions
*   Cannot access system settings or subscription management

**Project Manager:**

*   Project-focused leadership role with brand-specific access
*   Can create projects within assigned brands only
*   Views only explicitly assigned projects
*   Can assign team members to their own projects
*   Access to project-specific budgets but not agency-wide finances
*   Cannot invite team members or manage roles

**Supervising Editor:**

*   Enhanced editorial capabilities with cross-project collaboration
*   Can view all team member pipelines for coordination purposes
*   Ability to create content in other users' projects
*   Limited email template creation capabilities
*   Cannot access financial data or manage team members
*   Can change project statuses on assigned projects

**Editor:**

*   Basic content creation role with project-specific limitations
*   Can only view and edit assigned projects
*   Can change statuses on their own projects only
*   View and message primary employee assignees
*   No access to team management or financial data
*   Cannot view other team members' pipelines

## **3\. User Flow**

### 3.1 Role Assignment During Invitation

**3.1.1** When inviting a new team member, the authorized user selects a role from the predefined role dropdown in the invitation modal.

*   **Agency Owner** can assign any role including Admin
*   **Admin** can assign Project Manager, Supervising Editor, and Editor roles
*   **Project Manager, Supervising Editor, Editor** cannot invite team members

**3.1.2** The system displays a brief description of the selected role's capabilities to help the inviter make an informed decision.

*   Role descriptions include specific permissions and limitations
*   Visual indicators show access levels for each module
*   Brand assignment requirements are clearly displayed

**3.1.3** Upon invitation acceptance and account creation, the system automatically assigns all permissions associated with the selected role.

*   **Agency Owner** receives full system access immediately
*   **Admin** gains administrative permissions but financial restrictions apply
*   **Project Manager** access is limited to assigned brands and projects
*   **Supervising Editor** and **Editor** receive project-specific access only

**3.1.4** The new team member's first login experience is customized based on their role, showing only accessible modules and features.

### 3.2 Permission Verification at Login

**3.2.1** When a team member logs in, the system queries their role from the users table and loads associated permissions.

*   **Agency Owner** loads complete permission matrix
*   **Admin** loads full permissions excluding system settings and billing
*   **Project Manager** loads project-specific permissions for assigned brands
*   **Supervising Editor** loads editorial permissions with collaboration capabilities
*   **Editor** loads basic content creation permissions

**3.2.2** The navigation menu dynamically renders showing only modules the user has permission to access based on their role.

*   **Agency Owner** sees all menu items including system settings
*   **Admin** sees all operational menus except system configuration
*   **Project Manager** sees project management and assigned brand modules
*   **Supervising Editor** sees editorial modules and team coordination features
*   **Editor** sees basic project and content creation modules only

**3.2.3** Dashboard widgets and quick actions are filtered to display only functionality available to the user's permission level.

**3.2.4** The system caches permissions in the session for performance, refreshing only when role changes occur.

### 3.3 Module Access Control

**3.3.1** When a user attempts to access any module, the system validates their permission before rendering the interface.

**3.3.2** If the user lacks view permission for a module, the system displays "You don't have permission to access this area" and redirects to dashboard.

**3.3.3** Within accessible modules, action buttons like Edit, Delete, and Create are shown or hidden based on specific role permissions.

*   **Agency Owner** sees all available actions
*   **Admin** sees administrative actions excluding system-level changes
*   **Project Manager** sees project-related actions for assigned projects
*   **Supervising Editor** sees editorial and collaboration actions
*   **Editor** sees basic content creation and editing actions

**3.3.4** API endpoints validate permissions server-side, preventing unauthorized actions even if UI restrictions are bypassed.

### 3.4 Project-Level Permissions

**3.4.1** Project Managers and Editors see only projects explicitly assigned to them through the project assignment system.

*   **Project Manager** can create new projects within assigned brands
*   **Supervising Editor** can view all assigned projects and collaborate across them
*   **Editor** can only view and edit content for specifically assigned projects

**3.4.2** Owners and Admins bypass project-level filtering, seeing all projects across all brands within the agency.

*   **Agency Owner** has unrestricted access to all projects
*   **Admin** can view and manage all projects but respects brand assignments

**3.4.3** When viewing project lists, the system applies WHERE clauses based on role to filter results appropriately.

**3.4.4** Project creation permissions determine whether users see the "Create New Project" button in project interfaces.

*   **Agency Owner & Admin** see create button for all brands
*   **Project Manager** sees create button only for assigned brands
*   **Supervising Editor & Editor** do not see project creation options

### 3.5 Brand-Based Access

**3.5.1** Users can only access data within brands they've been explicitly assigned during invitation or through role editing.

*   **Agency Owner** automatically has access to all brands
*   **Admin** typically assigned to all brands but can be restricted
*   **Project Manager** assigned to specific brands based on responsibilities
*   **Supervising Editor & Editor** assigned to brands where they work on projects

**3.5.2** Multi-brand users see a brand switcher in the interface, with permissions applying within each brand context.

**3.5.3** Cross-brand data access is prevented even for high-permission roles unless explicitly granted brand access.

**3.5.4** Brand filtering occurs at the database query level for security, not just UI hiding.

### 3.6 Financial Data Restrictions

**3.6.1** Financial modules including billing, invoicing, and revenue reports are restricted to Owner and Admin roles only.

*   **Agency Owner** has complete financial access including payments and refunds
*   **Admin** can view financial reports but cannot process transactions
*   **Project Manager** can view project-specific budgets only
*   **Supervising Editor & Editor** have no financial access

**3.6.2** Project Managers can view project-specific budgets and costs but cannot access agency-wide financial data.

**3.6.3** Editors have no access to any financial information, with these sections completely hidden from their interface.

**3.6.4** Payment processing and refund capabilities are limited to Owner role with Admin having view-only access.

### 3.7 Communication Permissions

**3.7.1** Client communication permissions determine who can send emails, messages, and notifications to clients.

*   **Agency Owner & Admin** can send agency-wide communications
*   **Project Manager** can communicate with all clients for their projects
*   **Supervising Editor** can communicate with clients on assigned projects
*   **Editor** can communicate with clients but with approval workflows

**3.7.2** All roles except Basic can communicate with clients, but only Owners and Admins can send agency-wide communications.

**3.7.3** Automated email permissions control who can create and modify email templates and automation workflows.

*   **Agency Owner** can create and manage all email templates
*   **Admin** can create templates but cannot modify Owner-created ones
*   **Project Manager & Supervising Editor** can create limited project-specific templates
*   **Editor** cannot create email templates

**3.7.4** Internal team communication is unrestricted, allowing all team members to collaborate via internal messaging.

### 3.8 Administrative Functions

**3.8.1** System settings, integrations, and configuration options are accessible only to the Owner role.

**3.8.2** Admins can manage team members and moderate content but cannot modify system-level configurations.

**3.8.3** Subscription management and billing controls are exclusive to the Owner to prevent unauthorized plan changes.

**3.8.4** API key generation and third-party integration setup require Owner permissions for security.

## **4\. Functional Logic**

### 4.1 Role Definition Structure

Each role is defined in the roles table with a unique identifier, name, description, and hierarchy level for permission inheritance.

**Agency Owner (Role ID: 1, Hierarchy: 6)**

*   Complete system administrator with unrestricted access
*   Can manage subscription, billing, and financial transactions
*   Has access to system settings, API keys, and integrations
*   Can create and assign all other roles including Admin
*   Only role that can process refunds and manage bank account details
*   Can create email signatures for all brands within the agency

**Admin (Role ID: 2, Hierarchy: 5)**

*   Administrative role with operational control but financial limitations
*   Can invite and manage all team members except Owner
*   Has full access to all projects and brands within the agency
*   Can view financial reports but cannot process payments
*   Cannot access system settings, API management, or subscription controls
*   Can moderate content and manage team workflows

**Project Manager (Role ID: 3, Hierarchy: 4)**

*   Project-focused leadership role with brand-specific permissions
*   Can create and manage projects within explicitly assigned brands
*   Views only projects they are assigned to, not agency-wide projects
*   Can assign team members (Editors) to their own projects
*   Has access to project budgets but not agency-wide financial data
*   Can communicate with clients related to their managed projects
*   Cannot invite new team members or change user roles

**Supervising Editor (Role ID: 4, Hierarchy: 3)**

*   Senior editorial role with enhanced collaboration capabilities
*   Can view all team member pipelines for coordination purposes
*   Has ability to create content and files in other users' projects
*   Can approve content created by junior editors before publishing
*   Has limited email template creation for project communications
*   Can change project statuses on assigned projects
*   Cannot access financial data or manage team member roles

**Editor (Role ID: 5, Hierarchy: 2)**

*   Basic content creation role with project-specific access
*   Can only view and edit projects explicitly assigned to them
*   Can change statuses on their own projects but requires approval for publishing
*   Can view and message primary employee assignees on projects
*   Has basic client communication capabilities for assigned projects
*   Cannot view team pipelines, financial data, or manage other users
*   Cannot create projects or assign other team members

The roles\_permissions junction table maps each role to specific permissions across all system modules and actions. Permissions are granular, defining view, create, edit, delete, and manage capabilities for each module independently.

Role hierarchy ensures that higher roles inherit all permissions of lower roles plus additional capabilities. The system prevents creation of custom roles in Phase 1, using only the predefined five roles for consistency.

### 4.2 Permission Inheritance Model

**Agency Owner Role:**

*   Inherits no permissions (top-level role)
*   Has unrestricted access to all system features
*   Serves as the super-admin for the agency
*   Can override any system restriction or limitation
*   Has emergency access override capabilities

**Admin Role:**

*   Inherits basic operational permissions
*   Adds team management capabilities for all roles except Owner
*   Includes financial viewing but excludes payment processing
*   Has content moderation and workflow management permissions
*   Cannot inherit system configuration or subscription management rights

**Project Manager Role:**

*   Inherits project viewing and editing permissions
*   Focuses on project-level permissions with limited agency-wide access
*   Adds team assignment capabilities for owned projects
*   Includes client communication for project-related matters
*   Inherits brand-specific access controls

**Supervising Editor Role:**

*   Inherits basic editorial permissions from Editor role
*   Adds approval and publishing capabilities
*   Includes cross-project collaboration permissions
*   Has enhanced editorial permissions including content approval
*   Inherits project status management capabilities

**Editor Role:**

*   Base editorial access for assigned projects without approval rights
*   Inherits basic content creation and editing permissions
*   Includes limited client communication capabilities
*   Has project-specific access with approval workflows required
*   Serves as foundation for other editorial roles

### 4.3 Dynamic Permission Checking

Every API endpoint includes middleware that validates the requesting user's permissions before processing:

*   **Agency Owner** bypasses most permission checks but actions are still logged
*   **Admin** undergoes full permission validation excluding financial transactions
*   **Project Manager** has permissions verified against project assignments and brand access
*   **Supervising Editor** permissions checked for project assignment and collaboration rights
*   **Editor** undergoes strict permission validation for all actions

Frontend components use permission directives to conditionally render UI elements based on user capabilities:

*   Role-based component rendering ensures appropriate interface display
*   Action buttons and menu items filtered by individual role permissions
*   Real-time permission updates reflect role changes without page refresh

Database queries automatically include role-based filtering to prevent unauthorized data access at the query level. Real-time permission updates propagate to active sessions when roles change without requiring re-login. Permission caching uses Redis with 5-minute TTL to balance performance with security freshness.

### 4.4 Project Assignment Logic

Project assignments create explicit relationships between users and projects in the user\_projects junction table:

**Agency Owner Project Access:**

*   Has implicit access to all projects without explicit assignment
*   Can view, edit, and manage any project across all brands
*   Can assign any team member to any project
*   Can create projects for any brand within the agency
*   Project assignments do not restrict Owner access

**Admin Project Access:**

*   Has implicit access to all projects similar to Owner
*   Can assign any non-Owner role to projects
*   Can create and manage projects across all brands
*   Can remove users from project assignments
*   Assignment permissions allow bulk project management

**Project Manager Assignment Logic:**

*   Can only be assigned to projects within brands they have access to
*   Can self-assign to projects within their managed brands
*   Can assign Supervising Editors and Editors to their projects
*   Cannot assign other Project Managers or higher roles
*   Can create new projects within assigned brands and auto-assign themselves

**Supervising Editor Assignment Logic:**

*   Must be explicitly assigned to projects by Admin, Owner, or Project Manager
*   Cannot self-assign to projects outside their current assignments
*   Can view projects they're assigned to plus related collaborative projects
*   Assignment allows cross-project content creation for collaboration
*   Cannot assign other users to projects

**Editor Assignment Logic:**

*   Must be explicitly assigned to projects by higher-level roles
*   Cannot self-assign to any projects
*   Can only access explicitly assigned projects
*   Assignment determines all project-level permissions and visibility
*   Cannot assign other users or modify project assignments

Assignment permissions determine whether users can self-assign projects or require assignment by administrators. Removing project assignments immediately revokes access, with changes reflecting in real-time for active users. Bulk assignment capabilities allow Admins to assign multiple projects to team members efficiently. Project ownership separate from role permissions provides additional granular control over project responsibilities.

### 4.5 Module-Specific Permissions

**CRM Module Permissions:**

*   **Agency Owner:** Complete CRM access including all leads, contacts, and customer data
*   **Admin:** Full CRM management with ability to assign leads and manage customer relationships
*   **Project Manager:** CRM access limited to contacts associated with assigned projects and brands
*   **Supervising Editor:** View-only access to CRM data for assigned projects
*   **Editor:** Basic contact viewing for project-related client communication only

**Project Management Permissions:**

*   **Agency Owner:** Unrestricted project creation, management, and deletion across all brands
*   **Admin:** Full project management capabilities excluding system-level project settings
*   **Project Manager:** Project creation and management within assigned brands, team assignment for owned projects
*   **Supervising Editor:** Project viewing and status updates for assigned projects, cross-project collaboration
*   **Editor:** Basic project viewing and content editing for assigned projects only

**Content Permissions:**

*   **Agency Owner:** Complete content management including publishing, archiving, and content strategy
*   **Admin:** Content oversight and moderation capabilities with approval workflows
*   **Project Manager:** Content creation and management for projects within their responsibility
*   **Supervising Editor:** Content creation, editing, and approval for assigned projects with cross-project collaboration
*   **Editor:** Basic content creation and editing with approval requirements for publishing

**Report Permissions:**

*   **Agency Owner:** Access to all analytics, financial reports, and performance metrics across all brands
*   **Admin:** Comprehensive reporting access excluding financial transaction details
*   **Project Manager:** Project-specific analytics and performance metrics for assigned projects
*   **Supervising Editor:** Editorial performance reports and content analytics for assigned projects
*   **Editor:** Basic project progress reports and personal performance metrics only

**Integration Permissions:**

*   **Agency Owner:** Complete integration setup, API key management, and third-party service configuration
*   **Admin:** Integration usage and monitoring but cannot modify configurations
*   **Project Manager:** Limited integration access for project-specific tools and services
*   **Supervising Editor:** Basic integration usage for editorial tools and content management
*   **Editor:** Read-only access to necessary integrations for content creation

### 4.6 Data Visibility Rules

Row-level security ensures users only see data they have explicit permission to access:

*   **Agency Owner:** No row-level restrictions, full data visibility
*   **Admin:** Brand-based row filtering but access to all projects and team data
*   **Project Manager:** Row filtering based on assigned brands and projects
*   **Supervising Editor:** Row filtering based on project assignments and collaboration rights
*   **Editor:** Strict row filtering limited to assigned projects and related content

Column-level permissions hide sensitive fields like financial data from unauthorized roles:

*   Financial columns visible only to Agency Owner and Admin (view-only)
*   Personal information columns restricted based on role hierarchy
*   System configuration data hidden from non-Owner roles
*   Sensitive client data filtered based on project assignments

Aggregate data in reports respects individual data permissions, excluding unauthorized records from calculations. Search functionality filters results based on permissions, never exposing unauthorized data in search results. Export capabilities respect permission boundaries, only including authorized data in downloaded files.

### 4.7 Permission Conflict Resolution

When users have multiple roles through different contexts, the highest permission level applies:

*   **Agency Owner** permissions always take precedence in conflict situations
*   **Admin** permissions override lower roles but not Owner restrictions
*   **Project Manager** permissions apply within assigned brands and projects
*   **Editor** permissions serve as baseline with other roles adding capabilities

Explicit denials override implicit allowances to ensure security restrictions are maintained. Brand-specific permissions take precedence over global role permissions for brand-isolated data. Temporary permission elevation for specific tasks reverts automatically after task completion. Permission conflicts are logged for audit and reviewed to improve permission model design.

### 4.8 Audit and Compliance

All permission checks are logged with user, action, resource, result, and timestamp for audit trails:

*   **Agency Owner** actions logged with highest priority for compliance oversight
*   **Admin** actions tracked for operational audit and team management review
*   **Project Manager** actions logged for project accountability and performance tracking
*   **Supervising Editor** actions recorded for editorial workflow and approval tracking
*   **Editor** actions monitored for content creation compliance and quality control

Failed permission attempts trigger security alerts after threshold breaches for potential breach detection. Compliance reports can demonstrate proper access control for regulatory requirements. Permission change history is maintained indefinitely for forensic analysis if needed. Regular permission audits identify and flag unusual permission patterns or potential security issues.

### 4.9 Performance Optimization

Permission matrices are precomputed and cached to avoid runtime calculation overhead:

*   **Agency Owner** permissions cached as "full\_access" token for maximum performance
*   **Admin** permissions cached with specific exclusions for financial and system operations
*   **Project Manager** permissions cached per brand with project assignment mapping
*   **Supervising Editor** permissions cached with project and collaboration context
*   **Editor** permissions cached with minimal access patterns for faster validation

Database indexes on permission-related columns ensure fast permission checking queries. Bulk permission operations use batch processing to handle large team updates efficiently. Permission inheritance is resolved at role assignment time, not runtime, for performance. Static permission definitions in Phase 1 eliminate the overhead of dynamic permission resolution.

## **5\. Field Details & Validations**

**Field Name**

**Field Type**

**Validation Rules**

**Required**

**Default Value**

**Role Restrictions**

Role ID

System Generated

Unique identifier

Yes

Auto-increment

Owner: All, Admin: 2-5, Others: None

Role Name

Enum

Predefined set only (Owner, Admin, Project Manager, Supervising Editor, Editor)

Yes

None

Assignment restricted by hierarchy

User Assignment

Foreign Key

Valid user\_id

Yes

None

Owner/Admin can assign all roles

Brand Assignment

Foreign Key

Valid brand\_id

Yes

None

Project Manager+ require explicit assignment

Permission Level

Integer

1-5 hierarchy (5=Owner, 1=Editor)

Yes

Based on role

Higher roles can assign lower levels

Module Access

Boolean Array

Per module flags

Yes

Role defaults

Inherited from role definition

Action Permissions

JSON

CRUD permissions

Yes

Role template

Granular permissions per module

Assignment Date

Timestamp

DateTime

Yes

Current time

System-generated audit field

Modified By

Foreign Key

Valid admin user\_id

Yes

Current user

Tracks permission changes

Is Active

Boolean

Active/Inactive

Yes

True

Can be deactivated without deletion

Project Assignments

Array

Valid project\_ids

No

Empty

Role-specific assignment logic

Brand Restrictions

Array

brand\_id restrictions

No

All brands (Owner)

Role-based brand access control

Expiration Date

DateTime

Optional role expiry

No

NULL

Temporary role assignments

## **6\. Success Message Handling**

**Operation**

**Success Message**

**Display Duration**

**Post-Success Action**

**Role Restrictions**

Role Assigned

"Role successfully assigned to \[user\]"

5 seconds

Update listing

Owner/Admin only

Permissions Applied

"Permissions updated successfully"

3 seconds

Refresh access

Role-based notifications

Access Granted

"Access granted to requested resource"

3 seconds

Load resource

All roles

Access Revoked

"Access removed successfully"

3 seconds

Redirect user

Owner/Admin only

Audit Logged

"Action logged for compliance"

2 seconds

Continue

All roles

Project Assigned

"User assigned to project successfully"

4 seconds

Update project view

PM+ roles

Brand Access Updated

"Brand access updated for user"

4 seconds

Refresh brand list

Owner/Admin only

Role Upgraded

"User role upgraded successfully"

5 seconds

Send notification

Owner/Admin only

Bulk Assignment

"Multiple users assigned successfully"

6 seconds

Update team listing

Admin+ roles

## **7\. Error Message Handling**

**Error Scenario**

**Error Message**

**Required User Action**

**System Response**

**Role Context**

Insufficient permissions

"You don't have permission to perform this action"

Contact admin

Log attempt

All roles

Invalid role assignment

"This role cannot be assigned to this user"

Select valid role

Block assignment

Owner/Admin

Module access denied

"You cannot access this module"

Request access

Redirect to dashboard

Project-specific roles

Permission conflict

"Permission settings conflict detected"

Review settings

Show conflicts

Admin+ roles

Role not found

"Selected role does not exist"

Refresh and retry

Reload roles

System error

Circular permission

"This would create a permission loop"

Adjust settings

Prevent save

Owner/Admin

Exceeded role limit

"Maximum number of admins reached"

Review team structure

Block creation

Owner only

Database error

"Failed to update permissions"

Retry operation

Rollback changes

System error

Cache sync failure

"Permissions may not reflect recent changes"

Refresh browser

Clear cache

All roles

Audit log failure

"Action completed but not logged"

Report to IT

Queue for retry

System error

Project access denied

"You cannot access this project"

Request assignment

Show available projects

PM/Editor roles

Brand restriction

"Access denied for this brand"

Contact administrator

Filter available options

All non-Owner roles

## **8\. Edge Cases**

**Scenario**

**Handling Approach**

**Expected Behavior**

**Role Impact**

User with no role

Assign Editor role

Minimal access

Safety fallback

Deleted role reference

Fallback to Editor

Maintain access

Prevents system lockout

Multiple role contexts

Highest permission wins

Maximum access

Role hierarchy respected

Permission during transition

Snapshot permissions

Consistent access

Prevents disruption

Cross-agency access attempt

Strict isolation

Block completely

All roles affected

Suspended user permissions

Revoke all access

Force logout

All roles

API token permissions

Match user role

Same restrictions

Token inherits user role

Mobile app permissions

Sync with web

Consistent access

Platform-agnostic

Offline permission checks

Cache last known

Allow cached only

Graceful degradation

Owner role deletion attempt

Block operation

Maintain Owner

System protection

Admin self-demotion

Require Owner approval

Prevent accidental loss

Owner oversight required

Project Manager brand removal

Reassign or demote

Maintain project access

Graceful role transition

Editor project unassignment

Remove all project access

Update immediately

Clean permission removal

Bulk role changes

Transaction rollback on failure

All-or-nothing

Prevents partial updates

Emergency access override

Owner bypass with logging

Temporary escalation

Audit trail maintained

Permission rollback needed

Restore from backup

Point-in-time recovery

System-level recovery

## **9\. Acceptance Criteria**

### Core Requirements

*   Role-based access control must be enforced at both UI and API levels for all five predefined roles
*   All five predefined roles (Agency Owner, Admin, Project Manager, Supervising Editor, Editor) must be available for assignment during team member invitation
*   Permission checks must occur in under 100ms for optimal user experience across all role types
*   Users must only see and access data within their permission boundaries as defined by their role
*   Role changes must take effect immediately for active user sessions without requiring re-login

### Security Requirements

*   The system must prevent privilege escalation through any method for all roles
*   Brand-based isolation must be maintained regardless of role level, with only Agency Owner having implicit all-brand access
*   Financial and sensitive data must be restricted to authorized roles (Agency Owner and Admin with view-only)
*   Agency Owner must be the only role capable of processing refunds and managing subscriptions
*   API key generation and system settings must remain exclusive to Agency Owner

### Audit and Compliance

*   Audit logs must capture all permission-related actions and access attempts for every role
*   Permission inheritance must work correctly through the role hierarchy (Owner > Admin > Project Manager > Supervising Editor > Editor)
*   Error messages must clearly indicate why access was denied with role-specific context
*   Database queries must automatically filter based on user permissions and role assignments

### Performance and Scalability

*   The permission system must scale to support hundreds of users per agency across all role types
*   Mobile and web applications must have synchronized permission enforcement for all roles
*   Permission caching must be optimized for each role type with appropriate TTL settings

### Role-Specific Criteria

*   **Agency Owner** must have unrestricted access to all system features including billing and system configuration
*   **Admin** must have full operational access but be restricted from financial transactions and system settings
*   **Project Manager** must only access assigned brands and projects with team assignment capabilities
*   **Supervising Editor** must have cross-project collaboration abilities while maintaining project assignment boundaries
*   **Editor** must have basic content creation access limited to explicitly assigned projects

### Phase 1 Constraints

*   Phase 1 must use global role definitions consistently across all agencies without customization options
*   Custom role creation must be blocked in Phase 1 with clear messaging about Phase 2 availability
*   Role hierarchy must be strictly enforced with no ability to bypass or modify the predefined structure

## **10\. Manual Test Cases**

**Test Cases Document:** [Test\_Cases\_Roles\_and\_Permissions.xlsx](https://claude.ai/chat/Test_Cases_Roles_and_Permissions.xlsx)

### Test Categories by Role

**Agency Owner Test Scenarios (30 tests):**

*   Complete system access validation
*   Financial transaction processing
*   System setting modifications
*   All-role team management capabilities
*   Subscription and billing management
*   API key generation and management

**Admin Role Test Scenarios (25 tests):**

*   Team management excluding Owner role
*   Financial viewing without transaction access
*   Project management across all brands
*   Content moderation capabilities
*   System setting access restrictions

**Project Manager Test Scenarios (22 tests):**

*   Brand-specific project creation
*   Team assignment to owned projects
*   Project budget viewing limitations
*   Client communication for managed projects
*   Cross-brand access restrictions

**Supervising Editor Test Scenarios (20 tests):**

*   Cross-project collaboration capabilities
*   Content approval workflows
*   Team pipeline visibility
*   Editorial template creation
*   Project assignment requirements

**Editor Role Test Scenarios (18 tests):**

*   Project-specific content creation
*   Assignment-based access validation
*   Client communication limitations
*   Approval workflow requirements
*   Basic project status updates

**Cross-Role Integration Tests (15 tests):**

*   Role hierarchy enforcement
*   Permission inheritance validation
*   Multi-role conflict resolution
*   Brand isolation maintenance
*   Emergency access scenarios

## **11\. Dependencies**

**Dependency Type**

**Description**

**Impact if Unavailable**

**Fallback Approach**

**Role Considerations**

Database - Roles Table

Stores role definitions for all five roles

Cannot assign roles

Use cached data

Affects all role assignments

Database - Permissions Table

Permission mappings for role hierarchy

Cannot check access

Deny by default

All roles lose proper access

Database - User\_Roles

User role assignments

Cannot identify role

Assume Editor

Safety fallback to lowest privilege

Cache Service (Redis)

Permission caching by role

Slower checks

Direct DB queries

Performance impact on all roles

Session Management

User context and role state

Cannot authenticate

Force re-login

All users must re-authenticate

Audit Log Service

Compliance tracking for all roles

No audit trail

Queue locally

Compliance impact for all actions

API Gateway

Request filtering by role

No API protection

Block all APIs

Security failure affects all roles

Frontend Framework

UI permission directives

No UI filtering

Hide all actions

Users see empty interfaces

Message Queue

Permission sync across sessions

Delayed updates

Direct updates

Role changes propagate slowly

Database Indexes

Query performance for role checks

Slow permission checks

Add indexes

Performance degradation

Brand Service

Brand context for role restrictions

No brand filtering

Block access

Non-Owner roles lose functionality

Project Service

Project assignments by role

Cannot filter projects

Show none

Project-based roles lose access

Email Service

Role-based notification system

Cannot send notifications

Queue for retry

Role change notifications fail

Billing Service

Financial access for Owner/Admin

Cannot process payments

Block financial ops

Owner/Admin lose billing capabilities

Integration Service

Third-party access by role

Cannot use integrations

Basic functionality

Feature restrictions across roles

## **12\. References**

**Permission Matrix Documentation:**

*   Complete Roles & Permissions Matrix: [Roles\_and\_Permissions\_Matrix\_Complete.xlsx](https://claude.ai/chat/Roles_and_Permissions_Matrix_Complete.xlsx)
*   Role-Specific Permission Details: [Role\_Permission\_Breakdown.xlsx](https://claude.ai/chat/Role_Permission_Breakdown.xlsx)
*   Cross-Module Access Patterns: [Module\_Access\_Matrix.xlsx](https://claude.ai/chat/Module_Access_Matrix.xlsx)

**Technical Documentation:**

*   API Permission Middleware: [API\_Permission\_Validation.md](https://claude.ai/chat/API_Permission_Validation.md)
*   Database Schema: [Role\_Database\_Schema.sql](https://claude.ai/chat/Role_Database_Schema.sql)
*   Frontend Permission Directives: [UI\_Permission\_Components.md](https://claude.ai/chat/UI_Permission_Components.md)
*   Caching Strategy: [Permission\_Caching\_Strategy.md](https://claude.ai/chat/Permission_Caching_Strategy.md)

**Security Documentation:**

*   Security Audit Requirements: [Security\_Audit\_Checklist.md](https://claude.ai/chat/Security_Audit_Checklist.md)
*   Penetration Testing Guidelines: [Permission\_Penetration\_Tests.md](https://claude.ai/chat/Permission_Penetration_Tests.md)
*   Compliance Requirements: [Regulatory\_Compliance\_Mapping.md](https://claude.ai/chat/Regulatory_Compliance_Mapping.md)

**Phase 2 Considerations:**

*   Agency-specific role customization framework
*   Custom role creation interface design
*   Permission template marketplace concept
*   Advanced permission delegation workflows
*   Dynamic role modification capabilities
*   Multi-agency role synchronization
*   Custom approval workflows by role
*   Role-based integration permissions

**Document Version:** 2.0  
**Last Updated:** December 2024  
**Next Review:** March 2025  
**Owner:** Team Management Development Team  
**Approved By:** Technical Architecture Committee