> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Navigation Quick Reference & Implementation Guide

> Last Updated: 2025-01-25 Status: Active

**Last Updated:** 2025-01-25\
**Status:** Active

> **Navigation Documentation Index:** For an overview of all navigation documentation, see [NAVIGATION\_GUIDE\_INDEX.md](../../development/NAVIGATION_GUIDE_INDEX.md)\
> **Navigation Standard:** For complete navigation standards and policies, see [NAVIGATION\_STANDARD.md](NAVIGATION_STANDARD.md)

**Quick Start:** This document provides step-by-step implementation tasks for navigation improvements and quick lookup reference.

***

## Phase 1: Foundation (Weeks 1-2)

### Task 1.1: Add Sub-Module Visual Indicators (Desktop)

**File:** `src/platform/navigation/components/InModuleSidebar.tsx`

**Changes:**

1. Add visual badge/indicator for sub-module groups
2. Show sub-module description on hover
3. Style sub-module groups differently

**Implementation:**

```typescript theme={null}
// In NavGroupWithOverview component
{group.isSubModule && (
  <Badge variant="secondary" className="ml-auto text-xs">
    Sub-Module
  </Badge>
)}
```

**Acceptance Criteria:**

* [ ] Sub-modules have visual indicator in desktop sidebar
* [ ] Description shows on hover/focus
* [ ] Visual distinction is clear but not overwhelming

***

### Task 1.2: Enhance Mobile Menu Sheet for Sub-Modules

**File:** `src/platform/navigation/MobileMenuSheet.tsx`

**Changes:**

1. Show sub-modules prominently in module section
2. Add sub-module quick actions
3. Improve sub-module context display

**Implementation:**

```typescript theme={null}
// Add sub-module section before "All Modules"
{module.navGroups?.some(g => g.isSubModule) && (
  <div className="space-y-2">
    <h3 className="text-sm font-medium">Sub-Modules</h3>
    {module.navGroups
      .filter(g => g.isSubModule)
      .map(subModule => (
        <SubModuleCard 
          key={subModule.id}
          subModule={subModule}
          parentModule={module}
        />
      ))}
  </div>
)}
```

**Acceptance Criteria:**

* [ ] Sub-modules visible in mobile menu
* [ ] Quick actions accessible
* [ ] Clear parent-child relationship

***

### Task 1.3: Document Navigation Standards

**File:** `docs/architecture/MODULE_NAVIGATION_STANDARD.md`

**Changes:**

1. Add navigation pattern decision tree
2. Document when to use navItems vs. navGroups vs. sub-modules
3. Add visual examples

**Acceptance Criteria:**

* [ ] Decision tree documented
* [ ] Examples for each pattern
* [ ] Guidelines for module creators

***

## Phase 2: HR Optimization (Weeks 3-4)

### Task 2.1: Make HR Groups Collapsible with Smart Defaults

**File:** `src/platform/navigation/components/InModuleSidebar.tsx`

**Changes:**

1. Make all HR groups collapsible (not just 5+)
2. Default: Open "People Management" and current sub-module
3. Remember collapsed state per user

**Implementation:**

```typescript theme={null}
// Update useCollapsible logic
const useCollapsible = visibleNavGroups.length >= 3 || 
  module.id === 'hr'; // HR always uses collapsible

// Smart defaults
const [isOpen, setIsOpen] = useState(
  hasActiveItem || 
  group.defaultOpen || 
  (module.id === 'hr' && group.id === 'people-management') ||
  false
);
```

**Acceptance Criteria:**

* [ ] All HR groups are collapsible
* [ ] Smart defaults work correctly
* [ ] State persists per user (future: localStorage)

***

### Task 2.2: Add Sub-Module Quick Actions to HR Overview

**File:** `src/platform/navigation/components/InModuleSidebar.tsx`

**Changes:**

1. Show sub-module quick actions in group header
2. Add module-level quick actions section
3. Make quick actions accessible from parent view

**Implementation:**

```typescript theme={null}
// In NavGroupWithOverview, show quick actions when group is sub-module
{group.isSubModule && group.quickActions && (
  <div className="flex gap-1 px-3 py-1">
    {group.quickActions.map(action => (
      <Button key={action.route} variant="outline" size="sm">
        <ActionIcon className="h-3 w-3" />
        {action.label}
      </Button>
    ))}
  </div>
)}
```

**Acceptance Criteria:**

* [ ] Quick actions visible in group header
* [ ] Quick actions work correctly
* [ ] Mobile-friendly touch targets

***

### Task 2.3: Improve Mobile Sub-Module Discovery

**File:** `src/platform/navigation/MobileMenuSheet.tsx`

**Changes:**

1. Add "Enter Sub-Module" buttons in mobile menu
2. Show sub-module preview cards
3. Improve sub-module context in header

