Frontend Overview

This document provides an overview of the frontend architecture for the Agentic RAG Gift Recommender chat interface.

Technology Stack

Core Principles

1. Performance First

Target: 60+ FPS at all times

Strategies:

• CSS-first animations via Motion.Dev
• Virtualized message lists for long conversations
• Optimistic UI updates
• Efficient re-render boundaries
• Lazy loading for non-critical components

2. Responsive Design

Target: Seamless experience across all devices

Breakpoints:

• Mobile: < 640px
• Tablet: 640px - 1024px
• Desktop: > 1024px

Considerations:

• Touch-friendly interactions on mobile
• Optimized keyboard navigation on desktop
• Adaptive layouts that maximize screen real estate

3. Streaming UX

Target: Immediate feedback and smooth token rendering

Features:

• Token-by-token text streaming
• Skeleton states during loading
• Smooth scroll-to-bottom behavior
• Interrupt capability for ongoing responses

4. Accessibility

Target: WCAG 2.1 AA compliance

Implementation:

• Semantic HTML structure
• ARIA labels and live regions
• Keyboard navigation support
• Focus management for modals and transitions

Architecture Overview

Component Hierarchy

app/
├── layout.tsx              # Root layout with providers
├── page.tsx                # Main chat page
├── components/
│   ├── chat/
│   │   ├── ChatContainer.tsx
│   │   ├── MessageList.tsx
│   │   ├── MessageBubble.tsx
│   │   ├── TypingIndicator.tsx
│   │   └── StreamingText.tsx
│   ├── input/
│   │   ├── ChatInput.tsx
│   │   ├── SendButton.tsx
│   │   └── SuggestionChips.tsx
│   ├── products/
│   │   ├── ProductCard.tsx
│   │   ├── ProductGrid.tsx
│   │   └── ProductCarousel.tsx
│   └── ui/
│       ├── Button.tsx
│       ├── Skeleton.tsx
│       └── Modal.tsx
├── hooks/
│   ├── useChat.ts
│   ├── useStreaming.ts
│   └── useScrollAnchor.ts
└── lib/
    ├── api.ts
    └── utils.ts

Animation Philosophy

All animations use Motion.Dev (not Framer Motion) for optimal performance:

Entry Animations

• Messages fade and slide in from bottom
• Product cards stagger with spring physics
• Smooth opacity transitions

Micro-interactions

• Button hover/press states
• Input focus transitions
• Loading shimmer effects

Page Transitions

• Layout animations for responsive changes
• Modal enter/exit with backdrop blur
• Skeleton-to-content morphing

Performance Metrics

Metric	Target	Description
FPS	≥60	Smooth animations and scrolling
LCP	<2.5s	Largest Contentful Paint
FID	<100ms	First Input Delay
CLS	<0.1	Cumulative Layout Shift
TTI	<3.0s	Time to Interactive

Mobile Considerations

• Touch gestures: Swipe-to-dismiss for product details
• Viewport: Proper handling of virtual keyboard
• Haptics: Subtle feedback on actions (where supported)
• Reduced motion: Respect user preferences

Related Documentation

• Component Architecture - Detailed component design
• Animation System - Motion.Dev implementation
• Streaming UX - Real-time response handling
• State Management - Application state patterns
• Performance Optimization - 60 FPS strategies