Use Case 019: Unified Application Launch Dashboard

Overview

Description

This use case describes the unified application launch dashboard that serves as a single sign-on portal for all Riptide applications. After authenticating with Application Manager, users see a personalized dashboard displaying all applications they have access to, their assigned roles, team memberships, trial status (if applicable), and quick access links. The dashboard provides one-click application launching with automatic session propagation, eliminating the need for repeated authentication across the application ecosystem.

Actors

Preconditions

1. User has authenticated with Application Manager (password or SSO)
2. Active session exists with valid session token
3. User has at least one application access grant
4. Applications are registered and active in Application Manager
5. Application health checks passing (applications are accessible)

Postconditions

Success Postconditions

1. Dashboard displayed with user's accessible applications
2. Role badges and access status shown for each application
3. Trial countdown displayed (if user is TrialUser)
4. Team membership information shown
5. Application launched with session automatically propagated
6. Dashboard access logged in audit trail
7. Application launch event recorded

Failure Postconditions

1. Session expired error shown if session invalid
2. No applications shown if user has no access grants
3. Unavailable applications marked as offline
4. Trial expired users shown expired state with contact info

Triggers

• User completes authentication (UC-002)
• User navigates to Application Manager root URL after login
• User clicks "Dashboard" in navigation menu
• User redirected to dashboard after invitation acceptance (UC-017)
• User clicks "Launch" button on specific application
• User refreshes dashboard to see updated trial status

Basic Flow (Happy Path)

sequenceDiagram
    actor User as ApplicationUser
    participant Web as Dashboard UI
    participant API as Application Manager API
    participant DB as Identity Database
    participant App as Riptide Application

    User->>Web: Navigate to dashboard (/dashboard)
    Web->>API: GET /api/v1/dashboard
    Note over API: Auth: Bearer {sessionToken}
    
    API->>DB: Validate session token
    DB->>API: Session valid (userId, tenantId)
    
    API->>DB: Fetch user details
    DB->>API: User info (name, email, roles)
    
    API->>DB: Fetch application access grants
    DB->>API: List of accessible applications
    
    API->>DB: Fetch team memberships
    DB->>API: Team list with role assignments
    
    alt User is TrialUser
        API->>DB: Fetch trial expiration date
        DB->>API: Trial expires on 2026-03-15
        API->>API: Calculate days remaining
    end
    
    loop For each application
        API->>DB: Fetch application metadata
        DB->>API: App name, description, URL, icon
        
        API->>DB: Check application health status
        DB->>API: Health: Healthy (last check < 5 min ago)
    end
    
    API->>Web: Dashboard data JSON
    Note over API,Web: User info, apps, teams, trial status
    
    Web->>User: Display personalized dashboard
    Note over User,Web: Shows:<br/>- Welcome message<br/>- Trial countdown (if applicable)<br/>- Available applications grid<br/>- Team memberships<br/>- Quick actions
    
    Note over User: User launches application
    
    User->>Web: Click "Launch" on Application
    Web->>API: POST /api/v1/sessions/propagate
    Note over Web,API: Body: {applicationId, sessionToken}
    
    API->>DB: Validate session and access
    DB->>API: Access granted for application
    
    API->>API: Generate application session token
    Note over API: Token includes userId, tenantId, capabilities
    
    API->>DB: Log application launch event
    DB->>API: Event logged
    
    API->>Web: Launch URL with session token
    Note over API,Web: URL: https://app.example.com?token=xyz
    
    Web->>App: Open application in new tab
    App->>API: Validate session token
    API->>DB: Verify token and fetch capabilities
    DB->>API: Token valid, user capabilities
    API->>App: User validated
    
    App->>User: Display application dashboard

Alternative Flows

Alt-1: Trial User Near Expiration

Trigger: TrialUser dashboard access with < 7 days remaining

Flow:

1. User accesses dashboard
2. System calculates days remaining on trial
3. Days remaining < 7
4. Dashboard displays prominent warning banner:
   • "Your trial expires in 3 days"
   • "Contact us to extend your trial or upgrade"
   • Contact button linking to sales/support
5. Warning color-coded: Yellow (7-3 days), Orange (2-1 days), Red (< 1 day)
6. Rest of dashboard functions normally

Alt-2: Trial User Expired

Trigger: TrialUser dashboard access after trial expiration

