Use Case 001: Trial User Self-Registration and Access

Overview

Description

This use case describes the end-to-end process of a prospective customer self-registering for a trial account, receiving access credentials, and beginning to use Riptide applications. The system automatically provisions trial access, tracks trial duration, and manages the trial lifecycle without requiring manual intervention from administrators.

Actors

Preconditions

1. Application Manager is running and accessible
2. Email service (SMTP or AWS SES) is configured and operational
3. At least one Riptide application is registered and configured for trial access
4. Trial default duration is configured (default: 30 days)
5. Email verification is enabled (configurable)

Postconditions

Success Postconditions

1. New trial user record created in Identity database
2. Trial access granted to specified application(s)
3. Login token and API token generated for the user
4. Welcome email sent with credentials and access instructions
5. Trial expiration date calculated and stored
6. User can authenticate and access trial applications
7. Activity logged in audit trail

Failure Postconditions

1. No user record created if validation fails
2. Error message logged and returned to user
3. Partial data rolled back if transaction fails

Triggers

• User visits trial registration page
• User submits completed registration form
• API client calls /api/v1/trial-users POST endpoint

Basic Flow (Happy Path)

Detailed Steps

1. User Initiates Registration

   • User navigates to /trial/register or equivalent endpoint
   • System displays registration form with required fields

2. User Provides Information

   • Full Name (required)
   • Email Address (required, must be valid format)
   • Company Name (optional)
   • Phone Number (optional)
   • Industry/Use Case (optional)
   • Requested Application(s) (default: all trial-enabled apps)

3. System Validates Input

   • Check all required fields are present
   • Validate email format using regex
   • Verify email is not already registered (uniqueness check)
   • Validate trial duration if customized
   • Check requested applications exist and support trials

4. System Creates Trial User

   • Generate unique user ID (GUID)
   • Hash password if provided (or generate secure token)
   • Generate login token (32-character alphanumeric)
   • Generate API token (64-character alphanumeric)
   • Calculate expiration date: TrialStartDate + TrialDurationDays
   • Set IsActive = true
   • Set EmailVerified = false (if verification required)
   • Store creation timestamp

5. System Grants Application Access

   • For each requested application:
     • Create TrialUserApplication record
     • Link trial user ID to application ID
     • Set GrantedAt timestamp
     • Set ExpiresAt to trial expiration date

6. System Sends Welcome Email

   • Compose email with:
     • Welcome message and trial details
     • Login token and API token
     • Direct links to applications
     • Trial duration and expiration date
     • Support contact information
     • Getting started resources
   • Send via configured email provider
   • Log email delivery attempt

7. System Returns Success Response

   • Return 201 Created status
   • Include user details in response body
   • Provide next steps for user

8. User Receives Credentials

   • User checks email inbox
   • User reviews welcome message and credentials
   • User bookmarks or saves credentials securely

9. User Logs In

   • User navigates to application login page
   • User enters login token
   • System validates token and creates session
   • User is redirected to application dashboard

10. User Accesses Trial Application

    • User attempts to use trial application
    • Application validates session with Application Manager
    • User is granted access based on trial status
    • Usage is tracked for analytics

Alternative Flows

Alt Flow 1: Email Already Exists

Steps:

1. System detects email already exists during validation (step 3)
2. System checks status of existing user record
3. If existing trial is expired:
   • Return 409 Conflict with message: "A previous trial for this email has expired. Contact support to extend or upgrade."
   • Log attempt in audit trail
4. If existing trial is active:
   • Return 409 Conflict with message: "An active trial already exists for this email. Please login or reset your password."
   • Optionally resend credentials email
5. If pending email verification:
   • Return 409 Conflict with message: "Registration pending. Please check your email for verification link."
   • Optionally resend verification email

Alt Flow 2: Email Verification Required

Steps:

1. After user creation (step 4), check if email verification is required
2. If required:
   • Set EmailVerified = false
   • Generate verification token (GUID, expires in 24 hours)
   • Send verification email with link instead of credentials
