Feature/recent activity timeline

[Biokes]

Description

This PR implements a comprehensive Recent Activity Timeline component that displays a chronological view of bridge, asset, and alert activity with real-time WebSocket updates. The timeline provides users with a unified view of all system events, making it easier to monitor and respond to changes across the StellaBridge platform.

The implementation includes filtering capabilities, multiple display modes, and seamless integration with the existing WebSocket infrastructure for live updates.

Type of Change

• New feature (non-breaking change that adds functionality)
• Bug fix (non-breaking change that fixes an issue)
• Breaking change (fix or feature that changes existing behaviour)
• Refactoring (no functional changes)
• Documentation update
• CI/CD change
• Dependency update

Related Issue

Closes #315
Closes #316

Changes Made

Frontend Components:

• Created RecentActivityTimeline component with real-time event display
• Implemented TimelineEventCard with compact and expanded modes
• Built TimelineEventIcon with event type and severity indicators
• Developed TimelineFilters with comprehensive filtering options
• Added useTimelineEvents hook for event management and WebSocket integration

Type Definitions:

• Added comprehensive timeline type definitions in frontend/src/types/timeline.ts
• Defined event types: bridge, asset, alert, transaction, health
• Created filter and display mode interfaces

Integration:

• Integrated timeline into main Dashboard page
• Connected to existing WebSocket store for real-time updates
• Implemented event conversion from WebSocket messages to timeline events

Documentation:

• Created detailed component documentation in frontend/docs/recent-activity-timeline.md
• Added component README with usage examples and API reference
• Documented WebSocket integration and data model

Testing:

• Comprehensive unit tests for RecentActivityTimeline component
• Storybook stories for all component variations
• Test coverage for filtering, sorting, and display modes

Features Implemented:

• ✅ Chronological ordering (newest/oldest first toggle)
• ✅ Event type icons with severity indicators
• ✅ Filter by event type, severity, status, asset, and bridge
• ✅ Search functionality across event titles and descriptions
• ✅ Compact and expanded display modes
• ✅ Real-time WebSocket updates
• ✅ Loading skeletons and empty states
• ✅ Responsive design for mobile and desktop
• ✅ Accessible with ARIA labels and keyboard navigation
• ✅ Remove individual events and clear all functionality
• ✅ Connection status indicator (Live/Connecting)

---

Testing

• Unit tests pass locally (npm run test)
• New tests added for new behaviour
• Manual testing completed — describe below if relevant

Manual test steps:

1. Started development environment with npm run dev
2. Navigated to Dashboard page
3. Verified timeline component renders with proper styling
4. Tested real-time updates by triggering WebSocket events
5. Validated all filter options (type, severity, status, search)
6. Confirmed compact/expanded mode toggle works correctly
7. Tested sort order toggle (newest/oldest first)
8. Verified remove event and clear all functionality
9. Checked responsive behavior on mobile viewport
10. Validated accessibility with keyboard navigation and screen reader
11. Confirmed loading states and empty states display correctly
12. Tested connection status indicator updates

Migration Changes

• No database migrations in this PR

Documentation

• Relevant docs/ file updated
  • Created frontend/docs/recent-activity-timeline.md with comprehensive feature documentation
  • Created frontend/src/components/timeline/README.md with component API reference
• Inline comments / JSDoc updated for changed functions
  • All new components include JSDoc comments
  • Type definitions are fully documented
• No documentation changes needed
• README.md updated (new commands, endpoints, or setup steps)
• .env.example updated (new environment variables)
• backend/docs/API.md updated (new or changed endpoints)

Checklist

• Branch is up to date with main
• PR title follows Conventional Commits format (feat: build recent activity timeline)
• Code follows project style — consistent with existing components
• No console.log left in production code (only in error handlers)
• No secrets, credentials, or .env files committed
• Self-review completed — I have read my own diff

CI Status

• Backend lint, build, and tests pass (no backend changes)
• Frontend lint, build, and tests pass
• Contract format check, Clippy, and tests pass (no contract changes)
• Security scan passes (no new vulnerabilities)
• Docker build succeeds

Screenshots

Timeline Component - Compact Mode

The timeline displays events in a compact, scannable format with event type icons and severity indicators.

Timeline Component - Expanded Mode

Clicking an event expands it to show detailed information including metadata, links, and action buttons.

Timeline Filters

Comprehensive filtering options allow users to narrow down events by type, severity, status, asset, or bridge.

Real-time Updates

The timeline shows a "Live" indicator when connected to WebSocket and automatically displays new events as they occur.

Empty State

When no events match the current filters, a helpful empty state guides users.

Mobile Responsive

The timeline is fully responsive and works seamlessly on mobile devices.

Breaking Changes

None. This is a new feature that doesn't modify existing functionality.

Additional Notes

Design Decisions:

1. WebSocket Integration: The timeline leverages the existing useWebSocketStore for real-time updates, converting WebSocket messages to timeline events on the fly.

2. Performance: Implemented a maximum event limit (default 50, configurable) to prevent memory issues with long-running sessions. Events are efficiently filtered using useMemo and callbacks are optimized with useCallback.

3. Accessibility: All interactive elements have proper ARIA labels, the component uses semantic HTML, and keyboard navigation is fully supported.

4. Extensibility: The type system is designed to easily accommodate new event types in the future. The filter system is modular and can be extended with additional filter criteria.

5. User Experience:

   • Compact mode for quick scanning
   • Expanded mode for detailed investigation
   • Inline links to related pages (assets, bridges, transactions)
   • Remove individual events or clear all for session management

Future Enhancements (not in this PR):

• Virtual scrolling for better performance with thousands of events
• Export timeline data (CSV, JSON)
• Bookmark/pin important events
• Event grouping by time periods
• Advanced date range filtering
• Event annotations and notes
• Persistent event storage (currently in-memory only)

Testing Notes:

The component includes comprehensive unit tests covering:

• Rendering with different props
• Loading, error, and empty states
• Filter interactions
• Display mode and sort order toggles
• Event removal functionality
• Connection status display

Storybook stories demonstrate all component variations and can be viewed with npm run storybook.

Integration Points:

• Dashboard page (frontend/src/pages/Dashboard.tsx)
• WebSocket store (frontend/src/stores/webSocketStore.ts)
• Existing type definitions (frontend/src/types/index.ts)
• Tailwind design system (stellar theme colors)

Known Limitations:

• Events are stored in memory only and cleared on page refresh
• No backend API for historical event retrieval (future enhancement)
• Date range filtering UI is present but not fully implemented
• Maximum of 100 events retained in memory (configurable)

[drips-wave]

@Biokes Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Mosas2000]

Resolve conflict

[Biokes]

conflict resolved