**Implementation:**

```typescript theme={null}
// Add sub-module cards in module section
{module.navGroups
  .filter(g => g.isSubModule)
  .map(subModule => (
    <div key={subModule.id} className="border rounded-lg p-3">
      <div className="flex items-center gap-2 mb-2">
        <SubModuleIcon className="h-4 w-4" />
        <span className="font-medium">{subModule.label}</span>
      </div>
      <p className="text-xs text-muted-foreground mb-2">
        {subModule.description}
      </p>
      <Button 
        variant="outline" 
        size="sm"
        onClick={() => handleNavigation(subModule.overviewRoute)}
      >
        Enter {subModule.label}
      </Button>
    </div>
  ))}
```

**Acceptance Criteria:**

* [ ] Sub-modules discoverable in mobile menu
* [ ] Clear entry points
* [ ] Preview information helpful

***

### Task 2.4: Add HR Sub-Module to Mobile Bottom Nav Config

**File:** `src/platform/navigation/mobile-nav-config.ts`

**Changes:**

1. Add HR sub-module shortcuts to available shortcuts
2. Allow users to customize which sub-module appears
3. Update default shortcuts if needed

**Implementation:**

```typescript theme={null}
// Add to AVAILABLE_SHORTCUTS
{
  id: "hr-compliance",
  label: "Compliance",
  icon: ShieldCheck,
  route: "/hr/compliance",
  permission: "hr.compliance.view",
  category: "sub-module",
  parentModule: "hr",
  subModuleId: "compliance",
},
```

**Acceptance Criteria:**

* [ ] HR sub-modules available in bottom nav config
* [ ] Users can customize
* [ ] Permissions respected

***

## Phase 3: Cross-Module Consistency (Weeks 5-6)

### Task 3.1: Update Module Flyout for Sub-Modules

**File:** `src/platform/navigation/components/ModuleFlyout.tsx`

**Changes:**

1. Show sub-modules with visual distinction
2. Include sub-module quick actions
3. Add "Enter Sub-Module" action

**Implementation:**

```typescript theme={null}
// In CollapsibleNavGroupSection
{group.isSubModule && (
  <div className="flex items-center gap-2 px-3 py-1 bg-primary/5 rounded">
    <Badge variant="secondary" className="text-xs">Sub-Module</Badge>
    {group.quickActions && (
      <div className="flex gap-1 ml-auto">
        {group.quickActions.slice(0, 2).map(action => (
          <Button key={action.route} variant="ghost" size="sm">
            <ActionIcon className="h-3 w-3" />
          </Button>
        ))}
      </div>
    )}
  </div>
)}
```

**Acceptance Criteria:**

* [ ] Sub-modules visible in flyout
* [ ] Quick actions accessible
* [ ] Visual distinction clear

***

### Task 3.2: Standardize Mobile Menu Sheet

**File:** `src/platform/navigation/MobileMenuSheet.tsx`

**Changes:**

1. Consistent layout for all modules
2. Sub-module section standardized
3. Improved search includes sub-modules

**Implementation:**

```typescript theme={null}
// Standardize module rendering
const renderModule = (module: ModuleDefinition) => {
  const hasSubModules = module.navGroups?.some(g => g.isSubModule);
  
  return (
    <div className="space-y-2">
      <ModuleHeader module={module} />
      {hasSubModules && (
        <SubModulesSection 
          subModules={module.navGroups.filter(g => g.isSubModule)}
        />
      )}
      <ModuleNavItems module={module} />
    </div>
  );
};
```

**Acceptance Criteria:**

* [ ] Consistent layout across modules
* [ ] Sub-modules always visible when present
* [ ] Search works for sub-modules

***

### Task 3.3: Review and Align All Modules

**Files:** `src/platform/modules/module-registry.ts` (all modules)

**Changes:**

1. Review each module against standards
2. Align navigation patterns
3. Ensure consistency

**Checklist per Module:**

* [ ] Uses appropriate pattern (navItems vs. navGroups vs. sub-modules)
* [ ] Groups are logical and scannable
* [ ] Sub-modules have overviewRoute and quickActions
* [ ] Permissions are correct
* [ ] Mobile shortcuts configured (if applicable)

**Modules to Review:**

* [ ] HR (already optimized in Phase 2)
* [ ] RH
* [ ] FA
* [ ] FW
* [ ] LO
* [ ] FM
* [ ] GR

***

## Phase 4: Advanced Features (Weeks 7-8)

### Task 4.1: Navigation Customization UI

**File:** `src/platform/navigation/components/NavigationCustomizer.tsx` (new)

**Changes:**

1. Create navigation customization component
2. Allow pinning favorite sub-modules
3. Customize group order
4. Hide unused groups

**Implementation:**

