Proposed Page Organization

This document proposes an improved page organization for the SCORM API website, addressing issues with route structure, page grouping, and user flows.

Design Principles

Logical Grouping: Organize pages by feature, not by user role
Consistent Patterns: Uniform route structure across similar features
Unified Interfaces: Consolidate related pages with tabs
Clear Hierarchy: Consistent depth and nesting
Backward Compatible: Preserve existing routes

Proposed Route Structure

Customer Routes (Reorganized)

Option A: Feature-Based Grouping (Recommended)

/dashboard                    → Main dashboard
/content                      → Content management hub
  /content/packages           → Packages list
  /content/packages/[id]     → Package details
  /content/packages/upload    → Upload package (new)
  /content/dispatch           → Dispatch list
  /content/dispatch/create    → Create dispatch
  /content/dispatch/[id]      → Dispatch details
/analytics                    → Analytics hub
  /analytics/reports          → Unified reports (tabs)
  /analytics/usage            → Usage metrics
  /analytics/xapi             → xAPI statements
/integrations                 → Integrations hub
  /integrations/api-keys      → API keys
  /integrations/webhooks      → Webhooks
  /integrations/credentials   → Unified credentials
/account                      → Account hub
  /account/billing            → Billing
  /account/usage              → Usage quotas
  /account/settings           → Settings (new)
/learning                     → Learning hub (for learners)
  /learning/dashboard        → Learner dashboard
  /learning/packages/[id]    → Package view

Option B: Keep Current Structure, Add Hubs

/dashboard                    → Main dashboard
/dashboard/content            → Content hub (new)
  /dashboard/packages         → Packages (existing)
  /dashboard/dispatch         → Dispatch (existing)
/dashboard/analytics          → Analytics hub (new)
  /dashboard/reports          → Reports (existing)
  /dashboard/usage            → Usage (existing)
  /dashboard/xapi             → xAPI (existing)
/dashboard/integrations       → Integrations hub (new)
  /dashboard/api-keys         → API keys (existing)
  /dashboard/webhooks         → Webhooks (existing)
  /dashboard/credentials      → Credentials (existing)
/dashboard/account            → Account hub (new)
  /dashboard/billing          → Billing (existing)
  /dashboard/usage            → Usage (existing, shared)
  /dashboard/settings         → Settings (new)

Recommendation: Option B (backward compatible, adds hubs)

Proposed Page Consolidations

Consolidation 1: Reports Hub

Current: 3 separate pages

/dashboard/reports (landing)
/dashboard/reports/custom
/dashboard/reports/learner-progress

Proposed: 1 unified page with tabs

/dashboard/reports (unified interface)
- Tab: "Learner Progress"
- Tab: "Custom Reports"
- Tab: "Usage Analytics" (from /dashboard/usage)

Implementation:

<ReportsPage>
  <Tabs>
    <Tab label="Learner Progress" href="/dashboard/reports?tab=learner-progress">
      <LearnerProgressReports />
    </Tab>
    <Tab label="Custom Reports" href="/dashboard/reports?tab=custom">
      <CustomReports />
    </Tab>
    <Tab label="Usage" href="/dashboard/reports?tab=usage">
      <UsageMetrics />
    </Tab>
  </Tabs>
</ReportsPage>

Benefits:

Single page to learn
Easier navigation
Consistent interface
Can compare different analytics

Consolidation 2: Integrations Hub

Current: 3 separate pages

/dashboard/api-keys
/dashboard/webhooks
/dashboard/credentials (unified, but hidden)

Proposed: 1 unified page with tabs

/dashboard/integrations (unified interface)
- Tab: "API Keys"
- Tab: "Webhooks"
- Tab: "Dispatch Tokens"

Implementation:

<IntegrationsPage>
  <Tabs>
    <Tab label="API Keys" href="/dashboard/integrations?tab=api-keys">
      <ApiKeysManager />
    </Tab>
    <Tab label="Webhooks" href="/dashboard/integrations?tab=webhooks">
      <WebhooksManager />
    </Tab>
    <Tab label="Dispatch Tokens" href="/dashboard/integrations?tab=dispatch">
      <DispatchTokensManager />
    </Tab>
  </Tabs>
</IntegrationsPage>

Benefits:

Related features together
Easier to understand relationships
Single navigation item
Can manage all integrations in one place

Consolidation 3: Content Hub

Current: 2 separate pages

/dashboard/packages
/dashboard/dispatch

Proposed: 1 hub page with sections (optional)

/dashboard/content (hub page)
- Section: "SCORM Packages"
- Section: "Dispatch Packages"
- Or keep separate but add hub landing page

Benefits:

Clear content management area
Can add future content types
Consistent with other hubs

Proposed Route Patterns

Pattern 1: List → Detail → Actions

Standard Pattern:

/feature              → List page
/feature/[id]         → Detail page
/feature/create       → Create page (if needed)
/feature/[id]/edit    → Edit page (if needed)

