Riptide Application Manager - Use Case Documentation

This directory contains comprehensive use case documentation for the Riptide Application Manager platform. Each use case follows a standardized format with detailed flows, diagrams, API specifications, and testing scenarios.

📚 Use Case Index

Identity Management Use Cases

ID Use Case Name Priority Status Description
UC-001 Trial User Self-Registration and Access High ✅ Implemented End-to-end process for prospective customers to self-register for trial accounts and begin using Riptide applications
UC-002 Trial User Login and Session Management High ✅ Implemented User authentication, session creation, validation, timeout handling, and concurrent session management
UC-003 Application Access Validation Critical ✅ Implemented Real-time validation of user access to applications including session validation, trial status checking, and access grants
UC-004 Trial Expiration and Auto-Cleanup High ✅ Implemented Automated trial lifecycle management including expiration warnings, access blocking, and auto-cleanup with GDPR compliance
UC-005 Administrator User Management High ✅ Implemented Management of admin users who control the Application Manager system, including password policies and audit logging
UC-009 Password Reset and Recovery High ✅ Implemented Self-service and admin-initiated password reset process with token-based validation and password history checking
UC-012 Email Verification Process Medium ✅ Implemented Optional email verification workflow for trial user registration with token validation and resend capabilities
UC-014 Bulk User Operations and Management Medium ✅ Implemented Bulk operations for trial users including CSV import, mass trial extensions, and bulk access grants
UC-015 Application User Provisioning High ✅ Implemented Manual provisioning of permanent ApplicationUsers by administrators with role-based access control
UC-017 Team Member Invitation and Collaboration Medium ✅ Implemented Invite team members to collaborate with customizable access levels and role-based permissions
UC-018 External Identity Provider Integration Medium ✅ Implemented Integration with OAuth 2.0, SAML 2.0, Azure AD, and other external identity providers for SSO

Access Control Use Cases

ID Use Case Name Priority Status Description
UC-006 Role-Based Access Control Management Medium ✅ Implemented Create and manage roles, define capabilities/permissions, assign roles to users, and enforce permission checking

Configuration Management Use Cases

ID Use Case Name Priority Status Description
UC-007 Configuration File Management High ✅ Implemented Unix-inspired hierarchical configuration management including file/folder operations, validation, and content editing
UC-008 Configuration Version Control and Rollback High ✅ Implemented Automatic versioning of configuration changes, version comparison, and rollback capabilities with audit trail
UC-020 Multi-Environment Configuration Deployment High ✅ Implemented Manage configurations across development, staging, beta, and production environments with promotion workflows
UC-024 License Key Management High ✅ Implemented Import, list, validate, and revoke Riptide Platform license tokens; track licensed applications and features per installation

System Management Use Cases

ID Use Case Name Priority Status Description
UC-010 Activity Logging and Audit Trail High ✅ Implemented Comprehensive activity logging system with tamper-proof audit trails, search capabilities, and compliance reporting
UC-011 Dashboard and Metrics Visualization Medium ✅ Implemented Administrative dashboard with real-time metrics, system health indicators, activity feeds, and export capabilities
UC-013 Application Registration and Management High ✅ Implemented Register and manage Riptide applications including credentials, health checks, versioning, and usage statistics
UC-016 Tenant Provisioning and Management High ✅ Implemented Multi-tenant architecture support with automated tenant provisioning via application webhooks
UC-019 Unified Application Launch Dashboard High ✅ Implemented Single sign-on portal displaying all accessible applications with one-click launching and session propagation
UC-021 Compliance Security Assessment High ✅ Implemented On-demand and scheduled compliance assessments against SOC 2, HIPAA, FedRAMP, and StateRAMP frameworks; application × framework dashboard; per-application score trends; SecurityAdmin-gated access
UC-022 Advanced Cross-Entity Search and Saved Searches Medium ✅ Implemented Multi-criteria search across trial users and admin users with saved search persistence, CSV export, and pagination
UC-023 Application Health Monitoring High ✅ Implemented Automated and on-demand health monitoring for registered applications with status classification, uptime tracking, and alerting

Agent Identity Use Cases

