Advisor/client invite system

Overview

The advisor/client invite system enables financial advisors to invite their clients to the platform and manage their financial portfolios. This feature introduces a new relationship model where:

• Advisors can register with a specialized account type
• Advisors can create and prepare client spaces before client acceptance
• Advisors can invite multiple clients to the platform
• Clients get their own dedicated spaces that are linked to their advisor's subscription
• Advisors can access and manage their clients' financial data
• The application UI adapts contextually based on the user's role (advisor or client)

This document details the technical implementation of this feature, including database structure, authentication flows, and user interface components.

System architecture

Database schema

The advisor/client system builds on the existing space and subscription models with these key additions:

1. Space enhancement

   • Added is_advisor boolean flag to the space table to distinguish advisor spaces
   • Modified space creation logic in handle_new_profile function to set this flag based on signup type
   • Added space_for_client_email field to track prepared spaces that haven't been accepted yet

2. Advisor subscription items

   • New advisor_subscription_item table that creates a many-to-one relationship between client spaces and an advisor's subscription
   • This enables a single advisor subscription to cover multiple client spaces

3. Modified invite system

   • Added invite_type to track advisor-specific invites
   • Updated accept_invite function to handle different invitation types
   • Added support for prepared client spaces that exist before client acceptance

4. User spaces view

   • Provides a unified view of all spaces a user has access to
   • Includes context information (space_context) that determines the UI experience
   • Identifies relationships between advisors and clients
   • Supports the new prepared client space context

User roles and space contexts

The system introduces several new roles and contexts:

1. User roles

   • owner: The creator of a space (either individual or advisor)
   • advisor: An advisor managing a client's space
   • client: A client in their own space being managed by an advisor
   • member: A regular member in a space (from the existing system)

2. Space contexts (from the user_spaces view)

   • advisor_space: Advisor's own space where they manage their business
   • individual: Regular user's personal space
   • client_space: Client space that has an advisor relationship and has been accepted by the client
   • prepared_client_space: Client space created by an advisor but not yet accepted by the client
   • inactive: Space without an active subscription

The space context determines the user experience and is calculated based on role, subscription status, and the presence of advisor relationships.

Advisor workflow

Creating prepared client spaces

Advisors can now create and prepare client spaces before clients accept invitations:

1. Creating a prepared space

   • Advisor navigates to their dashboard
   • Clicks "Add client" button to open the prepare space dialog
   • Enters the client's email address and other required information
   • System validates the email (must be unique, properly formatted)

2. Setting up the space

   • System creates a new client space with space_for_client_email set to the provided email
   • This space has a context of prepared_client_space
   • The space is linked to the advisor's subscription via an advisor_subscription_item
   • The space appears in the advisor's dashboard immediately

3. Working in the prepared space

   • Advisor can immediately access and start working in the prepared space
   • They can configure portfolios, add assets, and set up the space for the client
   • All data entered is preserved for when the client eventually accepts the invitation

Inviting clients

Advisors can invite clients to join their prepared spaces:

1. Inviting to existing prepared space

   • When creating a prepared space, an invitation is automatically created
   • The system associates the invitation with the prepared space via the client email
   • Email is sent to the client with a signup/acceptance link

2. Creating the invitation

   • System creates a record in group_invite table with invite_type set to "advisor_client"
   • The invitation includes a reference to the prepared space

Managing client spaces

Advisors can now:

1. View both prepared client spaces and active client spaces in the advisor dashboard
2. Switch between their own space, prepared client spaces, and active client spaces
3. Begin managing financial data in prepared spaces before client acceptance
4. See which spaces are prepared and which are active based on visual indicators

The advisor dashboard is rendered when:

• The user has an advisor space (where is_advisor is true)
• The user's selected space is their advisor space
• The user has client spaces and/or prepared client spaces linked through advisor_subscription_item

// Logic determining when to show advisor dashboard (simplified)
function shouldShowAdvisorDashboard() {
  return (
    (profile.selectedSpaceId === null ||
      userSpaces.find((space) => space.spaceId === profile.selectedSpaceId)
        ?.spaceContext === "advisor_space") &&
    userSpaces[0].spaceContext === "advisor_space"
  );
}

Client workflow

Accepting invitations

When a client receives an invitation to a prepared space, they follow these steps:

1. Accessing the invitation

   • Client clicks the link in the invitation email
   • System validates the invite status
   • The invite type is captured and passed to the signup flow

