youtube-summarizer/docs/stories/3.3.summary-history-management.md

Story 3.3: Summary History Management

Status

Ready for Implementation

Story

As an authenticated user
I want to view and manage my summary history
So that I can reference previous summaries, search through them, and organize my video insights

Acceptance Criteria

1. History Display: Summary history displays in reverse chronological order with pagination
2. Search Functionality: Filter summaries by video title, content, date range, or AI model used
3. Favorites System: Users can star/favorite summaries for quick access
4. Bulk Operations: Support bulk delete and export with confirmation dialogs
5. Summary Sharing: Generate shareable links (public or private) for individual summaries
6. Export Options: Export entire history or filtered results as JSON, CSV, or ZIP archive
7. Summary Management: Edit summary titles, add notes, and organize with tags
8. Usage Statistics: Display summary count, total videos processed, and cost tracking

Technical Requirements

Backend Implementation

Database Schema Updates

# Add to Summary model (backend/models/summary.py)
is_starred = Column(Boolean, default=False, index=True)
notes = Column(Text)  # User's personal notes
tags = Column(JSON)  # Array of user tags
shared_token = Column(String(64), unique=True, nullable=True)  # For sharing
is_public = Column(Boolean, default=False)
view_count = Column(Integer, default=0)

# Add indexes for performance
Index('idx_user_starred', 'user_id', 'is_starred')
Index('idx_user_created', 'user_id', 'created_at')

API Endpoints (backend/api/summaries.py)

router = APIRouter(prefix="/api/summaries", tags=["summaries"])

# GET /api/summaries - List user's summaries with filters
# GET /api/summaries/{id} - Get single summary
# PUT /api/summaries/{id} - Update summary (star, notes, tags)
# DELETE /api/summaries/{id} - Delete single summary
# POST /api/summaries/bulk-delete - Delete multiple summaries
# GET /api/summaries/search - Advanced search
# GET /api/summaries/starred - Get starred summaries
# POST /api/summaries/{id}/share - Generate share link
# GET /api/summaries/shared/{token} - Access shared summary
# GET /api/summaries/export - Export summaries
# GET /api/summaries/stats - User statistics

Frontend Implementation

Components Structure

frontend/src/
├── pages/
│   └── history/
│       ├── SummaryHistoryPage.tsx    # Main history page
│       └── SharedSummaryPage.tsx     # Public share view
├── components/
│   └── summaries/
│       ├── SummaryList.tsx          # List with pagination
│       ├── SummaryCard.tsx          # Individual summary card
│       ├── SummarySearch.tsx        # Search and filters
│       ├── SummaryDetails.tsx       # Full summary view
│       ├── SummaryActions.tsx       # Star, share, delete actions
│       ├── BulkActions.tsx          # Bulk operations toolbar
│       ├── ExportDialog.tsx         # Export configuration
│       └── UsageStats.tsx           # Statistics display
└── hooks/
    ├── useSummaryHistory.ts         # History data fetching
    ├── useSummarySearch.ts          # Search functionality
    └── useSummaryActions.ts         # CRUD operations

Tasks / Subtasks

Task 1: Database Schema Updates (4 hours)

• Add new columns to Summary model (starred, notes, tags, sharing)
• Create database migration with Alembic
• Add indexes for performance optimization
• Update model relationships and validators

Task 2: Backend API Implementation (8 hours)

• Create summaries.py router with all endpoints
• Implement pagination with cursor-based approach
• Add search functionality with full-text search
• Implement sharing token generation and validation
• Create export service for multiple formats
• Add usage statistics aggregation
• Implement proper authorization checks
• Add rate limiting for export operations

Task 3: Frontend History Page (6 hours)

• Create SummaryHistoryPage with routing
• Implement SummaryList with infinite scroll
• Build SummaryCard with preview and actions
• Add loading states and empty states
• Implement responsive grid layout
• Add keyboard navigation support

Task 4: Search and Filtering (4 hours)

• Create SummarySearch component with filters
• Implement date range picker
• Add tag-based filtering
• Create saved search functionality
• Implement search highlighting in results

Task 5: Summary Actions (4 hours)

• Implement star/unstar functionality
• Create share dialog with options
• Add copy-to-clipboard for share links
• Implement delete with confirmation
• Add bulk selection interface
• Create bulk operations toolbar

Task 6: Export Functionality (4 hours)

• Create ExportDialog component
• Implement format selection (JSON, CSV, ZIP)
• Add date range and filter options
• Show export progress
• Handle large exports with streaming

Task 7: Usage Statistics (2 hours)

• Create UsageStats component
• Display summary count and trends
• Show cost tracking if available
• Add time-based analytics charts

Task 8: Testing & Documentation (4 hours)

• Write unit tests for API endpoints
• Add integration tests for history flow
• Create frontend component tests
• Update API documentation
• Add user documentation

Dependencies

Technical Dependencies

• Story 3.1: User Authentication (✅ Complete)
• Story 3.2: Frontend Auth Integration (✅ Complete)
• Database models with user relationships
• Authentication middleware
• Export service from Epic 2

External Dependencies

• React Query for data fetching
• Tanstack Table for data grid
• date-fns for date handling
• Chart.js for statistics visualization

Definition of Done

• All database migrations applied successfully
• API endpoints return correct data with proper pagination
• Search functionality works across title, content, and tags
• Starring system persists and filters correctly
• Bulk operations handle edge cases gracefully
• Share links work for both authenticated and public access
• Export generates valid files in all formats
• Frontend displays history with smooth scrolling
• All actions show appropriate loading states
• Mobile responsive design works correctly
• Unit tests pass with >80% coverage
• Integration tests verify complete flows
• Performance: Page loads in <2 seconds with 100+ summaries
• Accessibility: WCAG 2.1 AA compliance
• Documentation updated

Notes

Implementation Considerations

1. Performance: Use cursor-based pagination for large datasets
2. Caching: Implement Redis caching for frequently accessed summaries
3. Search: Consider full-text search with PostgreSQL or Elasticsearch
4. Export: Stream large exports to prevent memory issues
5. Sharing: Use signed URLs with expiration for security
6. Mobile: Implement swipe gestures for mobile actions

Future Enhancements

• Collaborative folders for team sharing
• Summary collections/playlists
• Advanced analytics dashboard
• Integration with note-taking apps
• Automated summary recommendations
• Version history for edited summaries

Design Mockup Structure

┌─────────────────────────────────────────────┐
│ 🎬 Summary History                    [Stats] │
├─────────────────────────────────────────────┤
│ [Search...] [Date] [Tags] [Model] [Export]  │
├─────────────────────────────────────────────┤
│ [✓] Select All  [★ Star] [🗑 Delete] [↗ Share]│
├─────────────────────────────────────────────┤
│ ┌──────────────┐ ┌──────────────┐          │
│ │ Video Title   │ │ Video Title   │          │
│ │ ★ 2 days ago │ │   5 days ago  │          │
│ │ Summary...   │ │ Summary...    │          │
│ │ [View] [···] │ │ [View] [···]  │          │
│ └──────────────┘ └──────────────┘          │
│                                              │
│           [Load More]                        │
└─────────────────────────────────────────────┘

Estimated Time: 36 hours

Priority: High - Core user experience feature Risk: Medium - Requires careful database design and performance optimization