Flow:

1. User accesses dashboard
2. System detects trial expired
3. Dashboard shows limited view:
   • "Your trial has expired"
   • Trial duration and expiration date shown
   • Access to applications disabled (Launch buttons greyed out)
   • Grace period information displayed (if applicable)
   • Contact administrator link
4. Logout button available
5. No application launching allowed

Alt-3: Application Offline/Unhealthy

Trigger: Dashboard loads but one or more applications are offline

Flow:

1. User accesses dashboard
2. System fetches application health statuses
3. Application health check failed or last check > 10 minutes ago
4. Application tile shows "Offline" badge
5. Launch button disabled for offline applications
6. Hover tooltip: "Application is currently unavailable"
7. Administrator notified of offline status
8. User can still launch healthy applications

Alt-4: No Application Access

Trigger: User has valid session but no application grants

Flow:

1. User accesses dashboard
2. Application access query returns empty result
3. Dashboard displays empty state:
   • "No applications available"
   • "Contact your administrator to request access"
   • List of team memberships (if any)
   • User profile information still accessible
4. For TrialUsers: Contact sales/support option

Alt-5: Session Expired During Dashboard Use

Trigger: User session expires while browsing dashboard

Flow:

1. User dashboard loaded successfully
2. User idle for > 8 hours (session timeout)
3. User clicks "Launch" on application
4. API returns 401 Unauthorized (session expired)
5. Web shows session expired modal
6. User redirected to login page with returnUrl=/dashboard
7. After re-authentication, user returns to dashboard

Business Rules

Dashboard Access Rules

• BR-019-01: All authenticated users can access dashboard
• BR-019-02: Dashboard only shows applications user has explicit access grants for
• BR-019-03: Expired TrialUsers see limited dashboard (no launching)
• BR-019-04: Team memberships displayed if user belongs to teams

Application Display Rules

• BR-019-05: Applications sorted alphabetically by default
• BR-019-06: User can customize application order (saved in preferences)
• BR-019-07: Application icons fetched from application registration
• BR-019-08: Offline applications shown but Launch button disabled
• BR-019-09: Applications display assigned role badges for that user

Trial Status Display Rules

• BR-019-10: Trial countdown shown for TrialUsers only
• BR-019-11: Warning banners shown when < 7 days remaining
• BR-019-12: Grace period info displayed if trial in grace period
• BR-019-13: Trial expiration timestamp shown in user's local timezone

Session Propagation Rules

• BR-019-14: Application launches use short-lived propagation tokens (5 min expiry)
• BR-019-15: Propagation tokens include user capabilities for target application
• BR-019-16: Each application launch logged in audit trail
• BR-019-17: Application validates propagation token before granting access

Data Requirements

Dashboard Data Structure

interface DashboardData {
  user: {
    userId: string;
    email: string;
    fullName: string;
    userType: 'Trial' | 'Application' | 'Admin';
    roles: Role[];
    profileImageUrl?: string;
  };
  
  trial?: {
    expiresAt: string;  // ISO 8601
    daysRemaining: number;
    gracePeriodDays: number;
    isExpired: boolean;
    isInGracePeriod: boolean;
  };
  
  applications: Application[];
  
  teams: Team[];
  
  notifications: Notification[];
}

interface Application {
  id: string;
  name: string;
  description: string;
  iconUrl: string;
  launchUrl: string;
  healthStatus: 'Healthy' | 'Degraded' | 'Offline' | 'Unknown';
  lastHealthCheck: string;
  userRoles: string[];  // Roles for this specific app
  tags: string[];
}

interface Team {
  teamId: string;
  teamName: string;
  memberCount: number;
  role: string;
  joinedAt: string;
}

interface Notification {
  id: string;
  type: 'Info' | 'Warning' | 'Error';
  message: string;
  actionLabel?: string;
  actionUrl?: string;
  createdAt: string;
}

User Interface

Dashboard Layout

