Skip to Content
📚 MyStoryFlow Docs — Your guide to preserving family stories
Use Cases & TestingTimeline System Flow

Timeline System Flow - Business Rules & Test Cases

Flow Overview

The Timeline System provides a comprehensive activity feed for family groups, displaying chronological events related to family activities including gift purchases, member management, story creation, and achievements.

Flow Types

  • Family Member Access: Authenticated family members can view timeline events based on their role
  • Event Creation: Automatic timeline event creation triggered by user actions
  • Event Display: Real-time timeline display with filtering and pagination

Core Principles

  • Timeline events are created automatically when significant family actions occur
  • Event visibility is controlled by family member roles and permissions
  • Events are displayed in reverse chronological order (newest first)
  • System supports pagination for performance with large event histories

Step-by-Step Rules

Step 1: Timeline Event Creation

BR-TL-001: Automatic Event Generation

  • Rule: Timeline events are created automatically when users perform significant actions (gift purchases, member additions, story creation, etc.)
  • Implementation: TimelineEventService.logEvent() called from action handlers
  • Test: Verify event creation occurs for each supported action type
  • Rationale: Provides seamless activity tracking without requiring manual user input

BR-TL-002: Event Type Classification

  • Rule: All events must have a valid EventType from the predefined enum (gift_purchased, member_added, story_created, etc.)
  • Implementation: EventType enum in event-types.ts with type guards
  • Test: Attempt to create events with invalid types should fail
  • Rationale: Ensures consistent event categorization and proper UI rendering

BR-TL-003: Metadata Validation

  • Rule: Each event type has specific required metadata fields that must be validated before storage
  • Implementation: validateEventContext() function with type-specific validation
  • Test: Events with missing required metadata should fail validation
  • Rationale: Maintains data integrity and enables rich event display

BR-TL-004: Permission-Based Event Creation

  • Rule: Users can only create timeline events for families they are members of
  • Implementation: checkEventCreationPermission() verifies family membership
  • Test: Non-members attempting to create events should receive permission errors
  • Rationale: Prevents unauthorized event creation and maintains family privacy

Step 2: Timeline Event Display

BR-TL-005: Role-Based Event Visibility

  • Rule: Timeline events are filtered based on user role and event visibility rules
  • Implementation: EVENT_VISIBILITY_RULES with role-based access control
  • Test: Users should only see events their role permits
  • Rationale: Maintains appropriate privacy levels for different types of family activities

BR-TL-006: Chronological Ordering

  • Rule: Timeline events are displayed in reverse chronological order (newest first)
  • Implementation: Database query with ORDER BY created_at DESC
  • Test: Verify events appear in correct temporal sequence
  • Rationale: Most recent activities are most relevant to users

BR-TL-007: Pagination Support

  • Rule: Timeline supports pagination with configurable limit and offset parameters
  • Implementation: EventRetrievalOptions with limit/offset and hasMore calculation
  • Test: Verify pagination works correctly with large event sets
  • Rationale: Maintains performance with large timeline histories

BR-TL-008: Event Type Filtering

  • Rule: Users can filter timeline events by event type (gifts, members, stories, etc.)
  • Implementation: TimelineFilters component with eventTypes array parameter
  • Test: Filtering should show only events of selected types
  • Rationale: Allows users to focus on specific types of family activities

Step 3: Timeline Event Interaction

BR-TL-009: Event Reactions

  • Rule: Family members can react to timeline events with emoji reactions
  • Implementation: Event reaction handling in TimelineEventCard component
  • Test: Reactions should increment/decrement counters appropriately
  • Rationale: Enables family engagement and celebration of activities

BR-TL-010: Event Comments

  • Rule: Family members can comment on timeline events (placeholder implementation)
  • Implementation: Comment section in TimelineEventCard (currently placeholder)
  • Test: Comment functionality when implemented
  • Rationale: Facilitates family conversation around shared activities

BR-TL-011: Achievement Event Highlighting

  • Rule: Achievement-type events receive special visual treatment with celebration styling
  • Implementation: Special styling for achievement_earned, streak_milestone, collaboration_milestone
  • Test: Achievement events should have distinct visual appearance
  • Rationale: Celebrates important family milestones prominently

Timeline Access

  • Users access family timelines through the family page timeline tab
  • Timeline loading shows skeleton placeholders during data fetch
  • Error states provide user-friendly messages with retry options

Infinite Scroll

  • Timeline supports infinite scroll for seamless browsing
  • Load more trigger activates when user scrolls near bottom
  • Loading indicators show during additional data fetch

Filter Controls

  • Event type filters are accessible via TimelineFilters component
  • Filter changes immediately update displayed events
  • Clear filter option returns to showing all event types

Data Persistence

Event Storage

  • Timeline events stored in timeline_events table with full metadata
  • Events linked to family_group_id for family-scoped access
  • Actor information enriched from profiles table

State Management

  • Timeline state managed via useFamilyTimeline React hook
  • Local state includes events array, loading states, and pagination info
  • Event reactions stored locally (placeholder for future backend integration)

Caching Strategy

  • Timeline events cached in React component state
  • New events prepended to existing timeline
  • Cache invalidated on family membership changes

API Integration