These use cases add non-human / AI-agent identities alongside the existing person-identity features, derived from the agent-identity plan (docs/internal/agent-identity-plan.md; SDK master design riptide-sdk/docs/plans/AGENT-IDENTITY-ARCHITECTURE.md). They were written ahead of build, so some field/command/route names in the bodies differ from the shipped code. As of the June 2026 agent-identity release the surface is implemented on development (UC-029 is partial), and each document carries an Implementation status note reconciling it to the code, including any gaps. Treat those notes — not the original prose — as authoritative for what shipped.

Agent Identity Backend

ID Use Case Name Priority Status Description
UC-025 Agent Identity Registration and Lifecycle High ✅ Implemented Tenant-owned agent registry CRUD: scope ceiling, allowed task-types, per-turn budget, public keys, and disable/revoke lifecycle
UC-026 Agent Credential Issuance and Ephemeral Tokens Critical ✅ Implemented Ephemeral scoped credential minting, OAuth 2.1 private_key_jwt (RFC 7523), RFC 7662 introspection, and revocation (DPoP reserved, not yet enforced)
UC-027 On-Behalf-Of Delegation High ✅ Implemented RFC 8693 token exchange and the AgentDelegationGrant envelope carrying identity scopes, with actor-chain audit (scope-only this phase)

LLM Gateway

ID Use Case Name Priority Status Description
UC-028 LLM Provider Account and Deployment Management High ✅ Implemented Provider accounts (env / database-encrypted / vault key sources), model catalog, and model deployments across providers with fail-closed unknown-model handling
UC-029 Task-Type Routing and Agent Provisioning High 🚧 Partially Implemented Task-type registry, classification-filtered routing, and agent provisioning; the model-chain cascade and the two named provisioning UX paths are not yet built
UC-030 LLM Request Dispatch Critical ✅ Implemented The LlmGatewayDispatcher lifecycle (resolve, classify, reserve, dispatch, reconcile); PII sweep and response-schema validation/retry not yet implemented
UC-031 Compatibility Passthrough Endpoints Medium ✅ Implemented OpenAI/Anthropic-shaped passthrough endpoints with SSE streaming and strict mid-stream budget hard-stop (embeddings passthrough not yet implemented)

Cost Governance