3. User receives verification email
4. User clicks verification link
5. System validates token and marks email as verified
6. System sends welcome email with credentials (step 6)
7. User can now proceed with login (step 9)

Alt Flow 3: Invalid Input Data

Steps:

1. Validation fails during step 3
2. System identifies specific validation error
3. System returns 400 Bad Request with descriptive error message
4. System includes field-level errors in response body
5. Web UI displays validation errors near affected fields
6. User corrects errors and resubmits form
7. Process continues from step 3

Alt Flow 4: Email Delivery Failure

Steps:

1. User successfully created (step 4 completed)
2. Email service fails during step 6 (network issue, invalid configuration, rate limit)
3. System logs email delivery error
4. System marks user record with EmailSentAt = null or EmailFailedAt = timestamp
5. System returns 201 Created to web UI (user was created successfully)
6. System displays warning: "Account created but email delivery failed. Contact support for credentials."
7. Administrator is notified of email failure
8. Administrator can:
   • Manually resend email via admin panel
   • Provide credentials to user through alternative channel
   • Investigate email service configuration

Alt Flow 5: Database Transaction Failure

Steps:

1. User creation begins (step 4)
2. Database connection lost or constraint violation occurs
3. System catches database exception
4. System rolls back partial transaction (no user record created)
5. System logs detailed error information
6. System returns 500 Internal Server Error
7. System displays generic error message: "Registration failed. Please try again."
8. User can retry registration
9. Administrator is alerted to investigate database issue

Business Rules

Data Requirements

User Type Hierarchy

The Application Manager uses an inheritance-based user model:

Base Class: User (abstract)

• Contains common fields for all user types
• Never instantiated directly

Derived Types:

1. TrialUser : User - Self-service trial users with time-limited access (see below)
2. ApplicationUser : User - Admin-provisioned users with permanent access (see UC-015)
3. Additional types can be added as needed (e.g., EnterpriseUser, PartnerUser)

User Type Comparison

Base User Properties (Inherited by All User Types)

{
  "Id": "uuid-v4",
  "Email": "string (required, unique, valid format)",
  "FullName": "string (required, 2-100 chars)",
  "TenantId": "string (for multi-tenant isolation)",
  "IsActive": "boolean (default: true)",
  "IsAdmin": "boolean (default: false)",
  "CreatedAt": "datetime (UTC)",
  "CreatedBy": "string (user ID or 'System')",
  "UpdatedAt": "datetime (UTC, nullable)",
  "LastLoginAt": "datetime (UTC, nullable)",
  "LastAccessedAt": "datetime (UTC, nullable)",
  "TotalLoginCount": "integer (default: 0)",
  "IpAddress": "string (nullable, last known IP)"
}

TrialUser-Specific Properties (extends User)

{
  "JobTitle": "string (optional, max 100 chars)",
  "CompanyName": "string (optional, max 200 chars)",
  "CompanySize": "enum (Solo, Small, Medium, Large, Enterprise)",
  "Industry": "string (optional, max 100 chars)",
  "LoginToken": "string (64 chars, hex, for passwordless auth)",
  "ApiToken": "string (64 chars, hex, for API access)",
  "Trials": "ICollection<ApplicationTrial> (navigation property)"
}

Complete TrialUser Record (Base + Specific)

For reference, a complete trial user record includes all base properties plus trial-specific ones:

{
  "_comment": "Base User properties",
  "Id": "uuid-v4",
  "Email": "string (required, unique, valid format)",
  "FullName": "string (required, 2-100 chars)",
  "TenantId": "string",
  "IsActive": "boolean (default: true)",
  "IsAdmin": "boolean (default: false)",
  "CreatedAt": "datetime (UTC)",
  "CreatedBy": "string",
  "UpdatedAt": "datetime (UTC, nullable)",
  "LastLoginAt": "datetime (UTC, nullable)",
  "LastAccessedAt": "datetime (UTC, nullable)",
  "TotalLoginCount": "integer (default: 0)",
  "IpAddress": "string (nullable)",
  
  "_comment": "TrialUser-specific properties",
  "JobTitle": "string (optional, max 100 chars)",
  "CompanyName": "string (optional, max 200 chars)",
  "CompanySize": "enum (Solo, Small, Medium, Large, Enterprise)",
  "Industry": "string (optional, max 100 chars)",
  "LoginToken": "string (64 chars, hex)",
  "ApiToken": "string (64 chars, hex)"
}