Examples:

/dashboard/packages → /dashboard/packages/[id] ✅
/dashboard/dispatch → /dashboard/dispatch/[id] ✅
/dashboard/api-keys → No detail page ❌ (add if needed)

Pattern 2: Hub → Tabs

Standard Pattern:

/feature              → Hub page with tabs
/feature?tab=tab1     → Tab 1 (query param)
/feature?tab=tab2     → Tab 2 (query param)

Examples:

/dashboard/reports?tab=learner-progress
/dashboard/reports?tab=custom
/dashboard/integrations?tab=api-keys

Pattern 3: Nested Resources

Standard Pattern:

/resource/[id]/sub-resource        → Sub-resource list
/resource/[id]/sub-resource/[subId] → Sub-resource detail

Examples:

/dashboard/packages/[id]/versions (if needed)
/admin/packages/[id]/distribution ✅ (existing)

Proposed New Pages

Page 1: Settings Page

Route: /dashboard/settings

Purpose: Unified settings page

Sections:

Profile Settings
Notification Preferences
Security Settings
API Preferences
Display Preferences

Implementation:

<SettingsPage>
  <Tabs>
    <Tab label="Profile">...</Tab>
    <Tab label="Notifications">...</Tab>
    <Tab label="Security">...</Tab>
    <Tab label="API">...</Tab>
    <Tab label="Display">...</Tab>
  </Tabs>
</SettingsPage>

Page 2: Content Hub Landing

Route: /dashboard/content

Purpose: Landing page for content management

Content:

Quick stats (package count, dispatch count)
Recent packages
Quick actions (Upload, Create Dispatch)
Links to Packages and Dispatch

Optional: Can be skipped if users go directly to Packages/Dispatch

Page 3: Package Upload UI

Route: /dashboard/packages/upload

Purpose: UI for uploading packages (currently API only)

Features:

Drag-and-drop upload
File validation
Progress indicator
Upload history

Benefits:

No need to use API for uploads
Better user experience
Integrated workflow

Page 4: Help Center

Route: /help

Purpose: Centralized help and support

Sections:

Getting Started
Common Questions
API Documentation
Support Contact
Status Page

Route Naming Standardization

Standard 1: Plural for Lists, Singular for Actions

Pattern:

List pages: /dashboard/packages (plural)
Detail pages: /dashboard/packages/[id] (plural + ID)
Action pages: /dashboard/dispatch/create (singular action)

Apply Consistently:

✅ /dashboard/packages (plural)
✅ /dashboard/api-keys (plural)
⚠️ /dashboard/billing (singular, but it's a settings page - OK)
⚠️ /dashboard/usage (singular, but it's metrics - OK)

Standard 2: Kebab-case for All Routes

Current: Already consistent ✅

Examples:

/dashboard/api-keys ✅
/dashboard/learner-progress ✅
/dashboard/xapi ⚠️ (abbreviation, but acceptable)

Standard 3: Consistent Depth

Pattern:

Level 1: /dashboard, /admin
Level 2: /dashboard/feature
Level 3: /dashboard/feature/[id] or /dashboard/feature/action
Level 4: /dashboard/feature/[id]/sub-feature (only when necessary)

Apply:

Keep most routes at 2-3 levels
Only use 4+ levels for deeply nested resources
Be consistent across similar features

Proposed Admin Route Structure

Reorganized Admin Routes

/admin                      → Admin dashboard
/admin/data                 → Data management hub
  /admin/packages           → All packages
  /admin/packages/[id]      → Package details
  /admin/tenants            → Tenant management
  /admin/api-keys           → All API keys
  /admin/webhooks           → All webhooks
/admin/analytics            → Analytics hub
  /admin/reports            → Unified reports (tabs)
  /admin/reports?tab=learner-progress
  /admin/reports?tab=custom
/admin/system               → System hub
  /admin/system/health      → System health
  /admin/system/settings    → System settings
  /admin/system/audit-logs  → Audit logs

Changes

Group Data Management: Packages, Tenants, API Keys, Webhooks
Unify Reports: Single reports page with tabs
System Hub: Health, Settings, Audit Logs together
Remove "(All Tenants)": Redundant in admin context

Proposed Learner Route Structure

Reorganized Learner Routes

/learning                   → Learning hub (new)
  /learning/dashboard       → Learner dashboard
  /learning/packages        → Enrolled packages list
  /learning/packages/[id]   → Package view
  /learning/progress        → Progress tracking
  /learning/certificates    → Certificates (if available)

Changes

Learning Hub: Central location for all learning features
Consistent Naming: /learning/* instead of /learner/*
Progress Page: Dedicated progress tracking page

Note: Keep /learner/* routes for backward compatibility, redirect to /learning/*

Page Consolidation Details

Reports Consolidation

Current Structure:

/dashboard/reports                    → Landing (minimal value)
/dashboard/reports/custom             → Custom reports
/dashboard/reports/learner-progress   → Learner progress
/dashboard/usage                      → Usage metrics (separate)

Proposed Structure:

/dashboard/reports                     → Unified reports interface
  ?tab=learner-progress               → Learner progress tab
  ?tab=custom                         → Custom reports tab
  ?tab=usage                          → Usage metrics tab

Migration:

Keep old routes, redirect to new with appropriate tab
Update all internal links
Update navigation

Integrations Consolidation

Current Structure:

/dashboard/api-keys                   → API keys only
/dashboard/webhooks                    → Webhooks only
/dashboard/credentials                 → Unified (hidden)

Proposed Structure:

/dashboard/integrations                → Unified integrations
  ?tab=api-keys                        → API keys tab
  ?tab=webhooks                        → Webhooks tab
  ?tab=dispatch                        → Dispatch tokens tab

Migration:

Keep old routes, redirect to new with appropriate tab
Add to navigation
Update all internal links

Route Depth Standardization

Standard Depth Levels

Level 1: Context

/dashboard, /admin, /learning

Level 2: Feature

/dashboard/packages, /dashboard/reports

Level 3: Detail or Action

/dashboard/packages/[id] (detail)
/dashboard/dispatch/create (action)

Level 4: Sub-feature (only when necessary)

/admin/packages/[id]/distribution (sub-feature)

Apply Consistently

Good Examples:

/dashboard/packages (Level 2) ✅
/dashboard/packages/[id] (Level 3) ✅
/dashboard/reports?tab=custom (Level 2 with query) ✅

Avoid:

/dashboard/feature/sub-feature/action (Level 4, too deep)
Use query params or tabs instead

Breadcrumb Implementation

Breadcrumb Structure

Pattern: Context > Category > Feature > Detail

Examples:

/dashboard/packages/[id] → Dashboard > Content > Packages > [Package Title]
/dashboard/reports?tab=custom → Dashboard > Analytics > Reports > Custom
/admin/packages/[id]/distribution → Admin > Data > Packages > [Title] > Distribution

Implementation:

<Breadcrumbs>
  <BreadcrumbItem href="/dashboard">Dashboard</BreadcrumbItem>
  <BreadcrumbItem href="/dashboard/content">Content</BreadcrumbItem>
  <BreadcrumbItem href="/dashboard/packages">Packages</BreadcrumbItem>
  <BreadcrumbItem current>{packageTitle}</BreadcrumbItem>
</Breadcrumbs>

Backward Compatibility

Route Preservation

Strategy: Keep all existing routes, add redirects where needed

Examples:

/dashboard/reports/custom → Redirect to /dashboard/reports?tab=custom
/dashboard/api-keys → Redirect to /dashboard/integrations?tab=api-keys
/learner/dashboard → Redirect to /learning/dashboard

Implementation:

// In page component or middleware
if (pathname === '/dashboard/reports/custom') {
  redirect('/dashboard/reports?tab=custom');
}

Gradual Migration

Phase 1: Add new routes, keep old routes working Phase 2: Update internal links to new routes Phase 3: Add redirects from old to new routes Phase 4: (Optional) Remove old routes after migration period

Implementation Plan

Phase 1: Add Missing Pages (Week 1)

Create /dashboard/settings page
Create /dashboard/content hub (optional)
Create /dashboard/packages/upload page (if UI upload needed)
Create /help page

Phase 2: Consolidate Pages (Week 2-3)

Consolidate Reports into unified page with tabs
Consolidate Integrations into unified page with tabs
Add breadcrumbs to all detail pages
Update navigation to new structure

Phase 3: Reorganize Routes (Week 4+)

Add hub pages (Content, Analytics, Integrations, Account)
Implement redirects from old to new routes
Update all internal links
Test backward compatibility

Success Metrics

Measurable Improvements

Route Consistency:
- Consistent patterns (target: 100%)
- Predictable URLs (target: >90% user prediction)
- No route confusion (target: <5% errors)
Page Consolidation:
- Reduced page count (target: 30% reduction)
- Unified interfaces (target: 3+ consolidations)
- User satisfaction (target: >4/5)
Navigation Efficiency:
- Clicks to feature (target: ≤2 clicks)
- Time to find page (target: <10 seconds)
- Breadcrumb usage (target: >50% users)

Summary

The proposed page organization addresses all identified issues:

✅ Logical Grouping: Feature-based organization
✅ Consistent Patterns: Uniform route structure
✅ Unified Interfaces: Tabs for related pages
✅ Clear Hierarchy: Consistent depth
✅ Backward Compatible: Preserve existing routes
✅ Missing Pages: Add Settings, Help, Upload UI
✅ Route Standardization: Consistent naming and depth
✅ Breadcrumbs: Show navigation path
✅ Consolidation: Reports, Integrations unified
✅ Hub Pages: Content, Analytics, Integrations, Account hubs

This organization provides a clear, consistent, and user-friendly page structure.