```typescript theme={null}
// New component structure
export function NavigationCustomizer() {
  const { currentModule } = useNavigation();
  const [pinnedItems, setPinnedItems] = useState<string[]>([]);
  const [hiddenGroups, setHiddenGroups] = useState<string[]>([]);
  
  // Save preferences to user profile
  const savePreferences = async () => {
    // Store in pf_user_preferences table
  };
  
  return (
    <Dialog>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Customize Navigation</DialogTitle>
        </DialogHeader>
        <div className="space-y-4">
          <PinnedItemsSection />
          <GroupOrderSection />
          <HiddenGroupsSection />
        </div>
      </DialogContent>
    </Dialog>
  );
}
```

**Acceptance Criteria:**

* [ ] Users can customize navigation
* [ ] Preferences persist
* [ ] Mobile and desktop supported

***

### Task 4.2: Enhance Global Search with Sub-Modules

**File:** `src/platform/navigation/components/GlobalSearch.tsx` (or create new)

**Changes:**

1. Include sub-modules in search results
2. Show sub-module context in results
3. Quick navigation to sub-modules

**Implementation:**

```typescript theme={null}
// In search results
const searchResults = useMemo(() => {
  const allResults = [
    ...modules,
    ...modules.flatMap(m => 
      m.navGroups
        ?.filter(g => g.isSubModule)
        .map(sub => ({
          ...sub,
          parentModule: m.name,
          category: 'sub-module',
        })) || []
    ),
    // ... other results
  ];
  
  return filterResults(allResults, query);
}, [query]);
```

**Acceptance Criteria:**

* [ ] Sub-modules appear in search
* [ ] Context is clear
* [ ] Navigation works correctly

***

### Task 4.3: Usage Analytics Integration

**File:** `src/platform/navigation/hooks/useNavigationAnalytics.ts` (new)

**Changes:**

1. Track navigation usage
2. Identify pain points
3. Create analytics dashboard

**Implementation:**

```typescript theme={null}
export function useNavigationAnalytics() {
  const trackNavigation = (event: NavigationEvent) => {
    // Send to analytics service
    analytics.track('navigation', {
      module: event.module,
      subModule: event.subModule,
      route: event.route,
      timestamp: Date.now(),
    });
  };
  
  return { trackNavigation };
}
```

**Acceptance Criteria:**

* [ ] Navigation events tracked
* [ ] Analytics dashboard created
* [ ] Privacy-compliant (no PHI)

***

## Testing Checklist

### Desktop Testing

* [ ] All modules render correctly
* [ ] Sub-modules have visual indicators
* [ ] Collapsible groups work
* [ ] Quick actions accessible
* [ ] Keyboard navigation works
* [ ] Screen reader compatible

### Mobile Testing

* [ ] Mobile menu shows sub-modules
* [ ] Touch targets meet 44px minimum
* [ ] Sub-module navigation works
* [ ] Breadcrumbs display correctly
* [ ] Bottom nav customizable
* [ ] Safe area insets respected

### Cross-Module Testing

* [ ] All modules follow standards
* [ ] Navigation patterns consistent
* [ ] Permissions respected
* [ ] Performance acceptable

***

## Rollout Strategy

### Phase 1 Rollout

1. Deploy to staging
2. Internal testing (1 week)
3. Beta users (1 week)
4. Production release

### Phase 2 Rollout

1. Deploy HR improvements to staging
2. HR team testing (1 week)
3. All users (gradual rollout)

### Phase 3 Rollout

1. Deploy all module improvements
2. User communication
3. Training materials
4. Support documentation

### Phase 4 Rollout

1. Feature flags for customization
2. Opt-in beta
3. Gradual rollout
4. Analytics monitoring

***

## Success Criteria

### Phase 1

* [ ] Sub-modules visually distinct
* [ ] Mobile menu improved
* [ ] Standards documented

### Phase 2

* [ ] HR navigation optimized
* [ ] User feedback positive
* [ ] No regression in other modules

### Phase 3

* [ ] All modules consistent
* [ ] Navigation patterns standardized
* [ ] User experience improved

### Phase 4

* [ ] Customization available
* [ ] Search enhanced
* [ ] Analytics providing insights

***

## Support & Documentation

### User Documentation

* [ ] Navigation guide for users
* [ ] Sub-module explanation
* [ ] Customization tutorial
* [ ] FAQ updates

### Developer Documentation

* [ ] Navigation standards updated
* [ ] Module creation guide
* [ ] Sub-module implementation guide
* [ ] API documentation

### Training Materials

* [ ] Video tutorials
* [ ] Screenshots
* [ ] Step-by-step guides
* [ ] Best practices

***

**Quick Reference Status:** Ready for Implementation\
**Next Review:** After Phase 1 completion