ApplicationUser-Specific Properties (extends User)

See UC-015: Application User Provisioning for complete ApplicationUser documentation.

{
  "Username": "string (required, unique, for login)",
  "AuthMethod": "enum (Password, SSO)",
  "PasswordHash": "string (BCrypt, nullable if SSO)",
  "MustChangePassword": "boolean (default: true for new users)",
  "ExternalUserId": "string (nullable, for SSO users)",
  "IdentityProvider": "string (nullable, e.g., 'AzureEntra')",
  "PasswordChangedAt": "datetime (UTC, nullable)",
  "PasswordExpiresAt": "datetime (UTC, nullable)",
  "PasswordChangeCount": "integer (default: 0)",
  "FailedLoginAttempts": "integer (default: 0)",
  "LockedOutUntil": "datetime (UTC, nullable)",
  "ApplicationAccess": "ICollection<ApplicationAccess> (navigation)",
  "UserRoles": "ICollection<UserRole> (navigation)"
}

Key Differences from TrialUser:

• Permanent access (no expiration)
• Username/password or SSO authentication (no tokens)
• Role-based access control (RBAC)
• Password policies and account lockout
• Created by AdminUser, not self-service

ApplicationTrial Entity

Represents a trial user's access to a specific application with time-limited access and provisioning details.

{
  "Id": "uuid-v4",
  "TrialUserId": "uuid-v4 (foreign key to TrialUser)",
  "ApplicationId": "uuid-v4 (foreign key to Application)",
  "TenantId": "uuid-v4 (isolated tenant for this trial)",
  "Status": "enum (Active, Expired, Purged)",
  "CreatedAt": "datetime (UTC)",
  "StartedAt": "datetime (UTC)",
  "ExpiresAt": "datetime (UTC, nullable for admin trials)",
  "LastAccessedAt": "datetime (UTC, nullable)",
  "LoginCount": "integer (access count for this trial)",
  "TenantProvisioned": "boolean",
  "ProvisioningSucceeded": "boolean",
  "ProvisioningError": "string (nullable)",
  "IsAdminTrial": "boolean (never expires)",
  "HasBeenExtended": "boolean",
  "ExtensionCount": "integer",
  "LastExtendedAt": "datetime (UTC, nullable)",
  "AssignedRoles": "List<string> (role names for RBAC)",
  "LoginToken": "string (inherited from TrialUser)",
  "ApiToken": "string (inherited from TrialUser)"
}

TeamMember Entity (Join Table)

Links a TrialUser to an ApplicationTrial as a team member. When a trial owner invites someone:

1. If invitee email not registered → Create new TrialUser via self-registration
2. If invitee already registered → Use existing TrialUser
3. Create TeamMember record linking TrialUser to ApplicationTrial

Important: Invited users authenticate as TrialUser (using their own tokens). TeamMember only tracks the membership relationship, not authentication.

{
  "Id": "uuid-v4",
  "ApplicationTrialId": "uuid-v4 (which trial)",
  "TrialUserId": "uuid-v4 (which TrialUser is the member)",
  "InvitedByUserId": "uuid-v4 (which TrialUser sent invitation)",
  "AssignedRoles": "List<string> (trial-specific roles)",
  "IsActive": "boolean",
  "InvitedAt": "datetime (UTC)",
  "AcceptedAt": "datetime (UTC, nullable)",
  "RemovedAt": "datetime (UTC, nullable)",
  "RemovedByUserId": "uuid-v4 (nullable)"
}

Navigation Properties:

• ApplicationTrial → The trial they're part of
• TrialUser → The user who is the member
• InvitedBy (TrialUser) → The user who sent the invitation
• RemovedBy (TrialUser) → The user who removed them (if applicable)

Note: TeamMember is a join table linking TrialUser to ApplicationTrial. See the Domain layer entity definitions for complete details.