2. Registration flow

   • For new users: Client completes the signup form
   • The system stores both invite_id and invite_type in the user's metadata
   • For existing users: Client logs in to their account

3. Space assignment

   • The system identifies the prepared space associated with the client's email
   • The prepared space is converted to an active client space (client_space context)
   • Client is added as role client to their space
   • The prepared data remains intact and available to the client immediately

Using client space

Once the invitation is accepted:

1. Client has access to their own financial dashboard with all the data prepared by their advisor
2. Client can see their advisor has access to their space
3. All activities in the client space are visible to both client and advisor

Technical implementation details

User spaces view

The user_spaces view has been enhanced to support prepared client spaces by distinguishing between regular client spaces and prepared client spaces based on whether the space_for_client_email field is populated.

The space context determines the appropriate UI to display and is calculated based on:

• The user's role in the space
• The subscription status and relationship
• Whether the space has been accepted by a client (via the space_for_client_email field)

Accept invite function

The accept invite process has been updated to handle prepared spaces, checking if there's an existing prepared space for the client's email before creating a new one. When a prepared space is found, it's converted to a regular client space instead of creating a new one.

Signup form enhancements

The signup form has been enhanced to properly handle redirects for prepared spaces:

// Simplified example of the updated useEffect in SignUpForm component
useEffect(() => {
  if (form.formState.isSubmitSuccessful) {
    if (state.redirect && state.reauthenticate) {
      reauthenticate()
        .then(() => {
          // Success - we're authenticated
          router.push(state.redirect as string);
        })
        .catch(() => {
          toast.error(t("SignUp.Form.reauthenticationError"));
          // Reset the ref so we can try again if needed
          hasRedirected.current = false;
        });
    } else if (state.redirect) {
      // Direct redirect without reauthentication
      router.push(state.redirect);
    }
  }
}, [state.redirect, state.reauthenticate, form, router, t]);

This ensures that:

1. Redirects work properly whether reauthentication is required or not
2. Users are always directed to the appropriate space after signup
3. The flow works correctly for both prepared spaces and regular invitations

User interface components

Advisor dashboard

The advisor dashboard has been enhanced to provide a unified view of all client spaces:

1. Shows both active client spaces and prepared client spaces in a unified grid
2. Visually distinguishes between active and prepared spaces
3. Provides a way to create new prepared spaces
4. Allows switching between all space types

Prepare space dialog

The new PrepareSpaceDialog replaces the previous AddClientDialog:

1. Collects client email and optionally other information
2. Validates input for correctness
3. Creates a prepared space immediately
4. Sends an invitation to the client
5. Returns the user to the dashboard where the new prepared space is visible

Client space and prepared space components

The system includes specialized components for different space types:

1. AdvisorClientSpace component

   • Displays active client spaces with client name and email
   • Provides visual indicators of the space status
   • Handles space switching when clicked

2. AdvisorPreparedSpace component

   • Displays prepared client spaces with space name and client email
   • Uses distinct visual styling to indicate prepared status
   • Handles space switching when clicked

These components ensure that advisors can easily distinguish between different space types while maintaining a consistent interface for interaction.

Client space navigation

When an advisor accesses any client space (prepared or active):

1. The UI reflects the specific type of space they are viewing
2. They have the ability to switch back to their advisor space
3. They can perform actions based on the space context

Best practices and considerations

Security

1. Invitations are validated through secure tokens
2. Client data is protected by row-level security policies
3. Role-based access controls ensure appropriate permissions
4. Prepared spaces maintain proper ownership until client acceptance

Subscription management

1. Advisor subscriptions are billed based on the number of client spaces, including prepared spaces
2. Subscription items maintain the relationship between spaces
3. Stripe integration handles proper billing

User experience

1. The application adapts its UI based on space context
2. Advisors have clear indicators when working in different space types
3. Clients see appropriate information about their advisor relationship
4. Prepared spaces allow advisors to set up client environments in advance

Conclusion

The enhanced advisor/client system with prepared spaces creates a powerful relationship model that enables financial advisors to start managing client portfolios immediately, without waiting for client acceptance. Advisors can now:

1. Create dedicated client spaces in advance
2. Configure and populate these spaces with relevant financial data
3. Send invitations to clients to join their prepared spaces
4. Manage both prepared and active client spaces from a unified dashboard

This implementation extends the existing database structures while adding specialized components to handle the unique requirements of prepared spaces. The result is a more efficient workflow for advisors and a better experience for clients, who gain access to fully configured spaces upon acceptance.