specweave 0.23.18 → 0.24.1

package/plugins/specweave-frontend/agents/frontend-architect/examples.md

@@ -0,0 +1,590 @@
+# Frontend Architect Agent - Real-World Examples
+
+This document provides real-world examples of using the Frontend Architect agent for common scenarios.
+
+## Table of Contents
+
+1. [E-Commerce Dashboard](#example-1-e-commerce-dashboard)
+2. [SaaS Marketing Website](#example-2-saas-marketing-website)
+3. [Real-Time Chat Application](#example-3-real-time-chat-application)
+4. [Design System Migration](#example-4-design-system-migration)
+5. [Performance Optimization](#example-5-performance-optimization)
+6. [Micro-Frontend Setup](#example-6-micro-frontend-setup)
+
+---
+
+## Example 1: E-Commerce Dashboard
+
+### Scenario
+Building an admin dashboard for an e-commerce platform with inventory management, order tracking, and analytics.
+
+### Prompt
+```
+Design a React-based admin dashboard for an e-commerce platform with:
+
+Requirements:
+- Real-time order notifications (WebSocket)
+- Product inventory management (10,000+ SKUs)
+- Analytics charts (sales, revenue, user activity)
+- Multi-user role support (admin, manager, viewer)
+- Mobile-responsive (tablet and desktop)
+
+Technical Stack:
+- Next.js 14 App Router
+- TypeScript
+- TailwindCSS
+- React Query for data fetching
+- Zustand for client state
+- Recharts for visualization
+
+Performance Targets:
+- LCP < 2.5s
+- Initial bundle < 300KB
+- Smooth 60fps scrolling for large tables
+
+Provide:
+1. Component architecture (Atomic Design)
+2. Folder structure
+3. State management strategy
+4. Data fetching patterns
+5. Authentication flow
+6. Optimization techniques
+```
+
+### Agent Output
+
+#### 1. Component Architecture (Atomic Design)
+
+```
+atoms/
+├── Button.tsx
+├── Input.tsx
+├── Badge.tsx
+├── Icon.tsx
+├── Avatar.tsx
+├── Skeleton.tsx
+└── Spinner.tsx
+
+molecules/
+├── FormField.tsx
+├── SearchBar.tsx
+├── Notification.tsx
+├── Pagination.tsx
+├── StatCard.tsx
+├── DataTableHeader.tsx
+└── FilterDropdown.tsx
+
+organisms/
+├── Sidebar.tsx
+├── TopNav.tsx
+├── OrderTable.tsx
+├── ProductTable.tsx
+├── AnalyticsChart.tsx
+├── NotificationPanel.tsx
+└── UserRoleSelector.tsx
+
+templates/
+├── DashboardLayout.tsx
+├── AuthLayout.tsx
+└── EmptyState.tsx
+
+pages/
+├── dashboard/
+│   ├── page.tsx (Overview)
+│   ├── orders/page.tsx
+│   ├── products/page.tsx
+│   └── analytics/page.tsx
+└── login/page.tsx
+```
+
+#### 2. Folder Structure
+
+```
+src/
+├── app/                    # Next.js App Router
+│   ├── (auth)/
+│   │   └── login/
+│   │       └── page.tsx
+│   ├── (dashboard)/
+│   │   ├── layout.tsx
+│   │   ├── page.tsx
+│   │   ├── orders/
+│   │   │   └── page.tsx
+│   │   ├── products/
+│   │   │   └── page.tsx
+│   │   └── analytics/
+│   │       └── page.tsx
+│   └── api/
+│       └── auth/[...nextauth]/route.ts
+│
+├── components/             # React components
+│   ├── atoms/
+│   ├── molecules/
+│   ├── organisms/
+│   └── templates/
+│
+├── lib/                    # Utilities & configuration
+│   ├── api/
+│   │   └── client.ts      # API client setup
+│   ├── hooks/
+│   │   ├── useOrders.ts
+│   │   ├── useProducts.ts
+│   │   ├── useWebSocket.ts
+│   │   └── useAuth.ts
+│   ├── store/
+│   │   └── index.ts       # Zustand store
+│   └── utils/
+│       ├── formatters.ts
+│       └── validators.ts
+│
+├── types/                  # TypeScript types
+│   ├── order.ts
+│   ├── product.ts
+│   ├── user.ts
+│   └── api.ts
+│
+└── styles/                 # Global styles
+    └── globals.css
+```
+
+#### 3. State Management Strategy
+
+**Client State (Zustand)**:
+```typescript
+// lib/store/index.ts
+import { create } from 'zustand';
+import { devtools, persist } from 'zustand/middleware';
+
+interface DashboardState {
+  // UI State
+  sidebarCollapsed: boolean;
+  theme: 'light' | 'dark';
+
+  // User State
+  user: User | null;
+  permissions: string[];
+
+  // Notifications
+  notifications: Notification[];
+  unreadCount: number;
+
+  // Actions
+  toggleSidebar: () => void;
+  setTheme: (theme: 'light' | 'dark') => void;
+  addNotification: (notification: Notification) => void;
+  markAsRead: (id: string) => void;
+}
+
+export const useDashboardStore = create<DashboardState>()(
+  devtools(
+    persist(
+      (set) => ({
+        sidebarCollapsed: false,
+        theme: 'light',
+        user: null,
+        permissions: [],
+        notifications: [],
+        unreadCount: 0,
+
+        toggleSidebar: () => set((state) => ({
+          sidebarCollapsed: !state.sidebarCollapsed
+        })),
+
+        setTheme: (theme) => set({ theme }),
+
+        addNotification: (notification) => set((state) => ({
+          notifications: [notification, ...state.notifications],
+          unreadCount: state.unreadCount + 1,
+        })),
+
+        markAsRead: (id) => set((state) => ({
+          notifications: state.notifications.map(n =>
+            n.id === id ? { ...n, read: true } : n
+          ),
+          unreadCount: Math.max(0, state.unreadCount - 1),
+        })),
+      }),
+      { name: 'dashboard-store' }
+    )
+  )
+);
+```
+
+**Server State (React Query)**:
+```typescript
+// lib/hooks/useOrders.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { apiClient } from '@/lib/api/client';
+
+export function useOrders(filters: OrderFilters) {
+  return useQuery({
+    queryKey: ['orders', filters],
+    queryFn: () => apiClient.getOrders(filters),
+    staleTime: 30000, // 30 seconds
+  });
+}
+
+export function useUpdateOrderStatus() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (params: { orderId: string; status: string }) =>
+      apiClient.updateOrderStatus(params.orderId, params.status),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['orders'] });
+    },
+  });
+}
+```
+
+#### 4. Data Fetching Patterns
+
+**Server Components (Default)**:
+```typescript
+// app/(dashboard)/orders/page.tsx
+import { Suspense } from 'react';
+import { OrderTable } from '@/components/organisms/OrderTable';
+import { Skeleton } from '@/components/atoms/Skeleton';
+
+export default async function OrdersPage() {
+  // Fetch in Server Component (no client-side loading state needed)
+  const initialOrders = await fetch('https://api.example.com/orders', {
+    next: { revalidate: 60 }, // ISR: revalidate every 60 seconds
+  }).then(res => res.json());
+
+  return (
+    <div>
+      <h1>Orders</h1>
+      <Suspense fallback={<Skeleton />}>
+        <OrderTable initialData={initialOrders} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+**Client Components (Interactive)**:
+```typescript
+// components/organisms/OrderTable.tsx
+'use client';
+
+import { useOrders } from '@/lib/hooks/useOrders';
+import { useState } from 'react';
+
+export function OrderTable({ initialData }: { initialData: Order[] }) {
+  const [filters, setFilters] = useState({ status: 'all', page: 1 });
+
+  const { data: orders, isLoading } = useOrders(filters, {
+    initialData, // Use server-fetched data as initial state
+    refetchInterval: 30000, // Refetch every 30s
+  });
+
+  return (
+    <div>
+      {/* Filters, pagination, etc. */}
+      {isLoading ? <Skeleton /> : <Table data={orders} />}
+    </div>
+  );
+}
+```
+
+#### 5. Real-Time WebSocket Integration
+
+```typescript
+// lib/hooks/useWebSocket.ts
+import { useEffect } from 'react';
+import { useDashboardStore } from '@/lib/store';
+import { useQueryClient } from '@tanstack/react-query';
+
+export function useWebSocket() {
+  const queryClient = useQueryClient();
+  const addNotification = useDashboardStore(state => state.addNotification);
+
+  useEffect(() => {
+    const ws = new WebSocket(process.env.NEXT_PUBLIC_WS_URL!);
+
+    ws.onmessage = (event) => {
+      const message = JSON.parse(event.data);
+
+      switch (message.type) {
+        case 'ORDER_CREATED':
+          addNotification({
+            id: Date.now().toString(),
+            type: 'info',
+            title: 'New Order',
+            message: `Order #${message.orderId} created`,
+            timestamp: Date.now(),
+          });
+          queryClient.invalidateQueries({ queryKey: ['orders'] });
+          break;
+
+        case 'INVENTORY_LOW':
+          addNotification({
+            id: Date.now().toString(),
+            type: 'warning',
+            title: 'Low Inventory',
+            message: `${message.productName} is running low`,
+            timestamp: Date.now(),
+          });
+          break;
+      }
+    };
+
+    return () => ws.close();
+  }, [addNotification, queryClient]);
+}
+
+// Usage in layout
+// app/(dashboard)/layout.tsx
+'use client';
+
+import { useWebSocket } from '@/lib/hooks/useWebSocket';
+
+export default function DashboardLayout({ children }: { children: React.ReactNode }) {
+  useWebSocket(); // Connect to WebSocket on mount
+
+  return <div>{children}</div>;
+}
+```
+
+#### 6. Optimization Techniques
+
+**Code Splitting**:
+```typescript
+// app/(dashboard)/analytics/page.tsx
+import dynamic from 'next/dynamic';
+import { Skeleton } from '@/components/atoms/Skeleton';
+
+// Lazy load heavy chart library
+const AnalyticsChart = dynamic(
+  () => import('@/components/organisms/AnalyticsChart'),
+  {
+    loading: () => <Skeleton className="h-96" />,
+    ssr: false, // Don't render on server (chart library is client-only)
+  }
+);
+
+export default function AnalyticsPage() {
+  return (
+    <div>
+      <h1>Analytics</h1>
+      <AnalyticsChart />
+    </div>
+  );
+}
+```
+
+**Virtual Scrolling for Large Tables**:
+```typescript
+// components/organisms/ProductTable.tsx
+'use client';
+
+import { useVirtualizer } from '@tanstack/react-virtual';
+import { useRef } from 'react';
+
+export function ProductTable({ products }: { products: Product[] }) {
+  const parentRef = useRef<HTMLDivElement>(null);
+
+  const virtualizer = useVirtualizer({
+    count: products.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 50, // Row height
+    overscan: 10, // Render 10 extra rows for smooth scrolling
+  });
+
+  return (
+    <div ref={parentRef} className="h-96 overflow-auto">
+      <div style={{ height: `${virtualizer.getTotalSize()}px` }}>
+        {virtualizer.getVirtualItems().map((virtualRow) => (
+          <div
+            key={virtualRow.index}
+            style={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              width: '100%',
+              height: `${virtualRow.size}px`,
+              transform: `translateY(${virtualRow.start}px)`,
+            }}
+          >
+            <ProductRow product={products[virtualRow.index]} />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+**Image Optimization**:
+```typescript
+// components/organisms/ProductCard.tsx
+import Image from 'next/image';
+
+export function ProductCard({ product }: { product: Product }) {
+  return (
+    <div>
+      <Image
+        src={product.imageUrl}
+        alt={product.name}
+        width={300}
+        height={300}
+        placeholder="blur"
+        blurDataURL={product.thumbnailUrl}
+        sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## Example 2: SaaS Marketing Website
+
+### Scenario
+Building a high-performance marketing website for a SaaS product with SEO optimization and accessibility.
+
+### Prompt
+```
+Design a Next.js marketing website for a B2B SaaS platform with:
+
+Requirements:
+- 10+ landing pages (home, features, pricing, about, blog)
+- SEO optimized (meta tags, structured data, sitemap)
+- Accessibility WCAG AA compliant
+- Blog with MDX support
+- Contact form with Resend integration
+- Newsletter signup
+- Dark mode support
+- i18n support (English, Spanish, German)
+
+Performance Targets:
+- Lighthouse score 95+ (all categories)
+- LCP < 2.5s
+- CLS < 0.1
+- 100% accessibility score
+
+Technical Stack:
+- Next.js 14 App Router
+- TypeScript
+- TailwindCSS
+- shadcn/ui components
+- MDX for blog
+- next-intl for i18n
+
+Provide component architecture and implementation examples.
+```
+
+### Agent Output
+
+[Detailed architecture with folder structure, SEO setup, i18n configuration, MDX integration, and accessibility patterns]
+
+---
+
+## Example 3: Real-Time Chat Application
+
+### Scenario
+Building a real-time chat application with WebSocket, typing indicators, and message history.
+
+[Full example with WebSocket setup, optimistic updates, and offline support]
+
+---
+
+## Example 4: Design System Migration
+
+### Scenario
+Migrating from Material-UI to a custom design system based on shadcn/ui.
+
+[Step-by-step migration plan with component mapping and codemods]
+
+---
+
+## Example 5: Performance Optimization
+
+### Scenario
+Optimizing a slow Next.js application (LCP 8s → 2s target).
+
+[Performance audit, bottleneck analysis, optimization implementation]
+
+---
+
+## Example 6: Micro-Frontend Setup
+
+### Scenario
+Setting up a micro-frontend architecture with Module Federation for a large enterprise application.
+
+[Webpack 5 Module Federation setup, shared dependencies, independent deployments]
+
+---
+
+## Tips for Effective Prompts
+
+1. **Be Specific**: Include framework versions, tech stack, and constraints
+2. **Define Metrics**: Specify performance targets (LCP, bundle size, etc.)
+3. **Provide Context**: Team size, timeline, existing infrastructure
+4. **State Goals**: SEO, accessibility, mobile-first, etc.
+5. **Include Examples**: Reference similar applications or patterns
+
+## Common Patterns
+
+### Pattern 1: Server + Client Component Split
+
+```typescript
+// Server Component (default in App Router)
+export default async function Page() {
+  const data = await fetchData(); // Server-side fetch
+  return <ClientComponent initialData={data} />;
+}
+
+// Client Component (interactive)
+'use client';
+export function ClientComponent({ initialData }) {
+  const [state, setState] = useState(initialData);
+  // Interactive logic here
+}
+```
+
+### Pattern 2: Optimistic Updates
+
+```typescript
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    await queryClient.cancelQueries({ queryKey: ['todos'] });
+    const previousTodos = queryClient.getQueryData(['todos']);
+
+    // Optimistically update UI
+    queryClient.setQueryData(['todos'], (old) => [...old, newTodo]);
+
+    return { previousTodos };
+  },
+  onError: (err, newTodo, context) => {
+    // Rollback on error
+    queryClient.setQueryData(['todos'], context.previousTodos);
+  },
+});
+```
+
+### Pattern 3: Parallel Data Fetching
+
+```typescript
+// Fetch multiple resources in parallel (Server Component)
+export default async function Page() {
+  const [user, posts, comments] = await Promise.all([
+    fetchUser(),
+    fetchPosts(),
+    fetchComments(),
+  ]);
+
+  return <Dashboard user={user} posts={posts} comments={comments} />;
+}
+```
+
+## Additional Resources
+
+- **Next.js Examples**: https://github.com/vercel/next.js/tree/canary/examples
+- **React Patterns**: https://patterns.dev
+- **TailwindCSS Components**: https://tailwindui.com
+- **shadcn/ui**: https://ui.shadcn.com
+- **Radix UI**: https://radix-ui.com