# Activity Logs & System Logs UI Features

**Last Updated**: October 2025  
**Status**: ✅ Complete and Production-Ready

## Table of Contents

1. [Overview](#overview)
2. [Color Coding System](#color-coding-system)
3. [Log Navigation Controls](#log-navigation-controls)
4. [Phase Badges](#phase-badges)
5. [Visual Grouping](#visual-grouping)
6. [Column Optimizations](#column-optimizations)
7. [Implementation Details](#implementation-details)

---

## Overview

The Activity Logs and System Logs UI implements a comprehensive visual system to help users quickly understand and navigate operation logs. The system includes:

- **Consistent Color Coding**: Operation-specific colors across toolbar buttons, dialog headers, and log entries
- **Visual Grouping**: Alternating backgrounds for related log entries
- **Navigation Controls**: Browse through logs without closing the modal
- **Phase Badges**: Clear indication of operation stages
- **Category-Based Operation Filters**: Upload/Download/AI Indexing/Copy-Move/Delete/Create-Modify/Sync/Backup filters that hide batch and control implementation details
- **Optimized Layout**: Streamlined columns for better readability
- **Warning Diagnostics Normalization**: Pathless rclone notices such as `NOTICE: Failed to copy: internal error ...` are rendered as provider reasons instead of being mis-labeled as fake filenames or timestamps
- **Jobs Queue Lifecycle Coverage**: Backup and sync job creation/deletion plus AI indexing cancel, retry, single dismiss, and completed-job batch dismiss controls are written to both user activity logs and system audit logs so queue changes remain traceable after a job row is removed
- **AI Indexing Outcome Summaries**: AI indexing log rows and detail dialogs show eligible-file coverage, eligible failures/skips, and unsupported-by-policy counts separately instead of treating unsupported formats as operational failures

---

## Color Coding System

### Purpose

Provide visual consistency across the entire application using operation-specific colors for:
- Toolbar buttons (ContentToolbar, SearchActionToolbar)
- Dialog headers (Copy, Move, Delete, Rename, Upload, Download)
- Activity logs (user activity tracking)
- System logs (system operation logging)
- Operation badges (status indicators)

### Centralized Color System

**File**: `src/lib/operation-colors.ts`

Provides:
- Type-safe operation type definitions
- Consistent color schemes for buttons, headers, icons, and borders
- Helper functions: `getButtonColors()`, `getHeaderColors()`, `getIconColors()`, `getBorderColors()`

### Operation Type Colors

All colors work in both light and dark modes with WCAG-compliant contrast ratios.

| Operation | Color | Light Mode | Dark Mode |
|-----------|-------|------------|-----------|
| **Upload** | Blue | `bg-blue-50 text-blue-700` | `bg-blue-950/30 text-blue-300` |
| **Download** | Green | `bg-green-50 text-green-700` | `bg-green-950/30 text-green-300` |
| **AI Indexing** | Emerald | `bg-emerald-50 text-emerald-700` | `bg-emerald-950/30 text-emerald-300` |
| **AI Indexing Controls** | Emerald | `bg-emerald-50 text-emerald-700` | `bg-emerald-950/30 text-emerald-300` |
| **Copy** | Purple | `bg-purple-50 text-purple-700` | `bg-purple-950/30 text-purple-300` |
| **Move** | Indigo | `bg-indigo-50 text-indigo-700` | `bg-indigo-950/30 text-indigo-300` |
| **Delete** | Red | `bg-red-50 text-red-700` | `bg-red-950/30 text-red-300` |
| **Create Folder** | Amber | `bg-amber-50 text-amber-700` | `bg-amber-950/30 text-amber-300` |
| **Rename** | Cyan | `bg-cyan-50 text-cyan-700` | `bg-cyan-950/30 text-cyan-300` |
| **Sync** | Teal | `bg-teal-50 text-teal-700` | `bg-teal-950/30 text-teal-300` |
| **Backup** | Emerald | `bg-emerald-50 text-emerald-700` | `bg-emerald-950/30 text-emerald-300` |

### Log Source Differentiation

Logs are visually distinguished by their source:

**User Activity Logs:**
- Blue accent border (4px left border)
- Default background color
- Subtle muted background on hover
- User icon

**System Audit Logs:**
- Orange accent border (4px left border)
- Subtle slate background
- Darker slate background on hover
- Shield icon

### Core Utilities

**File**: `src/lib/log-styling.ts`

Provides:
- Type definitions: `LogSource`, `OperationCategory`, `OperationColorScheme`
- Color schemes for 18 operation types
- 7 operation categories for logical grouping
- Dark mode support
- Icon mapping from lucide-react

### Component Library

#### OperationBadge
**File**: `src/components/logs/OperationBadge.tsx`

Displays operation type with color coding and icon.

Features:
- Three size variants (sm, md, lg)
- Optional icon display
- Tooltip with detailed information
- Compact icon-only variant (`OperationIconBadge`)

#### LogSourceIndicator
**File**: `src/components/logs/LogSourceIndicator.tsx`

Visual indicator for log source type.

Features:
- Three display variants (badge, label, icon)
- Distinct colors for each source type
- User icon for activity logs, Shield icon for system logs

#### StyledLogRow
**File**: `src/components/logs/StyledLogRow.tsx`

Table row component with visual differentiation.

Features:
- Colored left border accent (4px)
- Different background colors for each source
- Hover state styling
- Optional border accent toggle

#### LogColorLegend
**File**: `src/components/logs/LogColorLegend.tsx`

Collapsible legend explaining the color coding system.

Features:
- Expandable/collapsible interface
- Groups operations by category
- Shows all operation types with their colors
- Accessibility information section

---

## Log Navigation Controls

### Overview

Navigation controls in the log details modal allow users to browse through log entries sequentially without closing the modal.

**Date**: October 2025

### Motivation

Previously, users had to:
1. Click "View" to open a log entry
2. Review the details
3. Close the modal
4. Scroll to find the next entry
5. Click "View" again

This workflow was inefficient when reviewing multiple log entries sequentially.

### Solution

Added navigation controls that allow users to:
- Navigate to the previous/next log entry with button clicks
- See their current position in the log list
- Use keyboard shortcuts for faster navigation
- Navigate while respecting current filters and sort order

### UI Components

#### Navigation Buttons
- **Previous Button**: `ChevronLeft` icon, positioned in modal header
- **Next Button**: `ChevronRight` icon, positioned in modal header
- **Position Indicator**: Shows "X of Y" (e.g., "5 of 23")
- **Button States**: Disabled when at first/last entry

#### Visual Layout
```
┌─────────────────────────────────────────────────────────────┐
│ Activity details                    5 of 23  [<] [>]    [X] │
│ Oct 02, 2025, 08:38:37 PM                                   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ [Log entry details...]                                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Keyboard Shortcuts

- **Arrow Left** / **Arrow Right**: Navigate between entries
- **Escape**: Close modal
- **Home**: Jump to first entry
- **End**: Jump to last entry

### Implementation

**Files Modified:**
- `src/app/user/activity/page.tsx` - Activity logs page
- `src/app/dev/system-logs/page.tsx` - System logs page
- `src/components/logs/LogDetailsModal.tsx` - Modal component

**State Management:**
- Current log index tracked in parent component
- Navigation callbacks passed to modal
- Filtered/sorted log list used for navigation

---

## Phase Badges

### Overview

Enhanced the log details modal to display phase information prominently when the operation status is "pending".

**Date**: October 2025

### Problem Statement

Previously, when a log entry had status "pending" and a phase ("start", "progress", "complete", "error"), the modal only displayed the status badge. The phase information was buried in the details grid below.

### Solution

Display the status badge ("pending") alongside a separate phase badge ("start", "progress", etc.).

**Benefits:**
- Clear separation of concerns
- Easy to scan
- Follows existing pattern (Operation + Status badges)
- Allows phase-specific color coding
- Flexible for future enhancements

### Phase Color Schemes

**File**: `src/lib/log-styling.ts`

| Phase | Color | Icon | Label |
|-------|-------|------|-------|
| **start** | Blue outline | PlayCircle | Start |
| **progress** | Amber | Loader2 | Progress |
| **complete** | Green | CheckCircle | Complete |
| **error** | Red | XCircle | Error |

### Visual Example

```
┌─────────────────────────────────────────────────────────────┐
│ Activity details                                        [X] │
│ Oct 02, 2025, 08:38:37 PM                                   │
│                                                             │
│ [Copy] [Pending] [Progress]  ← Three badges                │
│                                                             │
│ Details...                                                  │
└─────────────────────────────────────────────────────────────┘
```

### Implementation

**Files Modified:**
- `src/lib/log-styling.ts` - Added `PHASE_COLOR_SCHEMES`
- `src/components/logs/LogDetailsModal.tsx` - Added phase badge rendering
- `src/components/ui/badge.tsx` - Enhanced badge component

---

## Visual Grouping

### Overview

Log entries that belong to the same operation/request are visually grouped with alternating backgrounds.

**Date**: October 2025

### Grouping Logic

- **Primary**: Entries with the same `requestId` are grouped together
- **Secondary**: Entries with the same `operationId` (if no `requestId`)
- **Fallback**: Each entry is its own group

### Visual Pattern

- **Group 1**: Default background
- **Group 2**: Subtle alternate background (`bg-slate-100/70 dark:bg-slate-800/20`)
- **Group 3**: Default background
- **Group 4**: Subtle alternate background
- Pattern continues alternating...

### Benefits

- Easier to visually scan logs and identify operation boundaries
- Quickly see which entries belong to the same request
- Especially helpful when multiple operations are interleaved
- Works seamlessly with existing color coding system

### Example Scenario

```
Request A (Delete): 3 entries → Default background
Request B (Copy):   2 entries → Alternate background
Request C (Move):   1 entry   → Default background
Request D (Upload): 4 entries → Alternate background
```

### Implementation

**Files Modified:**
- `src/app/user/activity/page.tsx` - Added grouping logic
- `src/app/dev/system-logs/page.tsx` - Added grouping logic
- `src/components/logs/StyledLogRow.tsx` - Added background alternation

---

## Column Optimizations

### Overview

Streamlined the log table columns for better readability and efficient use of space.

**Date**: October 2025

### Changes Made

#### 1. Phase Column Addition
- Added dedicated "Phase" column for pending operations
- Shows current operation stage (start, progress, complete, error)
- Only visible when relevant (pending operations)

#### 2. Duration Column Simplification
- Removed redundant "Duration" label
- Shows just the time value (e.g., "2.5s" instead of "Duration: 2.5s")
- Cleaner, more scannable format

#### 3. Optimized Column Widths
- **Timestamp**: Wider for full date/time display
- **Operation**: Compact with icon badges
- **Status**: Minimal width for status badges
- **Phase**: Conditional display
- **Duration**: Compact numeric display
- **Actions**: Fixed width for buttons

### Visual Comparison

**Before:**
```
| Timestamp | Operation | Status | Duration: 2.5s | Actions |
```

**After:**
```
| Timestamp | Operation | Status | Phase | 2.5s | Actions |
```

### Implementation

**Files Modified:**
- `src/app/user/activity/page.tsx` - Updated column definitions
- `src/app/dev/system-logs/page.tsx` - Updated column definitions

---

## Implementation Details

### Files Created

1. `src/lib/operation-colors.ts` - Centralized color system
2. `src/lib/log-styling.ts` - Log styling utilities
3. `src/components/logs/OperationBadge.tsx` - Operation badge component
4. `src/components/logs/LogSourceIndicator.tsx` - Log source indicator
5. `src/components/logs/StyledLogRow.tsx` - Styled table row
6. `src/components/logs/LogColorLegend.tsx` - Color legend component
7. `src/components/logs/LogDetailsModal.tsx` - Enhanced modal with navigation
8. `src/components/logs/operation-category-filters.ts` - Shared operation category filter mapping

### Files Modified

1. `src/app/user/activity/page.tsx` - Activity logs page
2. `src/app/dev/system-logs/page.tsx` - System logs page
3. `src/components/ui/badge.tsx` - Enhanced badge component
4. `src/components/ContentToolbar.tsx` - Applied color scheme
5. `src/components/SearchActionToolbar.tsx` - Applied color scheme

### Testing

- ✅ Visual regression testing with Storybook
- ✅ Accessibility testing (WCAG compliance)
- ✅ Dark mode compatibility
- ✅ Keyboard navigation testing
- ✅ Responsive design testing

---

## Activity Logs Partial Search Testing

### Overview

The activity logs search functionality supports partial matching (substring search) for both operationId and requestId fields. This allows users to search using any portion of these long UUID identifiers.

### Features

#### 1. Partial Matching
- Users can type just a portion of an operationId or requestId
- Search works with the beginning, middle, or end of the ID string
- Uses SQL ILIKE for case-insensitive pattern matching

#### 2. Case-Insensitive Search
- Search is case-insensitive for better usability
- "6B24AA81" will match "6b24aa81-0de9-4235-8923-8ceaf751f819"

#### 3. Special Character Escaping
- SQL LIKE wildcards (%, _) are properly escaped
- Prevents SQL injection and unexpected behavior

#### 4. OR Logic Maintained
- Search queries both operationId and requestId fields
- Returns results that match either field

### Manual Testing Steps

#### Test 1: Partial Match at Beginning
1. Navigate to `/user/activity`
2. In the search field, type: `6b24aa81`
3. Expected: Should find logs with operationId starting with "6b24aa81-..."
4. Verify: Results are filtered correctly

#### Test 2: Partial Match in Middle
1. Clear the search field
2. Type: `8923-8ceaf751`
3. Expected: Should find logs containing this substring in operationId or requestId
4. Verify: Results include logs with IDs containing this pattern

#### Test 3: Partial Match at End
1. Clear the search field
2. Type: `f819` (last part of an ID)
3. Expected: Should find logs with IDs ending in "f819"
4. Verify: Results are filtered correctly

#### Test 4: Case-Insensitive Search
1. Clear the search field
2. Type: `6B24AA81` (uppercase)
3. Expected: Should find the same results as lowercase "6b24aa81"
4. Verify: Case doesn't affect search results

#### Test 5: Request ID Search
1. Clear the search field
2. Type a partial requestId (e.g., `8bb891c1`)
3. Expected: Should find all logs with that requestId
4. Verify: Multiple related logs are returned (start, progress, complete phases)

#### Test 6: Very Short Search
1. Clear the search field
2. Type: `6b2` (very short partial)
3. Expected: Should find all logs containing "6b2" in operationId or requestId
4. Verify: Results may include multiple different operations

#### Test 7: No Results
1. Clear the search field
2. Type: `xyz123nonexistent`
3. Expected: Should show "No activity logs found yet."
4. Verify: Empty state is displayed correctly

#### Test 8: Clear Search
1. After any search, clear the search field completely
2. Expected: All logs should be displayed again
3. Verify: Full list is restored

#### Test 9: Special Characters (Edge Case)
1. Clear the search field
2. Type: `test%search` (contains SQL wildcard)
3. Expected: Should search for literal "test%search", not use % as wildcard
4. Verify: No SQL errors, proper escaping

### Example Test Data

#### Suggested Partial Searches:
- `6b24aa81` - Beginning of operation ID
- `8923-8ceaf751` - Middle portion of operation ID
- `f819` - End of operation ID
- `8bb891c1` - Beginning of request ID
- `25c1-498f` - Middle portion of request ID
- `1a3` - End of request ID

### Expected Behavior

**Successful Search:**
- Results appear immediately as you type
- Matching IDs are highlighted in the results
- Both operationId and requestId columns are searched
- Case doesn't matter

**No Results:**
- "No activity logs found yet." message is displayed
- No errors in console
- Search field remains functional

**Edge Cases:**
- Very short searches (1-2 characters) may return many results
- Special characters are treated as literals, not wildcards
- Empty search shows all logs

---

## Related Documentation

- [System Logs](./SYSTEM_LOGS.md) - Operation and system logging
- [Path Resolution](./PATH_RESOLUTION.md) - Comprehensive path resolution guide
- [Architecture](./ARCHITECTURE.md) - Overall system architecture
- [Testing](./TESTING.md) - Testing strategies

---

**Implementation Complete**: October 2025  
**Status**: ✅ Production-Ready  
**Coverage**: All activity and system log pages