Email Templates

• Welcome Email (no verification):

  • Subject: "Welcome to Your Riptide Trial"
  • Body includes: tokens, links, expiration date, getting started guide

• Verification Email (with verification):

  • Subject: "Verify Your Riptide Trial Account"
  • Body includes: verification link, expiration notice (24 hours)

• Welcome Email (post-verification):

  • Subject: "Your Riptide Trial is Ready"
  • Body includes: tokens, links, expiration date, getting started guide

User Interface

Registration Form

┌─────────────────────────────────────────────────────┐
│  Sign Up for Riptide Trial                         │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Full Name *                                        │
│  ┌─────────────────────────────────────────────┐   │
│  │ John Doe                                    │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  Email Address *                                    │
│  ┌─────────────────────────────────────────────┐   │
│  │ john.doe@example.com                        │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  Company Name                                       │
│  ┌─────────────────────────────────────────────┐   │
│  │ Acme Corporation                            │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  Phone Number                                       │
│  ┌─────────────────────────────────────────────┐   │
│  │ +1-555-0123                                 │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  Industry/Use Case                                  │
│  ┌─────────────────────────────────────────────┐   │
│  │ Financial Services                          │   │
│  └─────────────────────────────────────────────┘   │
│                                                     │
│  Applications to Access                             │
│  ☑ Fee Manager                                      │
│  ☑ Value Manager                                    │
│  ☐ Workflow Designer                                │
│                                                     │
│  ┌─────────────────────┐                           │
│  │  Create Trial Account │  [Cancel]               │
│  └─────────────────────┘                           │
│                                                     │
│  * Required fields                                  │
└─────────────────────────────────────────────────────┘

Success Screen

┌─────────────────────────────────────────────────────┐
│  ✅ Trial Account Created Successfully!             │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                     │
│  Your trial account has been created and an email  │
│  with access credentials has been sent to:         │
│                                                     │
│     john.doe@example.com                           │
│                                                     │
│  📧 Check your email for:                           │
│     • Login Token                                   │
│     • API Token                                     │
│     • Direct links to applications                  │
│     • Getting started guide                         │
│                                                     │
│  ⏰ Trial Duration: 30 days                         │
│  📅 Expires: February 29, 2026                      │
│                                                     │
│  ┌─────────────────────┐                           │
│  │   Go to Login        │                          │
│  └─────────────────────┘                           │
│                                                     │
│  Didn't receive the email?                          │
│  [Resend Email]                                     │
└─────────────────────────────────────────────────────┘

API Endpoints

Create Trial User

Endpoint: POST /api/v1/trial-users

Authentication: None (public endpoint) or API Key

Request Body:

{
  "fullName": "John Doe",
  "email": "john.doe@example.com",
  "companyName": "Acme Corporation",
  "phoneNumber": "+1-555-0123",
  "industry": "Financial Services",
  "trialDurationDays": 30,
  "applicationIds": [
    "app-id-fee-manager",
    "app-id-value-manager"
  ],
  "sendEmail": true
}

Success Response: 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "fullName": "John Doe",
  "email": "john.doe@example.com",
  "companyName": "Acme Corporation",
  "trialStartDate": "2026-01-30T10:30:00Z",
  "trialExpirationDate": "2026-03-01T10:30:00Z",
  "isActive": true,
  "emailVerified": false,
  "applicationsGranted": [
    {
      "applicationId": "app-id-fee-manager",
      "applicationName": "Fee Manager",
      "expiresAt": "2026-03-01T10:30:00Z"
    },
    {
      "applicationId": "app-id-value-manager",
      "applicationName": "Value Manager",
      "expiresAt": "2026-03-01T10:30:00Z"
    }
  ],
  "message": "Trial account created successfully. Check email for credentials."
}

Error Responses:

400 Bad Request - Validation error

{
  "error": "ValidationError",
  "message": "One or more validation errors occurred",
  "errors": {
    "email": ["Email address is already registered"],
    "fullName": ["Full name is required"]
  }
}

409 Conflict - Duplicate email