ID Use Case Name Priority Status Description
UC-032 Budget Cap Lattice and Enforcement Critical ✅ Implemented The generic cap lattice (Top→Tenant→Subscription→Provider→Model), CapLatticeResolver, three enforcement modes, and fail-closed cold-start defaults
UC-033 Agent Plan Lifecycle and Budget Delegation High ✅ Implemented AgentPlan lifecycle, plan-budget extensions, heartbeats and abandonment time-boxes, sub-plan delegation, and loop/fan-out safety nets
UC-034 Spend Reservation and Reconciliation Critical ✅ Implemented Pre-flight LlmSpendReservation, post-call reconciliation, the append-only LlmCallLedger, and the hourly SpendRollup aggregation job
UC-035 Provider Subscriptions and Utilization Medium ✅ Implemented ProviderSubscription on ProviderAccount, always-on utilization tracking, auto-created subscription-tier caps, and period rollover
UC-036 Cost Insights Dashboard and Billing Report High ✅ Implemented The OIDC-authenticated /insights/* dashboard (budget-viewer roles), scope-honesty coverage panel, and configurable-period billing report export
UC-037 Spend Anomaly Detection Medium ✅ Implemented Dual-baseline anomaly detection with a 7-day cold-start floor and three delivery channels (email / webhook / dashboard) by severity
UC-038 Agent and Cost Governance RBAC High ✅ Implemented Capability-based RBAC for the agent / gateway / cost-governance surface, composed onto the existing Role/Capability model with before/after audit

🎯 Use Case Categories

By Module

  • Identity Management: UC-001, UC-002, UC-003, UC-004, UC-005, UC-009, UC-012, UC-014, UC-015, UC-017, UC-018
  • Configuration Management: UC-007, UC-008, UC-020, UC-024
  • Access Control: UC-006
  • System Management: UC-010, UC-011, UC-013, UC-016, UC-019, UC-023
  • Security & Compliance: UC-021
  • Administration: UC-022
  • Agent Identity Backend: UC-025, UC-026, UC-027
  • LLM Gateway: UC-028, UC-029, UC-030, UC-031
  • Cost Governance: UC-032, UC-033, UC-034, UC-035, UC-036, UC-037, UC-038

By Priority

  • Critical: UC-003, UC-026, UC-030, UC-032, UC-034
  • High: UC-001, UC-002, UC-004, UC-005, UC-007, UC-008, UC-009, UC-010, UC-013, UC-015, UC-016, UC-019, UC-020, UC-021, UC-023, UC-024, UC-025, UC-027, UC-028, UC-029, UC-033, UC-036, UC-038
  • Medium: UC-006, UC-011, UC-012, UC-014, UC-017, UC-018, UC-022, UC-031, UC-035, UC-037

By Status

  • ✅ Implemented: UC-001 through UC-028, UC-030, UC-031, and UC-032 through UC-038 (the full person-identity surface plus the June 2026 agent-identity release; several agent-identity UCs ship with noted gaps — see each document's Implementation status note)
  • 🚧 Partially Implemented: UC-029 (task-type registry + routing + agent provisioning shipped; model-chain cascade and the two named provisioning UX paths not yet built)

📖 Document Structure

Each use case document follows a standardized format:

  1. Overview - Metadata table with ID, priority, status, version
  2. Description - Detailed explanation of the use case
  3. Actors - All participants and their roles
  4. Preconditions - Requirements before execution
  5. Postconditions - Expected outcomes (success and failure)
  6. Triggers - Events that initiate the use case
  7. Basic Flow - Happy path with detailed Mermaid sequence diagrams
  8. Alternative Flows - Edge cases, error scenarios, and variations
  9. Business Rules - Constraints and policies with enforcement mechanisms
  10. Data Requirements - Complete schemas and data structures
  11. User Interface - UI mockups and screen layouts
  12. API Endpoints - Complete API documentation with examples
  13. Performance Requirements - Response times, throughput, and scalability targets
  14. Security Considerations - Authentication, authorization, data protection, audit
  15. Testing Scenarios - Comprehensive test cases
  16. Monitoring and Analytics - Metrics, alerts, and dashboards
  17. Related Use Cases - Cross-references to dependent or related use cases
  18. Notes and Assumptions - Implementation details and decisions
  19. Revision History - Document version tracking

🔄 Use Case Relationships

graph TB
    UC001[UC-001: Trial User<br/>Self-Registration] --> UC002[UC-002: Login &<br/>Session Management]
    UC001 --> UC012[UC-012: Email<br/>Verification]
    UC002 --> UC003[UC-003: Application<br/>Access Validation]
    UC001 --> UC004[UC-004: Trial<br/>Expiration]
    UC004 --> UC002
    UC005[UC-005: Admin User<br/>Management] --> UC006[UC-006: Role-Based<br/>Access Control]
    UC006 --> UC002
    UC006 --> UC003
    UC007[UC-007: Config File<br/>Management] --> UC008[UC-008: Version<br/>Control]
    UC008 --> UC010[UC-010: Activity<br/>Logging]
    UC002 --> UC010
    UC001 --> UC010
    UC005 --> UC010
    UC007 --> UC010
    UC011[UC-011: Dashboard<br/>& Metrics] --> UC001
    UC011 --> UC002
    UC011 --> UC006
    UC013[UC-013: Application<br/>Registration] --> UC003
    UC013 --> UC001
    UC014[UC-014: Bulk User<br/>Operations] --> UC001
    UC014 --> UC004
    UC009[UC-009: Password<br/>Reset] --> UC002
    UC015[UC-015: Application<br/>User Provisioning] --> UC002
    UC015 --> UC006
    UC015 --> UC016[UC-016: Tenant<br/>Provisioning]
    UC017[UC-017: Team Member<br/>Invitation] --> UC015
    UC017 --> UC006
    UC018[UC-018: External IdP<br/>Integration] --> UC002
    UC018 --> UC015
    UC019[UC-019: Unified Launch<br/>Dashboard] --> UC002
    UC019 --> UC003
    UC019 --> UC013
    UC020[UC-020: Multi-Environment<br/>Config Deployment] --> UC007
    UC020 --> UC008
    UC020 --> UC010
    UC021[UC-021: Compliance<br/>Security Assessment] --> UC013
    UC021 --> UC010
    UC022[UC-022: Advanced<br/>Search] --> UC001
    UC022 --> UC005
    UC023[UC-023: Application<br/>Health Monitoring] --> UC013
    UC024[UC-024: License Key<br/>Management] --> UC013
    UC024 --> UC010

    %% Agent Identity release (shipped June 2026; UC-029 partial)
    UC025[UC-025: Agent<br/>Registration] --> UC026[UC-026: Credential<br/>Issuance]
    UC025 --> UC029[UC-029: Task-Type<br/>Routing]
    UC025 --> UC032[UC-032: Budget Cap<br/>Lattice]
    UC026 --> UC027[UC-027: On-Behalf-Of<br/>Delegation]
    UC027 --> UC033[UC-033: Plan Lifecycle<br/>& Delegation]
    UC028[UC-028: Provider &<br/>Deployments] --> UC029
    UC028 --> UC030[UC-030: LLM<br/>Dispatch]
    UC029 --> UC030
    UC030 --> UC031[UC-031: Compatibility<br/>Passthrough]
    UC031 --> UC026
    UC030 --> UC034[UC-034: Reservation<br/>& Reconciliation]
    UC030 --> UC032
    UC032 --> UC034
    UC033 --> UC034
    UC034 --> UC036[UC-036: Insights<br/>& Billing]
    UC035[UC-035: Provider<br/>Subscriptions] --> UC032
    UC035 --> UC034
    UC036 --> UC037[UC-037: Anomaly<br/>Detection]
    UC037 --> UC034
    UC038[UC-038: Agent &<br/>Cost RBAC] --> UC032
    UC038 --> UC036
    UC038 --> UC006
    UC016 --> UC032
    UC033 --> UC010
    UC034 --> UC010

    style UC003 fill:#ef4444,color:#fff
    style UC001 fill:#2563eb,color:#fff
    style UC002 fill:#2563eb,color:#fff
    style UC004 fill:#2563eb,color:#fff
    style UC005 fill:#2563eb,color:#fff
    style UC007 fill:#2563eb,color:#fff
    style UC008 fill:#2563eb,color:#fff
    style UC009 fill:#2563eb,color:#fff
    style UC010 fill:#2563eb,color:#fff
    style UC013 fill:#2563eb,color:#fff
    style UC015 fill:#2563eb,color:#fff
    style UC016 fill:#2563eb,color:#fff
    style UC019 fill:#2563eb,color:#fff
    style UC020 fill:#2563eb,color:#fff
    style UC006 fill:#f59e0b,color:#fff
    style UC011 fill:#f59e0b,color:#fff
    style UC012 fill:#f59e0b,color:#fff
    style UC014 fill:#f59e0b,color:#fff
    style UC017 fill:#f59e0b,color:#fff
    style UC018 fill:#f59e0b,color:#fff
    style UC021 fill:#2563eb,color:#fff
    style UC022 fill:#f59e0b,color:#fff
    style UC023 fill:#2563eb,color:#fff
    style UC024 fill:#2563eb,color:#fff
    style UC025 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3
    style UC026 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3
    style UC027 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3
    style UC028 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3
    style UC029 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3
    style UC030 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3
    style UC031 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3
    style UC032 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3
    style UC033 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3
    style UC034 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3
    style UC035 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3
    style UC036 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3
    style UC037 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3
    style UC038 fill:#6b7280,color:#fff,stroke:#7c3aed,stroke-width:2px,stroke-dasharray:4 3

Legend:

  • 🔴 Red = Critical Priority
  • 🔵 Blue = High Priority
  • 🟡 Orange = Medium Priority
  • ⬜ Gray (dashed purple outline) = Agent Identity release — ✅ shipped June 2026 (UC-029 partial)

🔗 Cross-Cutting Concerns

Security

All use cases address security through:

  • Authentication: Token-based authentication (UC-002)
  • Authorization: Role-based access control (UC-006)
  • Audit Trail: Comprehensive logging (UC-010)
  • Data Protection: Encryption, hashing, secure token generation
  • Rate Limiting: Prevent abuse across all public endpoints

Performance

Performance considerations across use cases:

  • Caching: Session validation (UC-003), dashboard metrics (UC-011)
  • Async Processing: Email delivery (UC-001), bulk operations (UC-014)
  • Database Optimization: Indexing, query optimization, connection pooling
  • Background Jobs: Trial expiration (UC-004), cleanup operations

Compliance

GDPR and compliance features:

  • Right to Erasure: Auto-cleanup with anonymization (UC-004)
  • Audit Trail: Complete activity history (UC-010)
  • Data Minimization: Only collect necessary information
  • Consent Management: Email opt-in/out capabilities

🎨 Visual Conventions

Mermaid Diagram Types

  • Sequence Diagrams: Show actor interactions over time
  • Flowcharts: Illustrate decision trees and branching logic
  • State Diagrams: Represent entity lifecycle states
  • ER Diagrams: Display data relationships
  • Architecture Diagrams: Show system component relationships

Status Indicators

  • ✅ Implemented - Feature is deployed and operational
  • 🚧 In Progress - Currently under development
  • 📋 Planned - Scheduled for future implementation
  • 🔍 Under Review - Being evaluated or designed
  • ❌ Deprecated - No longer supported

📝 How to Use This Documentation

For Product Managers

  • Review use cases to understand feature scope and user journeys
  • Use business rules to define product requirements
  • Reference related use cases to identify feature dependencies

For Developers

  • Follow basic and alternative flows for implementation guidance
  • Use API endpoint specifications for backend development
  • Reference data requirements for database schema design
  • Implement security considerations and business rules

For QA Engineers

  • Use testing scenarios as starting point for test plans
  • Validate all alternative flows and error conditions
  • Verify performance requirements are met
  • Test security considerations and audit logging

For Technical Writers

  • Extract user-facing documentation from UI sections
  • Use API endpoint documentation for developer guides
  • Reference business rules for user constraints and limitations

For Architects

  • Review use case relationships for system dependencies
  • Analyze performance requirements for capacity planning
  • Evaluate security considerations for architecture decisions
  • Use monitoring specifications for observability design

🔄 Maintenance and Updates

When to Update Use Cases

  • Feature enhancements or modifications
  • New alternative flows discovered during implementation
  • Changes to business rules or data requirements
  • API endpoint changes or new endpoints added
  • Security vulnerabilities identified and addressed
  • Performance optimizations implemented

Version Control

Each use case maintains a revision history table tracking:

  • Version number
  • Date of change
  • Author
  • Summary of changes

Review Cycle

  • Quarterly Review: Ensure all implemented use cases are accurate
  • Pre-Release Review: Verify documentation matches implementation before major releases
  • Post-Incident Review: Update use cases if incidents reveal gaps in documentation

📞 Contact and Contributions

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

To suggest changes or report issues with use case documentation:

  1. Create an issue in the project repository
  2. Tag with documentation label
  3. Reference specific use case ID (e.g., UC-001)
  4. Provide clear description of needed changes

🚀 Getting Started

If you're new to the Riptide Application Manager, we recommend reading use cases in this order:

Core Platform Understanding:

  1. UC-013 - Understand how applications are registered
  2. UC-019 - See the unified user experience
  3. UC-002 - Learn about authentication
  4. UC-003 - Understand access control flow

Trial User Journey:

  1. UC-001 - See how users sign up for trials
  2. UC-004 - Understand trial lifecycle
  3. UC-012 - Email verification workflow

Enterprise User Management:

  1. UC-015 - Permanent user provisioning
  2. UC-017 - Team collaboration
  3. UC-018 - SSO integration

Configuration Management:

  1. UC-007 - File and folder operations
  2. UC-008 - Version control system
  3. UC-020 - Multi-environment deployment

System Administration:

  1. UC-005 - Admin user management
  2. UC-006 - RBAC system
  3. UC-010 - Audit and compliance
  4. UC-011 - Admin dashboard

Agent Identity & AI Cost Governance (shipped June 2026):

  1. UC-025 - How agents are registered and scoped
  2. UC-026 - Ephemeral credentials and OAuth 2.1 tokens
  3. UC-030 - The LLM gateway request lifecycle
  4. UC-032 - The budget cap lattice and enforcement
  5. UC-034 - How spend is reserved, reconciled, and ledgered

Last Updated: June 15, 2026 Documentation Version: 1.4 Total Use Cases: 38 (37 Implemented, 1 Partially Implemented — UC-029). The agent-identity release (UC-025–038) shipped in June 2026; see each document's Implementation status note for code-name reconciliation and any gaps.