Timeline Endpoint

  • GET /api/family/timeline: Retrieve family timeline events
  • Parameters: familyGroupId (required), limit, offset, eventTypes
  • Response: Paginated list of enriched timeline events
  • Authentication: Required, family membership validated

Event Creation

  • Timeline events created via service calls during user actions
  • No direct API endpoint for manual event creation
  • Events created as side effects of gift purchases, member actions, etc.

Error Handling

  • API errors surface as user-friendly messages
  • Permission errors show access denied messages
  • Network errors provide retry mechanisms

Test Case Categories

Critical Path Testing

TC-TL-001: Basic Timeline Display

  • Tests: BR-TL-006, BR-TL-007 (Chronological ordering, pagination)
  • Scenario: User views family timeline with multiple events
  • Expected: Events display in reverse chronological order with pagination
  • Test Code: Located in __tests__/timeline/timeline-core-functionality.test.ts

TC-TL-002: Event Creation Flow

  • Tests: BR-TL-001, BR-TL-002, BR-TL-003 (Auto generation, type validation, metadata)
  • Scenario: User performs action that should create timeline event
  • Expected: Appropriate timeline event created with correct metadata
  • Test Code: Located in __tests__/timeline/timeline-creation-verification.test.ts

TC-TL-003: Permission-Based Access

  • Tests: BR-TL-004, BR-TL-005 (Permission checks, role-based visibility)
  • Scenario: Users with different roles access family timeline
  • Expected: Each user sees only events appropriate for their role
  • Test Code: Located in __tests__/timeline/timeline-business-rules.test.ts

Integration Testing

TC-TL-004: Gift Purchase Timeline Integration

  • Tests: BR-TL-001 (Auto event generation)
  • Scenario: Complete gift purchase flow from start to timeline event
  • Expected: Gift purchase event appears in family timeline with correct metadata
  • Test Code: Located in __tests__/gift-purchase/gift-purchase-integration.test.ts

TC-TL-005: Family Member Timeline Integration

  • Tests: BR-TL-001 (Auto event generation)
  • Scenario: Add family member and verify timeline event creation
  • Expected: Member added event appears in timeline
  • Test Code: Located in __tests__/timeline/timeline-integration.test.ts

Error Scenarios

TC-TL-006: Invalid Event Creation

  • Tests: BR-TL-002, BR-TL-003 (Type validation, metadata validation)
  • Scenario: Attempt to create timeline event with invalid data
  • Expected: Event creation fails with appropriate error messages
  • Test Code: Located in __tests__/timeline/timeline-event-service.test.ts

TC-TL-007: Unauthorized Timeline Access

  • Tests: BR-TL-004 (Permission checks)
  • Scenario: Non-family member attempts to view family timeline
  • Expected: Access denied with user-friendly error message
  • Test Code: Located in __tests__/timeline/timeline-business-rules.test.ts

Edge Cases

TC-TL-008: Empty Timeline State

  • Tests: BR-TL-006 (Display rules)
  • Scenario: New family with no timeline events
  • Expected: Empty state message with encouragement to create activities
  • Test Code: Located in __tests__/timeline/timeline-core-functionality.test.ts

TC-TL-009: Large Timeline Performance

  • Tests: BR-TL-007 (Pagination)
  • Scenario: Family with hundreds of timeline events
  • Expected: Timeline loads efficiently with pagination
  • Test Code: Located in __tests__/timeline/timeline-end-to-end.test.ts

TC-TL-010: Achievement Event Special Handling

  • Tests: BR-TL-011 (Achievement highlighting)
  • Scenario: User earns achievement and views timeline
  • Expected: Achievement event displays with special celebration styling
  • Test Code: Located in __tests__/timeline/timeline-integration.test.ts

Implementation Status

Completed Features

  • ✅ Core timeline event service with full CRUD operations
  • ✅ Comprehensive event type system with metadata schemas
  • ✅ React components for timeline display and event cards
  • ✅ API endpoint for timeline data retrieval
  • ✅ Permission-based access control
  • ✅ Event filtering and pagination
  • ✅ Achievement event special handling
  • ✅ Infinite scroll timeline browsing
  • ✅ Database constraints updated to support all event types
  • ✅ Gift purchase timeline events fully functional

Pending Features

  • 🔄 Event comment system (placeholder implemented)
  • 🔄 Event reaction backend persistence
  • 🔄 Real-time timeline updates
  • 🔄 Event notification system
  • 🔄 Timeline export functionality

Known Limitations

  • Event reactions stored in local state only
  • Comment system is placeholder implementation
  • No real-time updates (requires manual refresh)
  • Limited event type coverage (focused on core family activities)

Performance Considerations

Database Optimization

  • Timeline events indexed on family_group_id and created_at
  • Event metadata stored as JSONB for efficient querying
  • Pagination limits prevent large result sets

Frontend Optimization

  • Infinite scroll prevents loading all events at once
  • Event components memoized to prevent unnecessary re-renders
  • Timeline state managed efficiently with React hooks

Caching Strategy

  • Timeline events cached in component state during session
  • Profile data cached to avoid repeated user lookups
  • Filter state preserved during pagination

This documentation follows the MyStoryFlow business rules documentation standards as defined in CLAUDE.md

Family Management FlowReference Data System Flow