┌─────────────────────────────────────────────────────────────┐
│ [Logo] Application Manager            [Notifications] [User]│
├─────────────────────────────────────────────────────────────┤
│                                                              │
│ ┌──────────────────────────────────────────────────────────┐│
│ │ ⚠️  Your trial expires in 3 days       [Contact Us]     ││
│ └──────────────────────────────────────────────────────────┘│
│                                                              │
│  Welcome back, Jane Smith                                    │
│  Trial Account • Developer                                   │
│                                                              │
│  My Applications                              [⚙️ Customize] │
│                                                              │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐  │
│  │  📊           │  │  ⚙️            │  │  🔧           │  │
│  │ Workflow      │  │ Configuration │  │ Fee Manager   │  │
│  │ Designer      │  │ Manager       │  │               │  │
│  │               │  │               │  │               │  │
│  │ [Developer]   │  │ [Admin]       │  │ [Viewer]      │  │
│  │               │  │               │  │               │  │
│  │  [Launch] ✓   │  │  [Launch] ✓   │  │  [Launch] ✓   │  │
│  └───────────────┘  └───────────────┘  └───────────────┘  │
│                                                              │
│  My Teams                                                    │
│                                                              │
│  • Acme Corp Development Team (Developer) - 12 members      │
│  • Platform Engineering (Viewer) - 8 members                │
│                                                              │
│  Recent Activity                                             │
│                                                              │
│  • Launched Workflow Designer - 2 hours ago                 │
│  • Updated configuration in Config Manager - 1 day ago      │
│  • Joined Platform Engineering team - 3 days ago            │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Application Tile States

Healthy Application:

┌───────────────┐
│  📊           │
│ Workflow      │
│ Designer      │
│               │
│ [Developer]   │
│               │
│  [Launch] ✓   │
└───────────────┘

Offline Application:

┌───────────────┐
│  ⚠️ Offline    │
│ Fee Manager   │
│ (unavailable) │
│               │
│ [Viewer]      │
│               │
│  [Launch] 🔒   │
└───────────────┘

Expired Trial - Blocked Access:

┌───────────────┐
│  🔒           │
│ Workflow      │
│ Designer      │
│ Trial Expired │
│               │
│               │
│  Access Locked │
└───────────────┘

API Endpoints

Get Dashboard Data

Endpoint: GET /api/v1/dashboard

Headers:

Authorization: Bearer {sessionToken}

Response: 200 OK

{
  "user": {
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "jane@example.com",
    "fullName": "Jane Smith",
    "userType": "Trial",
    "roles": [
      {"id": "role-1", "name": "Developer"},
      {"id": "role-2", "name": "Viewer"}
    ]
  },
  "trial": {
    "expiresAt": "2026-03-15T23:59:59Z",
    "daysRemaining": 3,
    "gracePeriodDays": 7,
    "isExpired": false,
    "isInGracePeriod": false
  },
  "applications": [
    {
      "id": "app-1",
      "name": "Workflow Designer",
      "description": "Design and orchestrate business workflows",
      "iconUrl": "/icons/workflow-designer.svg",
      "launchUrl": "https://workflow.example.com",
      "healthStatus": "Healthy",
      "lastHealthCheck": "2026-02-23T10:25:00Z",
      "userRoles": ["Developer"],
      "tags": ["workflow", "automation"]
    },
    {
      "id": "app-2",
      "name": "Configuration Manager",
      "description": "Centralized configuration management",
      "iconUrl": "/icons/config-manager.svg",
      "launchUrl": "https://config.example.com",
      "healthStatus": "Healthy",
      "lastHealthCheck": "2026-02-23T10:26:00Z",
      "userRoles": ["Admin"],
      "tags": ["configuration", "devops"]
    }
  ],
  "teams": [
    {
      "teamId": "team-1",
      "teamName": "Acme Corp Development Team",
      "memberCount": 12,
      "role": "Developer",
      "joinedAt": "2026-01-15T10:00:00Z"
    }
  ],
  "notifications": [
    {
      "id": "notif-1",
      "type": "Warning",
      "message": "Your trial expires in 3 days",
      "actionLabel": "Contact Us",
      "actionUrl": "/contact-sales",
      "createdAt": "2026-02-23T00:00:00Z"
    }
  ]
}

Launch Application (Session Propagation)

Endpoint: POST /api/v1/applications/{applicationId}/launch

Headers:

Authorization: Bearer {sessionToken}

Response: 200 OK

{
  "launchUrl": "https://app.example.com/auth/sso?token=eyJhbGciOiJIUzI1NiIs...",
  "propagationToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 300,
  "application": {
    "id": "app-1",
    "name": "Workflow Designer",
    "url": "https://workflow.example.com"
  }
}