{
  "error": "DuplicateEmail",
  "message": "An active trial already exists for this email address",
  "existingTrialExpiresAt": "2026-02-15T10:30:00Z"
}

500 Internal Server Error - System error

{
  "error": "InternalError",
  "message": "An error occurred while creating the trial account. Please try again.",
  "requestId": "req-123456"
}

Performance Requirements

Security Considerations

Token Security

• Login tokens and API tokens must be cryptographically random
• Tokens should be generated using System.Security.Cryptography.RandomNumberGenerator
• Tokens must be unique across all users
• Tokens should never be logged in plain text
• Tokens are transmitted only via secure channels (HTTPS, encrypted email)

Email Security

• Use TLS/SSL for SMTP connections
• Validate email service credentials are properly secured
• Implement rate limiting on email sends (prevent abuse)
• Include unsubscribe link in emails (compliance)

Data Protection

• Email addresses stored as-is (indexed for uniqueness)
• Personal data encrypted at rest (if required by compliance)
• Implement GDPR right-to-erasure for trial users
• Audit trail maintained for all trial user operations

Rate Limiting

• Maximum 10 registration attempts per IP per hour
• Maximum 5 registration attempts per email per day
• Maximum 3 verification email resends per user per day

Testing Scenarios

Test Case 1: Successful Registration

Given: Valid user data and configured email service
When: User submits registration form
Then: User created, email sent, 201 response returned
Verify: Database record exists, email received, tokens are valid

Test Case 2: Duplicate Email Prevention

Given: Email already registered
When: User attempts to register with same email
Then: 409 Conflict returned
Verify: No duplicate user created, appropriate error message

Test Case 3: Email Verification Flow

Given: Email verification enabled
When: User completes registration
Then: Verification email sent, credentials withheld
When: User clicks verification link
Then: Account activated, credentials email sent
Verify: EmailVerified flag updated, welcome email received

Test Case 4: Invalid Email Format

Given: Invalid email format (no @, invalid domain, etc.)
When: User submits registration
Then: 400 Bad Request returned
Verify: No user created, validation error displayed

Test Case 5: Email Delivery Failure Handling

Given: Email service unavailable
When: User registration completes
Then: User created, email failure logged
Verify: User exists in database, admin notified, user can request credentials resend

Test Case 6: Token Uniqueness

Given: Multiple concurrent registrations
When: Users register simultaneously
Then: Each receives unique tokens
Verify: No token collisions in database

Monitoring and Analytics

Key Metrics to Track

• Registration Rate: Number of registrations per day/week/month
• Registration Success Rate: Successful registrations / Total attempts
• Email Delivery Success Rate: Emails delivered / Emails sent
• Verification Completion Rate: Users verified / Total registrations (if verification enabled)
• Time to First Login: Time between registration and first session creation
• Trial Activation Rate: Users who login / Total registrations
• Popular Applications: Which apps are most frequently selected

Alerts

• Registration failure rate > 5% in 1 hour
• Email delivery failure rate > 10% in 1 hour
• Database connection failures
• Abnormal spike in registrations (potential abuse)
• Verification email open rate < 50% (email deliverability issue)

Related Use Cases

• UC-002: Trial User Login and Session Management
• UC-003: Trial User Application Access Validation
• UC-004: Trial Expiration and Renewal
• UC-005: Administrator Trial User Management
• UC-006: Email Verification Process
• UC-007: Trial User Metrics and Reporting

Notes and Assumptions

1. Email Required: Email is the primary identifier; phone-based registration not currently supported
2. Automatic Provisioning: No manual approval required; trials are instant
3. Application Availability: Assumes all requested applications are properly configured and accessible
4. Single Trial Policy: One trial per email address (can be revisited)
5. Trial Extension: Extension/renewal requires administrator intervention (separate use case)
6. Payment Not Integrated: Trial registration is free; payment integration is out of scope
7. Localization: Currently English-only; internationalization is future enhancement

Revision History

Document Owner: Platform Architecture Team
Stakeholders: Product Management, Engineering, Customer Success
Review Cycle: Quarterly or as needed for major changes