Invitation

Overview

The Invitation domain in comby handles the process of inviting users to join an organization or Tenant. It supports the lifecycle of an invitation, from creation and sending to acceptance or declination. The Invitation aggregate is at the core of this domain, providing the structure for managing invitations, tracking their state, and handling related domain events.

Concept

What is an Invitation?

An Invitation is a secure, token-based mechanism to invite users to join a tenant or workspace. When accepted, the invitation automatically creates an identity for the user with pre-configured group memberships.

Key Characteristics:

Token-Based Security: Each invitation has a unique, random token
State-Driven Lifecycle: Tracks invitation states (created, sent, accepted, declined)
Dual-Level Support: Tenant-level and workspace-level invitations
Pre-Configured Access: Specify groups during invitation creation
Email-Linked: Invitations are tied to specific email addresses

Invitation Lifecycle:
Created → Sent → Accepted/Declined
   ↓         ↓         ↓
  Token   Email    Identity Created

Architecture

Hierarchy

System
└── Tenant
    ├── Invitations (Tenant-Level)
    │   ├── Token
    │   ├── Email
    │   ├── GroupUuids (Tenant groups)
    │   └── State
    └── Workspaces
        └── Invitations (Workspace-Level)
            ├── Token
            ├── Email
            ├── GroupUuids (Tenant groups)
            ├── WorkspaceGroupUuids (Workspace groups)
            └── State

Invitation is connected to:

Tenant: Each invitation belongs to a tenant
Workspace: Invitations can be workspace-specific
Identity: Creator and target identities
Account: Accepting user's account
Group: Tenant-level and workspace-level groups

Domain Model

An Invitation can belong to only one Tenant. However, a user can be invited to multiple Tenants. This design enables a user to be associated with multiple Tenants through separate invitations.

Invitation States

State	Description
`created`	Invitation created but not yet sent
`sent`	Invitation sent to recipient (email)
`accepted`	User accepted the invitation
`declined`	User declined the invitation

Invitation Types

1. Tenant-Level Invitation

Invites a user to join a tenant with specific tenant-level groups.

Flow:

1. Create invitation with tenant groups
2. Send invitation (email sent)
3. User accepts → Identity created with tenant groups

2. Workspace-Level Invitation

Invites a user to join both a tenant AND a specific workspace.

Flow:

1. Create invitation with workspace context
2. Specify both tenant groups AND workspace groups
3. Send invitation
4. User accepts → Identity created + added to workspace

Structure

The Invitation aggregate consists of the following elements:

References:

GroupUuids: A list of group UUIDs to which the invited account will be added upon accepting the invitation.
IdentityUuid: The UUID of the identity that created the invitation.
AccountUuid: The UUID of the account that accepts the invitation.

Value Objects:

Token: A unique token associated with the invitation, typically used for verification or authentication.
Email: The email address of the invitee.
State: Tracks the current state of the invitation, such as created, sent, accepted, or declined.

The domain defines several states to represent the lifecycle of an invitation:

created: The invitation has been created but not yet sent.
sent: The invitation has been sent to the invitee.
accepted: The invitee has accepted the invitation, and the associated account has been added to the relevant groups.
declined: The invitee has declined the invitation.

These states enable precise tracking of invitation progress and ensure consistent processing across the system.

Use Cases

1. Inviting New Team Member

Scenario: Manager invites new developer to join team
1. Manager creates invitation with "Developers" group
2. System generates unique token and sends email
3. New user receives email with invitation link
4. User clicks link, creates account (if needed)
5. User accepts invitation → Identity created with Developers group

2. Workspace Collaboration

Scenario: Project lead invites consultant to specific workspace
1. Lead creates workspace-level invitation
   - Tenant groups: ["Members"]
   - Workspace groups: ["Project Consultants"]
2. Consultant accepts invitation
3. Consultant gets:
   - Identity in tenant with Members permissions
   - Workspace membership with Consultant permissions

3. Bulk Invitations

Scenario: Onboarding multiple users at once
For each user email:
1. Create invitation with common groups
2. Send invitations (batch email)
3. Track acceptance status
4. Remind users who haven't accepted

4. Invitation Expiry & Resending

Scenario: User didn't receive or lost invitation
1. Admin finds old invitation
2. Admin resends invitation (same token)
3. User receives new email with same link
4. User accepts invitation as normal

Features

Tenant-level and workspace-level invitations
Secure token-based authentication
Pre-configured group assignments
Email-linked invitations
State tracking (created, sent, accepted, declined)
Manual send trigger
Public accept/decline endpoints
Token-based invitation lookup
Custom attributes support

Best Practices

Invitation Creation

Always specify at least one group (tenant or workspace)
Use valid email addresses for invitations
Set appropriate groups based on user role
Include workspace context when inviting to specific projects

Email Handling

Implement email sending in your application
Include clear invitation instructions in email
Provide direct links with token embedded
Set reasonable email templates

Token Security