Customize Dashboard Preferences

Endpoint: PATCH /api/v1/dashboard/preferences

Request Body:

{
  "applicationOrder": ["app-2", "app-1", "app-3"],
  "theme": "dark",
  "compactView": false
}

Response: 200 OK

Performance Requirements

• PR-019-01: Dashboard data loaded within 1.5 seconds
• PR-019-02: Application health checks cached for 5 minutes
• PR-019-03: Session propagation token generated within 200ms
• PR-019-04: Dashboard refreshes (user-initiated) complete within 800ms
• PR-019-05: Dashboard supports 1000+ concurrent active sessions

Security Considerations

Session Management

• Session token validated on every dashboard API call
• Expired sessions immediately redirect to login
• Session token never exposed in URLs
• Short-lived propagation tokens (5 min expiry) for app launches

Access Control

• Application visibility strictly enforced by user access grants
• Role badges reflect actual user permissions per application
• Tenant isolation enforced in all queries
• No cross-tenant data leakage

Audit & Compliance

• Dashboard access logged (timestamp, user ID, session ID)
• Application launches logged with target application
• Failed access attempts logged and alerted
• Trial status changes logged

Testing Scenarios

Test Case TC-019-01: Successful Dashboard Load

Preconditions:

• User authenticated with valid session
• User has access to 2 applications

Steps:

1. User navigates to /dashboard
2. System validates session
3. System fetches user data, apps, teams
4. Dashboard rendered with all data

Expected Results:

• Dashboard displays within 1.5 seconds
• 2 applications shown with correct roles
• Trial countdown shown (if TrialUser)
• Teams listed correctly

Test Case TC-019-02: Application Launch

Steps:

1. User on dashboard clicks "Launch" on application
2. System validates access
3. System generates propagation token
4. Application opened in new tab
5. Application validates token

Expected Results:

• Propagation token generated
• Application opens successfully
• User authenticated in application
• Launch event logged

Test Case TC-019-03: Trial Expiration Warning

Preconditions:

• TrialUser with 3 days remaining

Steps:

1. User accesses dashboard
2. System calculates days remaining

Expected Results:

• Warning banner displayed: "Your trial expires in 3 days"
• Banner color-coded orange
• Contact button available
• Applications still launchable

Test Case TC-019-04: Expired Trial Access Block

Preconditions:

• TrialUser with expired trial

Steps:

1. User accesses dashboard
2. System detects trial expired

Expected Results:

• Limited dashboard view shown
• Message: "Your trial has expired"
• Application Launch buttons disabled
• Contact administrator link shown

Monitoring and Analytics

Metrics

• dashboard.views: Dashboard page views (daily, weekly)
• dashboard.load.duration: Dashboard load time (p50, p95, p99)
• application.launches: Application launch count (per app, per user)
• trial.warnings.shown: Trial expiration warnings displayed
• session.propagation.duration: Session propagation latency

Alerts

• Dashboard load performance degradation: p95 > 3 seconds
• High application launch failures: > 5% failures in 1 hour
• Offline applications: Health checks failing > 3 consecutive times

Dashboards (Admin Analytics)

• Daily active users viewing dashboard
• Most launched applications
• Application health status trends
• Trial expiration funnel (warnings → expirations)

Related Use Cases

• UC-002: Trial User Login and Session Management - Session creation before dashboard
• UC-003: Application Access Validation - Access checking for visibility
• UC-004: Trial Expiration and Auto-Cleanup - Trial status display
• UC-013: Application Registration and Management - Applications shown on dashboard
• UC-017: Team Member Invitation - Team membership display
• UC-010: Activity Logging - Dashboard and launch event logging

Notes and Assumptions

Assumptions

1. Users expect single sign-on experience across all applications
2. Applications support token-based session propagation
3. Application health checks are reliable
4. Users prefer visual dashboard over CLI

Implementation Notes

1. Consider caching dashboard data for 1 minute to reduce DB load
2. Use WebSocket for real-time trial countdown updates
3. Implement lazy loading for application icons
4. Support customizable dashboard layouts (grid vs list)

Future Enhancements

1. Personalized application recommendations
2. Usage analytics per application
3. Favorite applications pinning
4. Quick search across all applications
5. Mobile-responsive dashboard design
6. Dark mode theme support

Revision History