Tokens are automatically generated (12 characters)
Never expose tokens in logs
Tokens are single-use (invitation can only be accepted once)
Validate tokens before accepting invitations

State Management

Check invitation state before sending
Don't accept already-accepted invitations
Delete declined invitations if no longer needed
Track sent invitations for follow-up

Troubleshooting

"Invitation token does not match"

Cause: Token provided doesn't match the invitation's stored token.

Solution: Ensure the correct token is used. Retrieve invitation by token first:

qry := &query.InvitationQueryGetByToken{Token: "provided-token"}

Group validation fails during creation

Cause: Specified group UUIDs don't exist in the tenant/workspace.

Solution:

Verify tenant groups exist in the tenant
Verify workspace groups exist in the workspace
Ensure groups are created before creating invitation

Invitation not sending email

Cause: Email sending is not implemented or configured.

Solution: Implement a reactor that listens to InvitationSentEvent:

// reactor/send_email.go
func (r *Reactor) OnInvitationSent(evt InvitationSentEvent) {
    // Send email with invitation link
    sendEmail(evt.Email, generateInvitationLink(evt.Token))
}

User can't accept invitation

Check:

Is the invitation state "sent"?
Is the token correct?
Does the user have a valid account?
Has the invitation already been accepted?

Identity not created after acceptance

Cause: Invitation acceptance didn't trigger identity creation.

Solution: Implement a reactor that listens to InvitationAcceptedEvent:

func (r *Reactor) OnInvitationAccepted(evt InvitationAcceptedEvent) {
    // Create identity with invitation's groups
    cmd := &identity.IdentityCommandCreate{
        IdentityUuid: evt.TargetIdentityUuid,
        AccountUuid:  evt.AccountUuid,
        GroupUuids:   evt.GroupUuids,
    }

    // Add to workspace if workspace invitation
    if len(evt.WorkspaceUuid) > 0 {
        // Add workspace membership
    }
}

Event-Driven Automation

Reactors

The Invitation domain uses reactors for automation:

Auto-Send Email on Creation

// Reactor listens to InvitationCreatedEvent
func (r *Reactor) OnInvitationCreated(evt InvitationCreatedEvent) {
    // Automatically send invitation email
    sendInvitationCommand := &command.InvitationCommandSend{
        InvitationUuid: evt.InvitationUuid,
    }
}

Create Identity on Acceptance

// Reactor listens to InvitationAcceptedEvent
func (r *Reactor) OnInvitationAccepted(evt InvitationAcceptedEvent) {
    // Create identity with invitation's configuration
    createIdentityCommand := &identity.IdentityCommandCreate{
        IdentityUuid: evt.TargetIdentityUuid,
        AccountUuid:  evt.AccountUuid,
        GroupUuids:   evt.GroupUuids,
    }

    // If workspace invitation, add to workspace
    if len(evt.WorkspaceUuid) > 0 {
        addMemberCommand := &workspace.WorkspaceCommandAddMember{
            WorkspaceUuid: evt.WorkspaceUuid,
            IdentityUuid:  evt.TargetIdentityUuid,
            GroupUuids:    evt.WorkspaceGroupUuids,
        }
    }
}

Integration with Other Domains

Identity Domain

When invitation is accepted:

// Create identity with invitation's groups
cmd := &identity.IdentityCommandCreate{
    IdentityUuid: invitation.TargetIdentityUuid,
    AccountUuid:  invitation.AccountUuid,
    GroupUuids:   invitation.GroupUuids,
}

Workspace Domain

For workspace invitations:

// Add member to workspace with workspace groups
cmd := &workspace.WorkspaceCommandAddMember{
    WorkspaceUuid: invitation.WorkspaceUuid,
    IdentityUuid:  invitation.TargetIdentityUuid,
    GroupUuids:    invitation.WorkspaceGroupUuids,
}

Account Domain

Integration with registration:

// During account registration, check for invitations
invitations := findInvitationsByEmail(registeredEmail)
for _, invitation := range invitations {
    // Auto-accept or prompt user to accept
}

Group Domain

Invitations reference groups:

Validate groups exist before creating invitation
Groups must exist in correct context (tenant/workspace)

Security Considerations

Token Generation

Tokens are randomly generated (12 characters)
Cryptographically secure random generation
Tokens are unique per invitation
Never reuse tokens

Email Validation

Always validate email format
Check for existing identities with same email
Prevent duplicate invitations to same email

Authorization

Only authorized users can create invitations
Workspace invitations require workspace membership
Accept/Decline endpoints are public (token-based security)

State Transitions

Valid Transitions:
- created → sent
- sent → accepted
- sent → declined

Invalid Transitions:
- accepted → sent (can't resend accepted invitation)
- declined → accepted (can't accept declined invitation)

Token Format

Invitations use a 12-character alphanumeric token:

Example: abc123xyz789

Properties:

Length: 12 characters
Character set: a-zA-Z0-9
Collision resistance: Very high (62^12 combinations)
Human-readable: Can be typed if needed