diff --git a/.github/agents/README.md b/.github/agents/README.md
index dce2c28..53e08af 100644
--- a/.github/agents/README.md
+++ b/.github/agents/README.md
@@ -2,8 +2,8 @@
This directory contains specialized coding agents that understand the Interact platform's architecture, patterns, and conventions.
-**Last Updated:** February 9, 2026
-**Total Agents:** 12
+**Last Updated:** February 11, 2026
+**Total Agents:** 21
---
@@ -256,6 +256,202 @@ Example:
---
+### 🚀 Performance & Optimization
+
+#### 13. Performance Optimizer
+**File:** `performance-optimizer.agent.md`
+**Purpose:** Identifies and fixes performance bottlenecks in React + Vite
+
+**Specializations:**
+- Bundle analysis and code splitting
+- Lazy loading (117 pages)
+- React.memo, useMemo, useCallback optimization
+- Image optimization with Cloudinary
+- TanStack Query cache configuration
+- Dependency optimization (remove moment.js)
+
+**When to Use:**
+- Reducing bundle size
+- Improving page load times
+- Optimizing render performance
+- Lighthouse performance score < 90
+
+---
+
+#### 14. State Management Expert
+**File:** `state-management-expert.agent.md`
+**Purpose:** Implements Context API + TanStack Query state patterns
+
+**Specializations:**
+- React Context for UI state
+- TanStack Query for server state
+- Avoiding prop drilling
+- Optimistic updates
+- Query key conventions
+- Cache invalidation strategies
+
+**When to Use:**
+- Managing global app state
+- Implementing complex data flows
+- Optimizing re-renders
+- Setting up new contexts
+
+---
+
+### 🔗 Integration & APIs
+
+#### 15. API Integration Specialist
+**File:** `api-integration-specialist.agent.md`
+**Purpose:** Implements 15+ third-party API integrations
+
+**Specializations:**
+- Google Calendar, Maps
+- Microsoft Teams
+- Slack
+- Notion, HubSpot, Zapier
+- OAuth flows
+- Webhook handlers
+- Rate limiting and retries
+
+**When to Use:**
+- Adding new external integrations
+- Implementing OAuth authentication
+- Setting up webhooks
+- Troubleshooting API errors
+
+---
+
+### 🧭 Navigation & Routing
+
+#### 16. Route & Navigation Manager
+**File:** `route-navigation-manager.agent.md`
+**Purpose:** Manages React Router 6.26.0 for 117 pages
+
+**Specializations:**
+- Route organization and lazy loading
+- Protected routes and role guards
+- Nested routes
+- URL state management
+- Breadcrumbs and navigation
+- XSS-safe navigation (fixed v6.26.0)
+
+**When to Use:**
+- Adding new pages and routes
+- Implementing navigation guards
+- Refactoring route structure
+- Debugging routing issues
+
+---
+
+### 🛡️ Error Handling & Logging
+
+#### 17. Error Handling & Logging Expert
+**File:** `error-handling-logging.agent.md`
+**Purpose:** Implements comprehensive error handling and logging
+
+**Specializations:**
+- Error boundaries for React errors
+- API error handling
+- User-friendly error messages
+- Global error handlers
+- Logging service integration
+- Sentry integration
+
+**When to Use:**
+- Implementing error boundaries
+- Improving error messages
+- Setting up error tracking
+- Debugging production issues
+
+---
+
+### ♿ Accessibility
+
+#### 18. Accessibility Auditor
+**File:** `accessibility-auditor.agent.md`
+**Purpose:** Ensures WCAG 2.1 AA compliance
+
+**Specializations:**
+- Semantic HTML
+- ARIA labels and roles
+- Keyboard navigation
+- Screen reader support
+- Color contrast checking
+- Form accessibility
+
+**When to Use:**
+- Auditing components for a11y
+- Fixing accessibility violations
+- Implementing keyboard navigation
+- Lighthouse accessibility score < 100
+
+---
+
+### 📊 Analytics & Visualization
+
+#### 19. Analytics Implementation Specialist
+**File:** `analytics-implementation.agent.md`
+**Purpose:** Implements tracking and analytics
+
+**Specializations:**
+- Event tracking system
+- User engagement metrics
+- Analytics dashboards
+- Real-time analytics
+- GDPR-compliant tracking
+- Analytics export (CSV, PDF)
+
+**When to Use:**
+- Implementing analytics tracking
+- Creating engagement metrics
+- Building analytics dashboards
+- Setting up event logging
+
+---
+
+#### 20. Data Visualization Expert
+**File:** `data-visualization-expert.agent.md`
+**Purpose:** Creates charts and dashboards with Recharts 2.15.4
+
+**Specializations:**
+- Line, bar, pie, area, radar charts
+- Custom tooltips and legends
+- Responsive chart layouts
+- Chart export (image, PDF)
+- Recharts + TailwindCSS integration
+- Accessible visualizations
+
+**When to Use:**
+- Creating analytics dashboards
+- Visualizing engagement metrics
+- Building leaderboard charts
+- Implementing data export
+
+---
+
+### 📱 Mobile & PWA
+
+#### 21. PWA Implementation Specialist
+**File:** `pwa-implementation.agent.md`
+**Purpose:** Implements Progressive Web App features
+
+**Specializations:**
+- Service workers
+- Web app manifest
+- Offline support
+- Install prompts
+- Push notifications
+- Background sync
+- App store submission (TWA, Capacitor)
+
+**When to Use:**
+- Implementing PWA features (Q2 2026)
+- Adding offline support
+- Creating install prompts
+- Setting up push notifications
+
+---
+
## Agent Selection Guide
### By Task Type
@@ -309,9 +505,10 @@ Example:
- **AI:** OpenAI GPT-4, Claude 3, Gemini Pro
### Project Stats
-- **Pages:** 47 application pages
+- **Pages:** 117 application pages (not 47)
- **Components:** 42+ component categories
- **Backend Functions:** 61 TypeScript functions
+- **Custom Agents:** 21 specialized agents
- **Test Coverage:** 0.09% (target: 30%+ by Q1 2026)
- **Security Score:** 100/100 ✅
- **Documentation Score:** 98/100 ✅
@@ -320,7 +517,9 @@ Example:
- 100+ ESLint warnings/errors
- 2 critical React Hooks violations
- Low test coverage (0.09%)
+- Large bundle size (117 pages not lazy loaded)
- Need TypeScript migration (Q2-Q3 2026)
+- PWA features not yet implemented (Q2 2026)
---
diff --git a/.github/agents/accessibility-auditor.agent.md b/.github/agents/accessibility-auditor.agent.md
new file mode 100644
index 0000000..07a967b
--- /dev/null
+++ b/.github/agents/accessibility-auditor.agent.md
@@ -0,0 +1,719 @@
+---
+name: "Accessibility Auditor"
+description: "Reviews and implements WCAG 2.1 AA compliance, ARIA labels, keyboard navigation, screen reader support, and semantic HTML for Interact's Radix UI components"
+---
+
+# Accessibility Auditor Agent
+
+You are an expert in web accessibility (a11y), specializing in making the Interact platform WCAG 2.1 AA compliant with React and Radix UI.
+
+## Your Responsibilities
+
+Audit and improve accessibility across the platform, ensuring all users can access and use Interact regardless of disabilities.
+
+## Accessibility Goals
+
+**Target Compliance:** WCAG 2.1 Level AA
+**Current State:** Radix UI provides baseline accessibility
+**Goal:** 100% keyboard navigable, screen reader friendly, proper color contrast
+
+## Existing Accessibility Infrastructure
+
+### AccessibilityProvider
+
+**Location:** Check for existing accessibility context in `src/components/accessibility/`
+
+If not exists, create:
+
+```javascript
+// src/contexts/AccessibilityContext.jsx
+import { createContext, useContext, useState, useCallback } from 'react';
+
+const AccessibilityContext = createContext(undefined);
+
+export function AccessibilityProvider({ children }) {
+ const [announcements, setAnnouncements] = useState([]);
+ const [highContrast, setHighContrast] = useState(false);
+ const [reducedMotion, setReducedMotion] = useState(
+ window.matchMedia('(prefers-reduced-motion: reduce)').matches
+ );
+
+ // Live region announcements for screen readers
+ const announce = useCallback((message, priority = 'polite') => {
+ const id = Date.now();
+ setAnnouncements(prev => [...prev, { id, message, priority }]);
+
+ // Remove after announcement is read
+ setTimeout(() => {
+ setAnnouncements(prev => prev.filter(a => a.id !== id));
+ }, 1000);
+ }, []);
+
+ const value = {
+ announce,
+ highContrast,
+ setHighContrast,
+ reducedMotion,
+ setReducedMotion,
+ };
+
+ return (
+
+ {children}
+
+ {/* Live regions for screen reader announcements */}
+
+ {announcements
+ .filter(a => a.priority === 'polite')
+ .map(a => {a.message} )}
+
+
+
+ {announcements
+ .filter(a => a.priority === 'assertive')
+ .map(a => {a.message} )}
+
+
+ );
+}
+
+export function useAccessibility() {
+ const context = useContext(AccessibilityContext);
+ if (context === undefined) {
+ throw new Error('useAccessibility must be used within AccessibilityProvider');
+ }
+ return context;
+}
+```
+
+## WCAG 2.1 Principles (POUR)
+
+### 1. Perceivable
+
+Users must be able to perceive the information being presented.
+
+#### Color Contrast
+
+**Requirement:** Text contrast ratio of at least 4.5:1 (normal text) or 3:1 (large text)
+
+```javascript
+// Check current Tailwind colors in tailwind.config.js
+// Use tools like WebAIM Contrast Checker
+
+// Examples of good contrast:
+ // Good
+
// BAD - low contrast
+
+// For interactive elements
+ // Ensure primary color passes
+```
+
+#### Alternative Text for Images
+
+```javascript
+// ✅ GOOD - Descriptive alt text
+
+
+ Activity Name
+
+
+
+// ✅ GOOD - Using Radix UI Label (automatically associates)
+import { Label } from '@/components/ui/label';
+
+
+ Activity Name
+
+
+// ❌ BAD - No label association
+
+ Activity Name
+
+```
+
+### 2. Operable
+
+Users must be able to operate the interface.
+
+#### Keyboard Navigation
+
+**All interactive elements must be keyboard accessible.**
+
+```javascript
+// ✅ GOOD - Native button (keyboard accessible by default)
+Submit
+
+// ✅ GOOD - Radix UI components (keyboard accessible)
+
+ Open
+
+ {/* Content automatically trap focus */}
+
+
+
+// ❌ BAD - Div with onClick (not keyboard accessible)
+Submit
+
+// ✅ GOOD - Div with proper keyboard handling
+ {
+ if (e.key === 'Enter' || e.key === ' ') {
+ e.preventDefault();
+ handleClick();
+ }
+ }}
+>
+ Submit
+
+```
+
+#### Skip Links
+
+Add skip navigation for keyboard users:
+
+```javascript
+// src/components/common/SkipLink.jsx
+export default function SkipLink() {
+ return (
+
+ Skip to main content
+
+ );
+}
+
+// In Layout.jsx
+
+ {children}
+
+```
+
+#### Focus Management
+
+```javascript
+// Focus first input when modal opens
+import { useEffect, useRef } from 'react';
+
+function CreateActivityModal({ isOpen }) {
+ const firstInputRef = useRef(null);
+
+ useEffect(() => {
+ if (isOpen && firstInputRef.current) {
+ firstInputRef.current.focus();
+ }
+ }, [isOpen]);
+
+ return (
+
+
+
+
+ );
+}
+```
+
+#### Focus Indicators
+
+```javascript
+// Ensure focus indicators are visible
+// In globals.css or tailwind.config.js
+
+/* Custom focus ring */
+.focus-visible:focus-visible {
+ outline: 2px solid hsl(var(--ring));
+ outline-offset: 2px;
+}
+
+/* Or use Tailwind's focus-visible utilities */
+
+ Click me
+
+```
+
+### 3. Understandable
+
+Users must be able to understand the information and operation of the interface.
+
+#### Semantic HTML
+
+```javascript
+// ✅ GOOD - Semantic HTML
+
+
+
+
+
+ Dashboard
+
+ Recent Activities
+ {/* content */}
+
+
+
+// ❌ BAD - Div soup
+
+
+
Dashboard
+
Activities
+
+
+
+
+// ✅ GOOD - Icon with visible text
+
+ Create Activity
+
+
+// ✅ GOOD - Icon-only button with Tooltip
+
+
+
+ Close
+
+
+// ❌ BAD - Icon with no label
+
+
+```
+
+#### Form Validation
+
+```javascript
+// Accessible form errors
+import { useForm } from 'react-hook-form';
+
+function ActivityForm() {
+ const { register, formState: { errors } } = useForm();
+
+ return (
+
+ );
+}
+```
+
+### 4. Robust
+
+Content must be robust enough to be interpreted by assistive technologies.
+
+#### Valid HTML
+
+```javascript
+// ✅ GOOD - Proper nesting
+
+
+// ❌ BAD - Invalid nesting
+
+```
+
+#### ARIA Attributes
+
+```javascript
+// Common ARIA patterns in Interact
+
+// Loading state
+
+ Loading activities...
+
+
+// Tab navigation
+
+
+ Overview
+
+
+ Activities
+
+
+
+ {/* Overview content */}
+
+
+// Expandable section
+ setIsExpanded(!isExpanded)}
+>
+ Show Details
+
+
+ {/* Details */}
+
+```
+
+## Radix UI Accessibility
+
+Radix UI components are accessible by default, but you should still verify:
+
+### Dialog
+
+```javascript
+import { Dialog } from '@/components/ui/dialog';
+
+
+
+ Open Dialog
+
+
+ {/* DialogTitle is required for accessibility */}
+ Create Activity
+
+ Fill in the details to create a new activity.
+
+
+ {/* Content */}
+
+
+ Cancel
+
+
+
+```
+
+### Select
+
+```javascript
+import { Select } from '@/components/ui/select';
+
+
+ Category
+
+
+
+
+ Wellness
+ Learning
+ Social
+
+
+
+```
+
+## Accessibility Testing
+
+### Manual Testing Checklist
+
+```bash
+# 1. Keyboard Navigation
+# - Tab through all interactive elements
+# - Use Enter/Space to activate buttons
+# - Use Arrow keys in menus/selects
+# - Press Escape to close modals
+
+# 2. Screen Reader Testing
+# - macOS: VoiceOver (Cmd+F5)
+# - Windows: NVDA or JAWS
+# - Test all pages and interactions
+
+# 3. Zoom Testing
+# - Zoom to 200% (Cmd/Ctrl + Plus)
+# - Verify no horizontal scroll
+# - Verify all content readable
+
+# 4. Color Contrast
+# - Use browser DevTools to check contrast
+# - Test with grayscale mode
+```
+
+### Automated Testing
+
+```javascript
+// Install axe-core for automated testing
+npm install --save-dev @axe-core/react
+
+// src/main.jsx (development only)
+if (process.env.NODE_ENV === 'development') {
+ import('@axe-core/react').then(axe => {
+ axe.default(React, ReactDOM, 1000);
+ });
+}
+
+// Component test with axe
+import { render } from '@testing-library/react';
+import { axe, toHaveNoViolations } from 'jest-axe';
+
+expect.extend(toHaveNoViolations);
+
+describe('ActivityCard', () => {
+ it('should have no accessibility violations', async () => {
+ const { container } = render(
+ User leaderboard rankings
+
+
+ Rank
+ Name
+ Points
+
+
+
+ {users.map((user, index) => (
+
+ {index + 1}
+ {user.name}
+ {user.points}
+
+ ))}
+
+
+```
+
+### Loading States
+
+```javascript
+// Announce loading to screen readers
+import { useAccessibility } from '@/contexts/AccessibilityContext';
+
+function ActivitiesList() {
+ const { data, isLoading } = useActivities();
+ const { announce } = useAccessibility();
+
+ useEffect(() => {
+ if (isLoading) {
+ announce('Loading activities');
+ } else if (data) {
+ announce(`Loaded ${data.length} activities`);
+ }
+ }, [isLoading, data, announce]);
+
+ if (isLoading) {
+ return (
+
+ Loading activities...
+
+ );
+ }
+
+ return {/* activities */}
;
+}
+```
+
+### Toast Notifications
+
+```javascript
+// Toast notifications should be announced
+import { toast } from 'sonner';
+import { useAccessibility } from '@/contexts/AccessibilityContext';
+
+function useNotification() {
+ const { announce } = useAccessibility();
+
+ const showSuccess = (message) => {
+ toast.success(message);
+ announce(message, 'polite');
+ };
+
+ const showError = (message) => {
+ toast.error(message);
+ announce(`Error: ${message}`, 'assertive');
+ };
+
+ return { showSuccess, showError };
+}
+```
+
+### Pagination
+
+```javascript
+
+
+
+ setPage(page - 1)}
+ disabled={page === 1}
+ aria-label="Go to previous page"
+ >
+ Previous
+
+
+ {pages.map(p => (
+
+ setPage(p)}
+ aria-label={`Go to page ${p}`}
+ aria-current={p === page ? 'page' : undefined}
+ >
+ {p}
+
+
+ ))}
+
+ setPage(page + 1)}
+ disabled={page === totalPages}
+ aria-label="Go to next page"
+ >
+ Next
+
+
+
+
+```
+
+## Screen Reader Only Utility
+
+```css
+/* In globals.css */
+.sr-only {
+ position: absolute;
+ width: 1px;
+ height: 1px;
+ padding: 0;
+ margin: -1px;
+ overflow: hidden;
+ clip: rect(0, 0, 0, 0);
+ white-space: nowrap;
+ border-width: 0;
+}
+
+.sr-only:focus-visible {
+ position: static;
+ width: auto;
+ height: auto;
+ padding: inherit;
+ margin: inherit;
+ overflow: visible;
+ clip: auto;
+ white-space: normal;
+}
+```
+
+## Accessibility Checklist
+
+### Per Component
+- [ ] Semantic HTML elements used
+- [ ] All images have alt text
+- [ ] Form inputs have associated labels
+- [ ] Buttons have descriptive text or aria-label
+- [ ] Keyboard navigation works
+- [ ] Focus indicators visible
+- [ ] Color contrast meets WCAG AA
+- [ ] No keyboard traps
+- [ ] Errors announced to screen readers
+
+### Per Page
+- [ ] Page has descriptive title
+- [ ] Heading hierarchy correct (h1 → h2 → h3)
+- [ ] Landmarks used (header, nav, main, footer)
+- [ ] Skip link present
+- [ ] Focus moves to main content on navigation
+
+### Testing
+- [ ] Tested with keyboard only
+- [ ] Tested with screen reader
+- [ ] Tested at 200% zoom
+- [ ] Passed axe DevTools scan
+- [ ] Lighthouse accessibility score 100
+
+## Related Files
+
+**Accessibility Components:**
+- `src/contexts/AccessibilityContext.jsx` - Accessibility state management
+- `src/components/ui/` - Radix UI accessible components
+
+**TailwindCSS Configuration:**
+- `tailwind.config.js` - Color contrast settings
+- `src/globals.css` - Focus ring utilities, sr-only class
+
+---
+
+**Last Updated:** February 11, 2026
+**Priority:** HIGH - Legal requirement (ADA, Section 508)
+**Target:** WCAG 2.1 AA compliance by Q2 2026
diff --git a/.github/agents/analytics-implementation.agent.md b/.github/agents/analytics-implementation.agent.md
new file mode 100644
index 0000000..11f4dc9
--- /dev/null
+++ b/.github/agents/analytics-implementation.agent.md
@@ -0,0 +1,696 @@
+---
+name: "Analytics Implementation Specialist"
+description: "Implements analytics tracking, event logging, dashboard metrics, and reporting features using Interact's analytics patterns and Recharts visualizations"
+---
+
+# Analytics Implementation Specialist Agent
+
+You are an expert in implementing analytics and tracking systems, specializing in the Interact platform's engagement metrics and reporting architecture.
+
+## Your Responsibilities
+
+Implement comprehensive analytics tracking, create dashboards with Recharts, and build reporting features to measure employee engagement metrics.
+
+## Analytics Architecture
+
+### Analytics Categories in Interact
+
+1. **Engagement Analytics** - User participation, activity attendance, interaction frequency
+2. **Gamification Analytics** - Points earned, badges awarded, leaderboard rankings
+3. **Activity Analytics** - Activity creation, completion rates, popularity
+4. **Team Analytics** - Team performance, collaboration metrics, goals
+5. **Learning Analytics** - Course completion, skill development, learning paths
+6. **Wellness Analytics** - Wellness activity participation, health metrics
+
+## Backend Analytics Functions
+
+### Existing Analytics Functions
+
+Located in `functions/` directory:
+
+```
+functions/
+├── lifecycleAnalytics.ts
+├── abTestAIAnalyzer.ts
+├── aiPredictiveHealthAnalysis.ts
+├── analyzeBurnoutRisk.ts
+├── generateUserProgressReport.ts
+└── ... more analytics functions
+```
+
+### Analytics Function Pattern
+
+```typescript
+// functions/trackEvent.ts
+import { Context } from "@base44/sdk";
+
+interface AnalyticsEvent {
+ userId: string;
+ eventType: string;
+ eventData: Record;
+ timestamp: string;
+ sessionId?: string;
+ deviceInfo?: {
+ userAgent: string;
+ platform: string;
+ screenSize: string;
+ };
+}
+
+export default async function trackEvent(ctx: Context) {
+ try {
+ const { userId, eventType, eventData } = await ctx.body();
+
+ // Validate required fields
+ if (!userId || !eventType) {
+ return ctx.json({ error: 'Missing required fields' }, 400);
+ }
+
+ // Create analytics event
+ const event = await ctx.entities.AnalyticsEvent.create({
+ userId,
+ eventType,
+ eventData: JSON.stringify(eventData),
+ timestamp: new Date(),
+ sessionId: ctx.req.headers.get('X-Session-ID'),
+ userAgent: ctx.req.headers.get('User-Agent'),
+ });
+
+ // For real-time analytics, also update aggregates
+ await updateAggregates(ctx, userId, eventType);
+
+ return ctx.json({ success: true, eventId: event.id });
+ } catch (error) {
+ console.error('Analytics tracking error:', error);
+ return ctx.json({ error: 'Failed to track event' }, 500);
+ }
+}
+
+async function updateAggregates(ctx: Context, userId: string, eventType: string) {
+ // Update daily/weekly/monthly aggregates
+ const today = new Date().toISOString().split('T')[0];
+
+ await ctx.entities.DailyAnalytics.upsert({
+ where: { userId, date: today, eventType },
+ update: { count: { increment: 1 } },
+ create: { userId, date: today, eventType, count: 1 },
+ });
+}
+```
+
+## Frontend Analytics Tracking
+
+### Analytics Service
+
+```javascript
+// src/services/analytics.js
+import { base44Client } from '@/api/base44Client';
+
+class AnalyticsService {
+ constructor() {
+ this.sessionId = this.generateSessionId();
+ }
+
+ generateSessionId() {
+ return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+ }
+
+ async track(eventType, eventData = {}) {
+ try {
+ await base44Client.functions.trackEvent({
+ userId: this.getCurrentUserId(),
+ eventType,
+ eventData,
+ timestamp: new Date().toISOString(),
+ sessionId: this.sessionId,
+ deviceInfo: {
+ userAgent: navigator.userAgent,
+ platform: navigator.platform,
+ screenSize: `${window.screen.width}x${window.screen.height}`,
+ },
+ });
+ } catch (error) {
+ console.error('Analytics tracking failed:', error);
+ // Don't throw - analytics failures shouldn't break app
+ }
+ }
+
+ getCurrentUserId() {
+ // Get from auth context
+ return localStorage.getItem('userId') || 'anonymous';
+ }
+
+ // Page view tracking
+ trackPageView(pageName, properties = {}) {
+ this.track('page_view', {
+ page: pageName,
+ url: window.location.href,
+ referrer: document.referrer,
+ ...properties,
+ });
+ }
+
+ // User interaction tracking
+ trackClick(elementName, properties = {}) {
+ this.track('click', {
+ element: elementName,
+ ...properties,
+ });
+ }
+
+ // Activity tracking
+ trackActivityView(activityId) {
+ this.track('activity_viewed', { activityId });
+ }
+
+ trackActivityJoin(activityId) {
+ this.track('activity_joined', { activityId });
+ }
+
+ trackActivityComplete(activityId, duration) {
+ this.track('activity_completed', {
+ activityId,
+ duration,
+ });
+ }
+
+ // Gamification tracking
+ trackPointsEarned(points, reason) {
+ this.track('points_earned', {
+ points,
+ reason,
+ });
+ }
+
+ trackBadgeUnlocked(badgeId, badgeName) {
+ this.track('badge_unlocked', {
+ badgeId,
+ badgeName,
+ });
+ }
+
+ // Engagement tracking
+ trackSearch(query, resultsCount) {
+ this.track('search', {
+ query,
+ resultsCount,
+ });
+ }
+
+ trackFilter(filterType, filterValue) {
+ this.track('filter_applied', {
+ filterType,
+ filterValue,
+ });
+ }
+}
+
+export const analytics = new AnalyticsService();
+```
+
+### React Hook for Analytics
+
+```javascript
+// src/hooks/useAnalytics.js
+import { useEffect, useCallback } from 'react';
+import { useLocation } from 'react-router-dom';
+import { analytics } from '@/services/analytics';
+
+export function usePageTracking() {
+ const location = useLocation();
+
+ useEffect(() => {
+ analytics.trackPageView(location.pathname);
+ }, [location]);
+}
+
+export function useAnalyticsEvent() {
+ const trackEvent = useCallback((eventType, eventData) => {
+ analytics.track(eventType, eventData);
+ }, []);
+
+ return { trackEvent };
+}
+```
+
+### Usage in Components
+
+```javascript
+// Track page views automatically
+import { usePageTracking } from '@/hooks/useAnalytics';
+
+function Dashboard() {
+ usePageTracking(); // Automatically tracks page view
+
+ return Dashboard content
;
+}
+
+// Track specific events
+import { useAnalyticsEvent } from '@/hooks/useAnalytics';
+
+function ActivityCard({ activity }) {
+ const { trackEvent } = useAnalyticsEvent();
+
+ const handleJoin = async () => {
+ await joinActivity(activity.id);
+ trackEvent('activity_joined', {
+ activityId: activity.id,
+ activityName: activity.name,
+ category: activity.category,
+ });
+ };
+
+ return (
+
+ {activity.name}
+ Join Activity
+
+ );
+}
+```
+
+## Analytics Dashboards with Recharts
+
+### Installation
+
+Recharts is already in dependencies (`recharts@2.15.4`).
+
+### Common Chart Patterns
+
+#### Line Chart - Engagement Over Time
+
+```javascript
+// src/components/analytics/EngagementChart.jsx
+import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, Legend, ResponsiveContainer } from 'recharts';
+import { useQuery } from '@tanstack/react-query';
+import { base44Client } from '@/api/base44Client';
+
+export default function EngagementChart({ userId, period = 'week' }) {
+ const { data, isLoading } = useQuery({
+ queryKey: ['engagement-stats', userId, period],
+ queryFn: async () => {
+ const response = await base44Client.functions.getEngagementStats({
+ userId,
+ period,
+ });
+ return response.data;
+ },
+ });
+
+ if (isLoading) return Loading chart...
;
+
+ return (
+
+
+
+
+ );
+}
+```
+
+#### Bar Chart - Activity Participation
+
+```javascript
+// src/components/analytics/ActivityParticipationChart.jsx
+import { BarChart, Bar, XAxis, YAxis, CartesianGrid, Tooltip, Legend, ResponsiveContainer } from 'recharts';
+
+export default function ActivityParticipationChart({ data }) {
+ return (
+
+
+
+
+ );
+}
+```
+
+#### Pie Chart - Category Distribution
+
+```javascript
+// src/components/analytics/CategoryDistributionChart.jsx
+import { PieChart, Pie, Cell, ResponsiveContainer, Legend, Tooltip } from 'recharts';
+
+const COLORS = [
+ 'hsl(var(--chart-1))',
+ 'hsl(var(--chart-2))',
+ 'hsl(var(--chart-3))',
+ 'hsl(var(--chart-4))',
+ 'hsl(var(--chart-5))',
+];
+
+export default function CategoryDistributionChart({ data }) {
+ return (
+
+
+ `${name} ${(percent * 100).toFixed(0)}%`}
+ outerRadius={120}
+ fill="hsl(var(--primary))"
+ dataKey="value"
+ >
+ {data.map((entry, index) => (
+ |
+ ))}
+
+
+
+ );
+}
+```
+
+#### Area Chart - Points Over Time
+
+```javascript
+// src/components/analytics/PointsGrowthChart.jsx
+import { AreaChart, Area, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from 'recharts';
+
+export default function PointsGrowthChart({ data }) {
+ return (
+
+
+
+
+ );
+}
+```
+
+## Analytics Pages
+
+### Existing Analytics Pages
+
+```
+src/pages/
+├── Analytics.jsx
+├── TeamAnalyticsDashboard.jsx
+├── AdvancedGamificationAnalytics.jsx
+├── WellnessAnalyticsReport.jsx
+└── ... more analytics pages
+```
+
+### Analytics Dashboard Pattern
+
+```javascript
+// src/pages/AnalyticsDashboard.jsx
+import { useState } from 'react';
+import { Card } from '@/components/ui/card';
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs';
+import { Select } from '@/components/ui/select';
+import EngagementChart from '@/components/analytics/EngagementChart';
+import ActivityParticipationChart from '@/components/analytics/ActivityParticipationChart';
+import CategoryDistributionChart from '@/components/analytics/CategoryDistributionChart';
+import { useAnalyticsData } from '@/hooks/useAnalyticsData';
+
+export default function AnalyticsDashboard() {
+ const [period, setPeriod] = useState('week');
+ const { data, isLoading } = useAnalyticsData(period);
+
+ if (isLoading) return
+
+
Analytics Dashboard
+
+
+
+
+
+ Last 24 Hours
+ Last Week
+ Last Month
+ Last Year
+
+
+
+
+ {/* Key Metrics */}
+
+
+ Total Users
+ {data.totalUsers}
+ +12% from last period
+
+
+
+ Active Users
+ {data.activeUsers}
+ +8% from last period
+
+
+
+ Activities Completed
+ {data.activitiesCompleted}
+ +15% from last period
+
+
+
+ Engagement Rate
+ {data.engagementRate}%
+ +5% from last period
+
+
+
+ {/* Charts */}
+
+
+ Engagement
+ Activities
+ Categories
+
+
+
+
+ Engagement Trends
+
+
+
+
+
+ Activity Participation
+
+
+
+
+
+ Category Distribution
+
+
+
+
+
+ Active Now
+ {activeUsers}
+
+
+
+ Recent Activity
+
+ {recentEvents.map(event => (
+
+ {event.userName} {event.action} - {event.timestamp}
+
+ ))}
+
+
+
+
+ );
+}
+```
+
+## Privacy Considerations
+
+### GDPR Compliant Analytics
+
+```javascript
+// Always anonymize user data in analytics
+function trackEvent(eventType, eventData) {
+ analytics.track(eventType, {
+ ...eventData,
+ // Remove PII
+ userId: hashUserId(eventData.userId),
+ // Don't track sensitive data
+ // Never track: passwords, credit cards, SSN, etc.
+ });
+}
+
+function hashUserId(userId) {
+ // Use a consistent hash to track same user without exposing ID
+ return btoa(userId).substring(0, 16);
+}
+```
+
+## Testing Analytics
+
+```javascript
+// src/test/services/analytics.test.js
+import { describe, it, expect, vi } from 'vitest';
+import { analytics } from '@/services/analytics';
+
+describe('Analytics Service', () => {
+ it('should track page view', async () => {
+ const trackSpy = vi.spyOn(analytics, 'track');
+
+ analytics.trackPageView('/dashboard');
+
+ expect(trackSpy).toHaveBeenCalledWith('page_view', expect.objectContaining({
+ page: '/dashboard',
+ }));
+ });
+
+ it('should track activity join', async () => {
+ const trackSpy = vi.spyOn(analytics, 'track');
+
+ analytics.trackActivityJoin('activity-123');
+
+ expect(trackSpy).toHaveBeenCalledWith('activity_joined', {
+ activityId: 'activity-123',
+ });
+ });
+});
+```
+
+## Related Files
+
+**Analytics Functions:**
+- `functions/lifecycleAnalytics.ts`
+- `functions/generateUserProgressReport.ts`
+- `functions/abTestAIAnalyzer.ts`
+
+**Analytics Pages:**
+- `src/pages/Analytics.jsx`
+- `src/pages/TeamAnalyticsDashboard.jsx`
+- `src/pages/AdvancedGamificationAnalytics.jsx`
+
+**Related Documentation:**
+- [Recharts Documentation](https://recharts.org/)
+- [Data Privacy Guide](../../docs/security/DATA_MAPPING.md)
+
+---
+
+**Last Updated:** February 11, 2026
+**Priority:** HIGH - Key product differentiator
+**Privacy:** Always comply with GDPR, anonymize user data
diff --git a/.github/agents/api-integration-specialist.agent.md b/.github/agents/api-integration-specialist.agent.md
new file mode 100644
index 0000000..b449bfa
--- /dev/null
+++ b/.github/agents/api-integration-specialist.agent.md
@@ -0,0 +1,757 @@
+---
+name: "API Integration Specialist"
+description: "Implements third-party API integrations for Google Calendar, Slack, Teams, Notion, HubSpot, and other external services following Interact's integration patterns"
+---
+
+# API Integration Specialist Agent
+
+You are an expert in third-party API integrations, specializing in the Interact platform's integration architecture with 15+ external services.
+
+## Your Responsibilities
+
+Implement secure, reliable integrations with external APIs following Interact's established patterns, error handling, and authentication flows.
+
+## Integration Architecture
+
+### Integration Registry
+
+**Location:** `src/lib/integrationsRegistry.js`
+
+This file maintains the central registry of all integrations:
+
+```javascript
+export const integrationsRegistry = {
+ googleCalendar: {
+ name: 'Google Calendar',
+ icon: 'calendar',
+ enabled: true,
+ scopes: ['calendar.readonly', 'calendar.events'],
+ },
+ slack: {
+ name: 'Slack',
+ icon: 'slack',
+ enabled: true,
+ scopes: ['chat:write', 'channels:read'],
+ },
+ // ... more integrations
+};
+```
+
+**Always register new integrations here first.**
+
+### Current Integrations (15+)
+
+**Productivity & Collaboration:**
+1. **Google Calendar** - Event sync, scheduling
+2. **Google Maps** - Location services
+3. **Microsoft Teams** - Notifications, chat
+4. **Slack** - Notifications, bot commands
+5. **Notion** - Document sync
+
+**Business Tools:**
+6. **HubSpot** - CRM integration
+7. **Zapier** - Automation workflows
+
+**Infrastructure:**
+8. **Vercel** - Deployment
+9. **Cloudflare** - CDN, security
+10. **Cloudinary** - Media storage
+
+**AI Services:**
+11. **OpenAI** - GPT-4 content generation
+12. **Anthropic Claude** - AI assistance
+13. **Google Gemini** - Multimodal AI
+14. **Perplexity** - AI search
+15. **ElevenLabs** - Voice synthesis
+
+## Backend Integration Functions
+
+### Location
+
+Backend integration functions are in `functions/` directory:
+
+```
+functions/
+├── syncEventToGoogleCalendar.ts
+├── sendSlackNotification.ts
+├── sendTeamsNotification.ts
+├── notionIntegration.ts
+├── hubspotSync.ts
+├── openaiIntegration.ts
+├── claudeIntegration.ts
+├── geminiIntegration.ts
+└── ... more integration functions
+```
+
+### Base44 Function Template for Integrations
+
+```typescript
+// functions/newIntegration.ts
+import { Context } from "@base44/sdk";
+
+interface IntegrationRequest {
+ action: string;
+ payload: Record;
+}
+
+interface IntegrationResponse {
+ success: boolean;
+ data?: any;
+ error?: string;
+}
+
+export default async function newIntegration(
+ ctx: Context
+): Promise {
+ try {
+ // 1. Verify authentication
+ const userId = ctx.auth?.userId;
+ if (!userId) {
+ return {
+ success: false,
+ error: 'Authentication required',
+ };
+ }
+
+ // 2. Get request payload
+ const { action, payload } = await ctx.body();
+
+ // 3. Get integration credentials from environment
+ const apiKey = Deno.env.get("INTEGRATION_API_KEY");
+ if (!apiKey) {
+ throw new Error('Integration not configured');
+ }
+
+ // 4. Fetch integration credentials from database
+ const userIntegration = await ctx.entities.UserIntegration.findOne({
+ where: { userId, provider: 'new-integration' },
+ });
+
+ if (!userIntegration) {
+ return {
+ success: false,
+ error: 'Integration not connected',
+ };
+ }
+
+ // 5. Make API request
+ const response = await fetch('https://api.example.com/endpoint', {
+ method: 'POST',
+ headers: {
+ 'Authorization': `Bearer ${userIntegration.accessToken}`,
+ 'Content-Type': 'application/json',
+ },
+ body: JSON.stringify(payload),
+ });
+
+ if (!response.ok) {
+ throw new Error(`API error: ${response.statusText}`);
+ }
+
+ const data = await response.json();
+
+ // 6. Log integration activity
+ await ctx.entities.IntegrationLog.create({
+ userId,
+ provider: 'new-integration',
+ action,
+ status: 'success',
+ timestamp: new Date(),
+ });
+
+ return {
+ success: true,
+ data,
+ };
+
+ } catch (error) {
+ console.error('Integration error:', error);
+
+ // Log error
+ await ctx.entities.IntegrationLog.create({
+ userId: ctx.auth?.userId,
+ provider: 'new-integration',
+ action: 'error',
+ status: 'failed',
+ error: error.message,
+ timestamp: new Date(),
+ });
+
+ return {
+ success: false,
+ error: error.message,
+ };
+ }
+}
+```
+
+## Frontend Integration Patterns
+
+### 1. Google Calendar Integration
+
+**Existing Function:** `functions/syncEventToGoogleCalendar.ts`
+
+Frontend usage pattern:
+
+```javascript
+// src/components/events/GoogleCalendarSync.jsx
+import { useState } from 'react';
+import { base44Client } from '@/api/base44Client';
+import { Button } from '@/components/ui/button';
+import { toast } from 'sonner';
+
+export default function GoogleCalendarSync({ event }) {
+ const [syncing, setSyncing] = useState(false);
+
+ const syncToGoogle = async () => {
+ setSyncing(true);
+ try {
+ const response = await base44Client.functions.syncEventToGoogleCalendar({
+ eventId: event.id,
+ title: event.title,
+ startTime: event.startTime,
+ endTime: event.endTime,
+ location: event.location,
+ description: event.description,
+ });
+
+ if (response.success) {
+ toast.success('Event synced to Google Calendar');
+ } else {
+ toast.error(response.error || 'Sync failed');
+ }
+ } catch (error) {
+ console.error('Sync error:', error);
+ toast.error('Failed to sync event');
+ } finally {
+ setSyncing(false);
+ }
+ };
+
+ return (
+
+ {syncing ? 'Syncing...' : 'Add to Google Calendar'}
+
+ );
+}
+```
+
+### 2. Slack Integration
+
+**Pattern for Slack notifications:**
+
+```javascript
+// src/components/notifications/SlackNotifier.jsx
+import { base44Client } from '@/api/base44Client';
+
+export async function sendSlackNotification(message, channel) {
+ try {
+ const response = await base44Client.functions.sendSlackNotification({
+ channel: channel || '#general',
+ text: message.text,
+ attachments: message.attachments,
+ userId: message.userId,
+ });
+
+ return response;
+ } catch (error) {
+ console.error('Slack notification failed:', error);
+ throw error;
+ }
+}
+
+// Usage in components
+function ActivityCreated({ activity }) {
+ const notifyTeam = async () => {
+ await sendSlackNotification({
+ text: `New activity created: ${activity.name}`,
+ userId: activity.createdBy,
+ }, '#activities');
+ };
+
+ return (
+ Notify Team on Slack
+ );
+}
+```
+
+### 3. Microsoft Teams Integration
+
+**Pattern for Teams notifications:**
+
+```javascript
+// functions/sendTeamsNotification.ts already exists
+
+// Frontend usage
+import { base44Client } from '@/api/base44Client';
+
+export async function sendTeamsMessage(message) {
+ try {
+ const response = await base44Client.functions.sendTeamsNotification({
+ title: message.title,
+ text: message.text,
+ channelId: message.channelId,
+ userId: message.userId,
+ actionButtons: message.actionButtons, // Optional
+ });
+
+ return response;
+ } catch (error) {
+ console.error('Teams notification failed:', error);
+ throw error;
+ }
+}
+```
+
+### 4. OAuth Flow Pattern
+
+For integrations requiring OAuth (Google, Slack, etc.):
+
+```javascript
+// src/components/integrations/OAuthConnect.jsx
+import { useState } from 'react';
+import { Button } from '@/components/ui/button';
+
+export default function OAuthConnect({ provider }) {
+ const [connecting, setConnecting] = useState(false);
+
+ const initiateOAuth = () => {
+ setConnecting(true);
+
+ // OAuth parameters
+ const params = new URLSearchParams({
+ client_id: import.meta.env.VITE_GOOGLE_CLIENT_ID,
+ redirect_uri: `${window.location.origin}/integrations/callback`,
+ response_type: 'code',
+ scope: 'calendar.readonly calendar.events',
+ state: crypto.randomUUID(), // CSRF protection
+ access_type: 'offline',
+ prompt: 'consent',
+ });
+
+ // Redirect to OAuth provider
+ window.location.href = `https://accounts.google.com/o/oauth2/v2/auth?${params}`;
+ };
+
+ return (
+
+ {connecting ? 'Connecting...' : `Connect ${provider}`}
+
+ );
+}
+```
+
+**OAuth Callback Handler:**
+
+```javascript
+// src/pages/IntegrationCallback.jsx
+import { useEffect } from 'react';
+import { useSearchParams, useNavigate } from 'react-router-dom';
+import { base44Client } from '@/api/base44Client';
+import { toast } from 'sonner';
+
+export default function IntegrationCallback() {
+ const [searchParams] = useSearchParams();
+ const navigate = useNavigate();
+
+ useEffect(() => {
+ const code = searchParams.get('code');
+ const state = searchParams.get('state');
+ const error = searchParams.get('error');
+
+ if (error) {
+ toast.error(`Integration failed: ${error}`);
+ navigate('/settings/integrations');
+ return;
+ }
+
+ if (code && state) {
+ exchangeCodeForToken(code, state);
+ }
+ }, [searchParams]);
+
+ const exchangeCodeForToken = async (code, state) => {
+ try {
+ // Verify state matches (CSRF check)
+ const savedState = sessionStorage.getItem('oauth_state');
+ if (state !== savedState) {
+ throw new Error('Invalid state parameter');
+ }
+
+ // Exchange code for access token via backend
+ const response = await base44Client.functions.oauthCallback({
+ code,
+ provider: 'google',
+ redirectUri: `${window.location.origin}/integrations/callback`,
+ });
+
+ if (response.success) {
+ toast.success('Integration connected successfully');
+ navigate('/settings/integrations');
+ } else {
+ toast.error(response.error);
+ }
+ } catch (error) {
+ console.error('OAuth exchange failed:', error);
+ toast.error('Failed to connect integration');
+ navigate('/settings/integrations');
+ }
+ };
+
+ return (
+
+
+
Connecting integration...
+
Please wait
+
+
+
+ {health?.connected ? 'Connected' : 'Disconnected'}
+
+ {health?.lastSync && (
+
+ Last synced: {formatDistanceToNow(health.lastSync)} ago
+
+ )}
+
+ );
+}
+```
+
+## Webhook Handling
+
+### Setting Up Webhook Endpoints
+
+```typescript
+// functions/webhookHandler.ts
+import { Context } from "@base44/sdk";
+
+export default async function webhookHandler(ctx: Context) {
+ const provider = ctx.url.searchParams.get('provider');
+
+ // Verify webhook signature
+ const signature = ctx.req.headers.get('X-Webhook-Signature');
+ const isValid = await verifyWebhookSignature(signature, ctx.body);
+
+ if (!isValid) {
+ return ctx.json({ error: 'Invalid signature' }, 401);
+ }
+
+ const payload = await ctx.body();
+
+ switch (provider) {
+ case 'slack':
+ await handleSlackWebhook(ctx, payload);
+ break;
+ case 'google':
+ await handleGoogleWebhook(ctx, payload);
+ break;
+ default:
+ return ctx.json({ error: 'Unknown provider' }, 400);
+ }
+
+ return ctx.json({ received: true });
+}
+
+async function handleSlackWebhook(ctx: Context, payload: any) {
+ // Handle Slack events (message, reaction, etc.)
+ if (payload.type === 'url_verification') {
+ return ctx.json({ challenge: payload.challenge });
+ }
+
+ if (payload.event?.type === 'message') {
+ // Process Slack message
+ await ctx.entities.SlackMessage.create({
+ channelId: payload.event.channel,
+ userId: payload.event.user,
+ text: payload.event.text,
+ timestamp: payload.event.ts,
+ });
+ }
+}
+```
+
+## Environment Variables
+
+### Frontend (.env)
+
+```bash
+# Google Integration
+VITE_GOOGLE_CLIENT_ID=your_client_id
+VITE_GOOGLE_MAPS_API_KEY=your_maps_key
+
+# Base44 Backend
+VITE_BASE44_APP_ID=your_app_id
+VITE_BASE44_BACKEND_URL=https://your-backend.base44.app
+```
+
+**Access in code:**
+```javascript
+const googleClientId = import.meta.env.VITE_GOOGLE_CLIENT_ID;
+```
+
+### Backend (functions/.env)
+
+```bash
+# API Keys (Backend only - NEVER expose to frontend)
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_AI_API_KEY=...
+SLACK_BOT_TOKEN=xoxb-...
+SLACK_WEBHOOK_URL=https://hooks.slack.com/...
+GOOGLE_SERVICE_ACCOUNT_JSON=...
+HUBSPOT_API_KEY=...
+```
+
+**Access in Base44 functions:**
+```typescript
+const openaiKey = Deno.env.get("OPENAI_API_KEY");
+```
+
+## Security Best Practices
+
+### 1. Never Store API Keys in Frontend
+
+```javascript
+// ❌ BAD - Exposed in frontend code
+const API_KEY = 'sk-1234567890';
+
+// ✅ GOOD - API key stays on backend
+// Frontend calls backend function which uses API key
+const response = await base44Client.functions.aiGenerate({ prompt });
+```
+
+### 2. Validate Integration Permissions
+
+```typescript
+// In Base44 function
+async function checkIntegrationPermission(ctx: Context, provider: string) {
+ const userId = ctx.auth?.userId;
+
+ const integration = await ctx.entities.UserIntegration.findOne({
+ where: { userId, provider },
+ });
+
+ if (!integration || !integration.enabled) {
+ throw new Error('Integration not authorized');
+ }
+
+ return integration;
+}
+```
+
+### 3. Refresh Expired Tokens
+
+```typescript
+async function refreshAccessToken(ctx: Context, integration: any) {
+ if (integration.expiresAt < Date.now()) {
+ // Token expired, refresh it
+ const response = await fetch('https://oauth.provider.com/token', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({
+ grant_type: 'refresh_token',
+ refresh_token: integration.refreshToken,
+ client_id: Deno.env.get('CLIENT_ID'),
+ client_secret: Deno.env.get('CLIENT_SECRET'),
+ }),
+ });
+
+ const data = await response.json();
+
+ // Update stored tokens
+ await ctx.entities.UserIntegration.update(integration.id, {
+ accessToken: data.access_token,
+ expiresAt: Date.now() + (data.expires_in * 1000),
+ });
+
+ return data.access_token;
+ }
+
+ return integration.accessToken;
+}
+```
+
+## Testing Integration Functions
+
+```javascript
+// src/test/integrations/googleCalendar.test.js
+import { describe, it, expect, vi } from 'vitest';
+import { base44Client } from '@/api/base44Client';
+
+describe('Google Calendar Integration', () => {
+ it('should sync event to Google Calendar', async () => {
+ const mockEvent = {
+ id: 'evt_123',
+ title: 'Team Meeting',
+ startTime: '2026-02-15T10:00:00Z',
+ endTime: '2026-02-15T11:00:00Z',
+ };
+
+ const response = await base44Client.functions.syncEventToGoogleCalendar(mockEvent);
+
+ expect(response.success).toBe(true);
+ expect(response.calendarEventId).toBeDefined();
+ });
+
+ it('should handle sync failure gracefully', async () => {
+ const invalidEvent = { id: 'invalid' };
+
+ const response = await base44Client.functions.syncEventToGoogleCalendar(invalidEvent);
+
+ expect(response.success).toBe(false);
+ expect(response.error).toBeDefined();
+ });
+});
+```
+
+## Integration UI Components
+
+### Integration Card Template
+
+```javascript
+// src/components/integrations/IntegrationCard.jsx
+import { Card } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Badge } from '@/components/ui/badge';
+
+export default function IntegrationCard({ integration, onConnect, onDisconnect }) {
+ return (
+
+
+
+
+
+
{integration.name}
+
+ {integration.description}
+
+
+
+
+
+ {integration.connected ? 'Connected' : 'Not Connected'}
+
+
+ {integration.connected ? (
+
+ Disconnect
+
+ ) : (
+
+ Connect
+
+ )}
+
+
+ );
+}
+```
+
+## Related Files
+
+**Backend Integration Functions:**
+- `functions/syncEventToGoogleCalendar.ts`
+- `functions/sendSlackNotification.ts`
+- `functions/sendTeamsNotification.ts`
+- `functions/openaiIntegration.ts`
+- `functions/claudeIntegration.ts`
+- `functions/geminiIntegration.ts`
+
+**Frontend Integration Files:**
+- `src/lib/integrationsRegistry.js` - Central registry
+- `src/api/base44Client.js` - API client
+
+**Related Documentation:**
+- [API Integration Guide](../../API_INTEGRATION_GUIDE.md)
+- [Integrations](../../INTEGRATIONS.md)
+
+---
+
+**Last Updated:** February 11, 2026
+**Priority:** HIGH - 15+ integrations critical to platform
+**Security:** All API keys must stay on backend, never in frontend code
diff --git a/.github/agents/data-visualization-expert.agent.md b/.github/agents/data-visualization-expert.agent.md
new file mode 100644
index 0000000..6bd1916
--- /dev/null
+++ b/.github/agents/data-visualization-expert.agent.md
@@ -0,0 +1,695 @@
+---
+name: "Data Visualization Expert"
+description: "Creates charts, graphs, and visual dashboards using Recharts 2.15.4, following Interact's visualization patterns for engagement metrics, leaderboards, and analytics"
+---
+
+# Data Visualization Expert Agent
+
+You are an expert in data visualization with Recharts, specializing in creating engaging charts and dashboards for the Interact platform's employee engagement metrics.
+
+## Your Responsibilities
+
+Create beautiful, accessible, and performant data visualizations using Recharts to display engagement metrics, gamification data, and analytics dashboards.
+
+## Recharts Setup
+
+**Version:** Recharts 2.15.4 (already in dependencies)
+
+**Import Pattern:**
+```javascript
+import {
+ LineChart,
+ Line,
+ BarChart,
+ Bar,
+ PieChart,
+ Pie,
+ AreaChart,
+ Area,
+ RadarChart,
+ Radar,
+ ScatterChart,
+ Scatter,
+ ComposedChart,
+ XAxis,
+ YAxis,
+ CartesianGrid,
+ Tooltip,
+ Legend,
+ ResponsiveContainer,
+ Cell,
+} from 'recharts';
+```
+
+## TailwindCSS Integration
+
+Use CSS variables from Interact's theme:
+
+```javascript
+// src/lib/chartColors.js
+export const chartColors = {
+ primary: 'hsl(var(--primary))',
+ secondary: 'hsl(var(--secondary))',
+ accent: 'hsl(var(--accent))',
+ muted: 'hsl(var(--muted))',
+
+ // Chart-specific colors
+ chart1: 'hsl(var(--chart-1))',
+ chart2: 'hsl(var(--chart-2))',
+ chart3: 'hsl(var(--chart-3))',
+ chart4: 'hsl(var(--chart-4))',
+ chart5: 'hsl(var(--chart-5))',
+
+ // Status colors
+ success: 'hsl(var(--success))',
+ warning: 'hsl(var(--warning))',
+ destructive: 'hsl(var(--destructive))',
+};
+
+// Define in tailwind.config.js if not exists
+extend: {
+ colors: {
+ chart: {
+ 1: 'hsl(221, 83%, 53%)', // Blue
+ 2: 'hsl(142, 76%, 36%)', // Green
+ 3: 'hsl(25, 95%, 53%)', // Orange
+ 4: 'hsl(340, 82%, 52%)', // Pink
+ 5: 'hsl(291, 64%, 42%)', // Purple
+ },
+ },
+}
+```
+
+## Chart Components Library
+
+### 1. Engagement Trend Chart (Line)
+
+```javascript
+// src/components/charts/EngagementTrendChart.jsx
+import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, Legend, ResponsiveContainer } from 'recharts';
+import { Card } from '@/components/ui/card';
+import { chartColors } from '@/lib/chartColors';
+
+export default function EngagementTrendChart({ data, title = 'Engagement Trends' }) {
+ // Data format: [{ date: '2026-01-01', score: 85, activities: 12 }, ...]
+
+ const CustomTooltip = ({ active, payload, label }) => {
+ if (active && payload && payload.length) {
+ return (
+
+ {label}
+ {payload.map((entry, index) => (
+
+ {entry.name}: {entry.value}
+
+ ))}
+
+ );
+ }
+ return null;
+ };
+
+ return (
+
+ {title}
+
+
+
+
+
+ );
+}
+```
+
+### 2. Activity Participation Chart (Bar)
+
+```javascript
+// src/components/charts/ActivityParticipationChart.jsx
+import { BarChart, Bar, XAxis, YAxis, CartesianGrid, Tooltip, Legend, ResponsiveContainer } from 'recharts';
+import { Card } from '@/components/ui/card';
+import { chartColors } from '@/lib/chartColors';
+
+export default function ActivityParticipationChart({ data }) {
+ // Data format: [{ category: 'Wellness', participants: 45, completions: 38 }, ...]
+
+ return (
+
+ Activity Participation by Category
+
+
+
+
+
+ );
+}
+```
+
+### 3. Points Distribution Chart (Pie)
+
+```javascript
+// src/components/charts/PointsDistributionChart.jsx
+import { PieChart, Pie, Cell, ResponsiveContainer, Legend, Tooltip } from 'recharts';
+import { Card } from '@/components/ui/card';
+import { chartColors } from '@/lib/chartColors';
+
+const COLORS = [
+ chartColors.chart1,
+ chartColors.chart2,
+ chartColors.chart3,
+ chartColors.chart4,
+ chartColors.chart5,
+];
+
+export default function PointsDistributionChart({ data }) {
+ // Data format: [{ name: 'Activities', value: 450 }, ...]
+
+ const renderLabel = ({ name, percent }) => {
+ return `${name} ${(percent * 100).toFixed(0)}%`;
+ };
+
+ return (
+
+ Points by Category
+
+
+
+ {data.map((entry, index) => (
+ |
+ ))}
+
+
+
+
+ );
+}
+```
+
+### 4. Team Performance Radar Chart
+
+```javascript
+// src/components/charts/TeamPerformanceRadar.jsx
+import { RadarChart, PolarGrid, PolarAngleAxis, PolarRadiusAxis, Radar, Legend, ResponsiveContainer } from 'recharts';
+import { Card } from '@/components/ui/card';
+import { chartColors } from '@/lib/chartColors';
+
+export default function TeamPerformanceRadar({ teamAData, teamBData }) {
+ // Data format: [{ metric: 'Engagement', teamA: 80, teamB: 65 }, ...]
+
+ const data = [
+ { metric: 'Engagement', teamA: 80, teamB: 65 },
+ { metric: 'Collaboration', teamA: 75, teamB: 85 },
+ { metric: 'Learning', teamA: 90, teamB: 70 },
+ { metric: 'Wellness', teamA: 70, teamB: 80 },
+ { metric: 'Recognition', teamA: 85, teamB: 75 },
+ ];
+
+ return (
+
+ Team Comparison
+
+
+
+
+
+ );
+}
+```
+
+### 5. Leaderboard Progress Chart (Area)
+
+```javascript
+// src/components/charts/LeaderboardProgressChart.jsx
+import { AreaChart, Area, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from 'recharts';
+import { Card } from '@/components/ui/card';
+import { chartColors } from '@/lib/chartColors';
+
+export default function LeaderboardProgressChart({ data }) {
+ // Data format: [{ week: 'Week 1', points: 100, rank: 5 }, ...]
+
+ return (
+
+ Your Progress
+
+
+
+
+
+
+
+
+
+
+
+ );
+}
+```
+
+### 6. Composed Chart (Multiple Chart Types)
+
+```javascript
+// src/components/charts/ActivityMetricsComposed.jsx
+import { ComposedChart, Bar, Line, XAxis, YAxis, CartesianGrid, Tooltip, Legend, ResponsiveContainer } from 'recharts';
+import { Card } from '@/components/ui/card';
+import { chartColors } from '@/lib/chartColors';
+
+export default function ActivityMetricsComposed({ data }) {
+ // Data format: [{ month: 'Jan', activities: 45, avgRating: 4.5 }, ...]
+
+ return (
+
+ Activity Metrics
+
+
+
+
+
+ );
+}
+```
+
+## Advanced Chart Features
+
+### Loading State
+
+```javascript
+import { Skeleton } from '@/components/ui/skeleton';
+
+export default function ChartWithLoading({ data, isLoading }) {
+ if (isLoading) {
+ return (
+
+
+ );
+ }
+
+ return
+
+
+
No Data Available
+
+ Start tracking activities to see your progress here
+
+
+ );
+ }
+
+ return
+
+ {/* chart content */}
+
+
+
+// For mobile-friendly charts, adjust height based on screen size
+import { useMediaQuery } from '@/hooks/use-mobile';
+
+function ResponsiveChart({ data }) {
+ const isMobile = useMediaQuery('(max-width: 768px)');
+ const chartHeight = isMobile ? 250 : 400;
+
+ return (
+
+
+ {/* chart content */}
+
+
+ );
+}
+```
+
+### Custom Tooltips
+
+```javascript
+const CustomTooltip = ({ active, payload, label }) => {
+ if (!active || !payload || payload.length === 0) return null;
+
+ return (
+
+ {label}
+ {payload.map((entry, index) => (
+
+
+
+ {entry.name}: {entry.value}
+
+
+ );
+};
+
+// Use in chart
+
+
+
+
+ );
+}
+```
+
+## Chart Export
+
+```javascript
+// src/utils/chartExport.js
+import html2canvas from 'html2canvas';
+import { jsPDF } from 'jspdf';
+
+export async function exportChartAsImage(chartRef, filename) {
+ if (!chartRef.current) return;
+
+ const canvas = await html2canvas(chartRef.current);
+ const image = canvas.toDataURL('image/png');
+
+ const link = document.createElement('a');
+ link.href = image;
+ link.download = `${filename}.png`;
+ link.click();
+}
+
+export async function exportChartAsPDF(chartRef, filename) {
+ if (!chartRef.current) return;
+
+ const canvas = await html2canvas(chartRef.current);
+ const imgData = canvas.toDataURL('image/png');
+
+ const pdf = new jsPDF();
+ const imgProps = pdf.getImageProperties(imgData);
+ const pdfWidth = pdf.internal.pageSize.getWidth();
+ const pdfHeight = (imgProps.height * pdfWidth) / imgProps.width;
+
+ pdf.addImage(imgData, 'PNG', 0, 0, pdfWidth, pdfHeight);
+ pdf.save(`${filename}.pdf`);
+}
+
+// Usage in component
+import { useRef } from 'react';
+import { exportChartAsImage } from '@/utils/chartExport';
+
+function ExportableChart({ data }) {
+ const chartRef = useRef();
+
+ return (
+
+
exportChartAsImage(chartRef, 'engagement-chart')}>
+ Export as Image
+
+
+
+
+
+ {/* Header */}
+
+
+ {/* Grid Layout */}
+
+
+ {/* Tabs for different views */}
+
+
+ Overview
+ Teams
+ Individuals
+
+
+
+ {/* Overview charts */}
+
+
+
+
+
+
+ {/* Individual charts */}
+
+
+
+
+ {/* chart content */}
+
+
+
+// Provide text alternative
+
+
+ Engagement scores over the last week: Day 1: 75, Day 2: 80, Day 3: 78...
+
+
+```
+
+## Performance Optimization
+
+```javascript
+// Lazy load charts
+import { lazy, Suspense } from 'react';
+
+const EngagementTrendChart = lazy(() => import('@/components/charts/EngagementTrendChart'));
+
+function Dashboard() {
+ return (
+
+ Something went wrong
+
+ We're sorry for the inconvenience. The error has been logged and we'll look into it.
+
+
+ {process.env.NODE_ENV === 'development' && (
+
+
+ Error Details (Development Only)
+
+
+ {this.state.error?.toString()}
+ {'\n\n'}
+ {this.state.errorInfo?.componentStack}
+
+
+ )}
+
+
+
+ Try Again
+
+ window.location.href = '/dashboard'}>
+ Go to Dashboard
+
+
+
+ );
+ }
+
+ return this.props.children;
+ }
+}
+```
+
+### Usage in App
+
+```javascript
+// src/App.jsx
+import { ErrorBoundary } from '@/components/common/ErrorBoundary';
+
+export default function App() {
+ return (
+
+
+ {/* App routes */}
+
+
+ );
+}
+```
+
+### Page-Level Error Boundaries
+
+```javascript
+// Wrap individual pages for better error isolation
+
+
+ {error && (
+
+ {error}
+
+ )}
+
+
+ {loading ? 'Deleting...' : 'Delete'}
+
+
+ );
+}
+```
+
+### Form Submission Error Handling
+
+```javascript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import * as z from 'zod';
+import { toast } from 'sonner';
+
+const schema = z.object({
+ name: z.string().min(1, 'Name is required'),
+ description: z.string().min(10, 'Description must be at least 10 characters'),
+});
+
+function CreateActivityForm() {
+ const { register, handleSubmit, setError, formState: { errors, isSubmitting } } = useForm({
+ resolver: zodResolver(schema),
+ });
+
+ const onSubmit = async (data) => {
+ try {
+ await base44Client.entities.Activity.create(data);
+ toast.success('Activity created');
+ } catch (error) {
+ console.error('Form submission error:', error);
+
+ // Handle field-specific errors
+ if (error.status === 422 && error.data?.errors) {
+ // Set form errors from API response
+ Object.entries(error.data.errors).forEach(([field, message]) => {
+ setError(field, { type: 'manual', message });
+ });
+ } else {
+ // General error
+ toast.error('Failed to create activity');
+ }
+ }
+ };
+
+ return (
+
+ );
+}
+```
+
+## Global Error Handlers
+
+### Window Error Handler
+
+```javascript
+// src/utils/errorHandlers.js
+export function setupGlobalErrorHandlers() {
+ // Catch unhandled errors
+ window.addEventListener('error', (event) => {
+ console.error('Unhandled error:', event.error);
+
+ // Log to error tracking
+ if (window.Sentry) {
+ window.Sentry.captureException(event.error);
+ }
+
+ // Prevent default error display
+ event.preventDefault();
+ });
+
+ // Catch unhandled promise rejections
+ window.addEventListener('unhandledrejection', (event) => {
+ console.error('Unhandled promise rejection:', event.reason);
+
+ // Log to error tracking
+ if (window.Sentry) {
+ window.Sentry.captureException(event.reason);
+ }
+
+ // Show user-friendly message
+ toast.error('An unexpected error occurred');
+
+ // Prevent default
+ event.preventDefault();
+ });
+}
+
+// Call in main.jsx
+import { setupGlobalErrorHandlers } from './utils/errorHandlers';
+
+setupGlobalErrorHandlers();
+```
+
+## Logging Utilities
+
+### Logger Service
+
+```javascript
+// src/services/logger.js
+class Logger {
+ constructor() {
+ this.isDevelopment = process.env.NODE_ENV === 'development';
+ }
+
+ log(level, message, data = {}) {
+ const logEntry = {
+ level,
+ message,
+ data,
+ timestamp: new Date().toISOString(),
+ url: window.location.href,
+ userAgent: navigator.userAgent,
+ };
+
+ // Console logging (development only)
+ if (this.isDevelopment) {
+ console[level](message, data);
+ }
+
+ // Send to backend for persistence
+ this.sendToBackend(logEntry);
+
+ // Send to external service
+ this.sendToExternalService(logEntry);
+ }
+
+ info(message, data) {
+ this.log('info', message, data);
+ }
+
+ warn(message, data) {
+ this.log('warn', message, data);
+ }
+
+ error(message, error, data = {}) {
+ this.log('error', message, {
+ ...data,
+ error: error?.toString(),
+ stack: error?.stack,
+ });
+ }
+
+ debug(message, data) {
+ if (this.isDevelopment) {
+ this.log('debug', message, data);
+ }
+ }
+
+ async sendToBackend(logEntry) {
+ try {
+ await fetch('/api/logs', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(logEntry),
+ });
+ } catch (error) {
+ console.error('Failed to send log to backend:', error);
+ }
+ }
+
+ sendToExternalService(logEntry) {
+ try {
+ if (window.Sentry && logEntry.level === 'error') {
+ window.Sentry.captureMessage(logEntry.message, {
+ level: logEntry.level,
+ extra: logEntry.data,
+ });
+ }
+ } catch (error) {
+ console.error('Failed to send log to external service:', error);
+ }
+ }
+}
+
+export const logger = new Logger();
+
+// Usage
+import { logger } from '@/services/logger';
+
+logger.info('User logged in', { userId: user.id });
+logger.error('API call failed', error, { endpoint: '/activities' });
+logger.debug('Component rendered', { props });
+```
+
+## User-Facing Error Messages
+
+### Error Message Component
+
+```javascript
+// src/components/common/ErrorMessage.jsx
+import { AlertCircle } from 'lucide-react';
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
+import { Button } from '@/components/ui/button';
+
+export default function ErrorMessage({ error, onRetry, onDismiss }) {
+ return (
+
+ Error
+
+ {error?.message || 'Something went wrong'}
+
+ {onRetry && (
+
+ Try Again
+
+ )}
+ {onDismiss && (
+
+ Dismiss
+
+ )}
+
+
+
+ );
+}
+
+// Usage
+function ActivitiesList() {
+ const { data, isLoading, error, refetch } = useActivities();
+
+ if (error) {
+ return navigate('/activities/new')}>
+ Create Activity
+
+ }
+ />
+ );
+ }
+
+ return (
+
+ {activities.map(activity => (
+
+ ))}
+
+
+ );
+
+ expect(screen.getByText(/something went wrong/i)).toBeInTheDocument();
+
+ spy.mockRestore();
+ });
+
+ it('renders children when no error', () => {
+ render(
+
+ Normal content
+
+ );
+
+ expect(screen.getByText('Normal content')).toBeInTheDocument();
+ });
+});
+```
+
+## Best Practices
+
+### ✅ DO:
+- Wrap async operations in try-catch blocks
+- Use error boundaries around major sections
+- Show user-friendly error messages
+- Log errors for debugging
+- Implement retry logic for transient failures
+- Distinguish between client and server errors
+- Provide actionable error messages
+
+### ❌ DON'T:
+- Silently catch errors without logging
+- Show technical error messages to users
+- Use generic "Something went wrong" for all errors
+- Ignore error recovery options
+- Log sensitive data in errors
+- Let errors crash the entire application
+
+## Related Files
+
+**Error Handling:**
+- `src/components/common/ErrorBoundary.jsx` - Error boundary component
+- `src/api/base44Client.js` - API error handling
+- `src/services/logger.js` - Logging service
+
+**UI Components:**
+- `src/components/ui/alert.jsx` - Alert component for errors
+- `sonner` - Toast notifications library
+
+---
+
+**Last Updated:** February 11, 2026
+**Priority:** HIGH - Critical for production stability
+**Security:** Never log sensitive data (passwords, tokens, PII)
diff --git a/.github/agents/performance-optimizer.agent.md b/.github/agents/performance-optimizer.agent.md
new file mode 100644
index 0000000..e3669e4
--- /dev/null
+++ b/.github/agents/performance-optimizer.agent.md
@@ -0,0 +1,476 @@
+---
+name: "Performance Optimizer"
+description: "Identifies and fixes performance bottlenecks specific to React 18 + Vite 6, including code splitting, lazy loading, bundle analysis, and runtime optimization"
+---
+
+# Performance Optimizer Agent
+
+You are an expert in React performance optimization, specializing in the Interact platform's Vite 6 + React 18 architecture.
+
+## Your Responsibilities
+
+Identify and resolve performance bottlenecks across the Interact platform, focusing on bundle size reduction, runtime performance, and user experience optimization.
+
+## Performance Analysis Tools
+
+### Bundle Analysis
+
+Use Vite's built-in bundle visualization:
+
+```bash
+# Build with bundle analysis
+npm run build
+
+# Analyze bundle with rollup-plugin-visualizer (already in devDependencies)
+# Check dist/ folder size breakdown
+du -sh dist/
+du -h dist/assets/* | sort -hr | head -20
+```
+
+**Current Bundle Stats:**
+- The platform has 117 pages in `src/pages/`
+- 42+ component categories in `src/components/`
+- Large dependencies: Three.js, Recharts, Quill, Framer Motion
+
+### Runtime Performance Monitoring
+
+Check for performance issues:
+- React DevTools Profiler for component render times
+- Chrome DevTools Performance tab
+- Lighthouse audits (target: 90+ performance score)
+- Core Web Vitals: LCP, FID, CLS
+
+## Optimization Strategies
+
+### 1. Code Splitting & Lazy Loading
+
+**Pattern for Pages (HIGH PRIORITY):**
+
+In a naive setup, all 117 pages would be imported eagerly, which hurts bundle size and initial load. **This repo already uses lazy loading via `src/pages.config.js` and `Suspense` in `src/App.jsx` — do not revert to eager imports.** When optimizing or adding new pages, extend this pattern:
+
+```javascript
+// In src/pages.config.js
+import { lazy } from 'react';
+
+export const pagesConfig = {
+ Dashboard: lazy(() => import('./pages/Dashboard')),
+ Activities: lazy(() => import('./pages/Activities')),
+ TeamDashboard: lazy(() => import('./pages/TeamDashboard')),
+ // ...add additional pages here using React.lazy
+};
+
+// In src/App.jsx
+import { Suspense } from 'react';
+import { pagesConfig } from './pages.config';
+import { Loading } from '@/components/common/Loading';
+
+export function App() {
+ return (
+
+ setShowChart(true)}>Show Chart
+ {showChart && (
+
+ );
+}
+```
+
+**Priority for Lazy Loading:**
+1. All 117 pages in `src/pages/`
+2. Rich text editor (Quill) in `src/components/`
+3. Charts (Recharts) in `src/components/analytics/`
+4. 3D graphics (Three.js) if used in components
+5. Heavy modals and dialogs
+
+### 2. React Performance Optimization
+
+**Use React.memo for Pure Components:**
+
+```javascript
+import { memo } from 'react';
+
+// BEFORE - Re-renders on every parent update
+export default function ActivityCard({ activity }) {
+ return {activity.name} ;
+}
+
+// AFTER - Only re-renders when activity changes
+export default memo(function ActivityCard({ activity }) {
+ return {activity.name} ;
+});
+```
+
+**When to use memo:**
+- List items (ActivityCard, BadgeItem, LeaderboardEntry)
+- Expensive components with many child elements
+- Components receiving stable props
+- Components in frequently updating parents
+
+**Use useMemo for Expensive Calculations:**
+
+```javascript
+import { useMemo } from 'react';
+
+function LeaderboardPage({ users }) {
+ // BEFORE - Recalculates on every render
+ const sortedUsers = [...users].sort((a, b) => b.points - a.points);
+
+ // AFTER - Only recalculates when users change
+ const sortedUsers = useMemo(
+ () => [...users].sort((a, b) => b.points - a.points),
+ [users]
+ );
+
+ return
+
+ {virtualizer.getVirtualItems().map(virtualRow => (
+
+
+ ))}
+
+
handleClick(id)}>Click
+
+ // GOOD
+ const handleClickWrapper = useCallback(() => handleClick(id), [id]);
+ Click
+ ```
+
+- Load all components eagerly
+- Skip `loading="lazy"` on images
+- Ignore TanStack Query cache configuration
+
+**✅ DO:**
+- Use tree-shaking friendly imports
+- Lazy load routes and heavy components
+- Use React.memo, useMemo, useCallback appropriately
+- Implement proper loading states
+- Monitor bundle size on every build
+- Use Lighthouse CI in GitHub Actions
+
+## Verification Steps
+
+After making performance optimizations:
+
+```bash
+# 1. Build and check bundle size
+npm run build
+du -sh dist/
+
+# 2. Compare before/after
+echo "Before: XYZ MB"
+echo "After: XYZ MB"
+echo "Savings: XYZ%"
+
+# 3. Test locally
+npm run preview
+
+# 4. Run Lighthouse audit
+# Use Chrome DevTools → Lighthouse → Desktop/Mobile
+
+# 5. Verify no broken lazy loads
+# Test all routes and components
+```
+
+## Performance Targets
+
+**Bundle Size:**
+- Total dist/ folder: < 3MB (uncompressed)
+- Initial JS bundle: < 500KB (gzipped)
+- Each page chunk: < 100KB (gzipped)
+
+**Runtime Performance:**
+- Lighthouse Performance score: 90+
+- LCP (Largest Contentful Paint): < 2.5s
+- FID (First Input Delay): < 100ms
+- CLS (Cumulative Layout Shift): < 0.1
+- Time to Interactive: < 3.5s
+
+**Memory Usage:**
+- No memory leaks in React DevTools
+- Heap size stable after navigation
+- No unbounded array growth
+
+## Related Files
+
+**Key Performance Files:**
+- `vite.config.js` - Build configuration and chunking
+- `src/lib/imageUtils.js` - Image optimization helper
+- `src/App.jsx` - Main app, add lazy loading here
+- `package.json` - Dependencies to optimize
+- `.github/workflows/ci.yml` - Add Lighthouse CI
+
+## Related Documentation
+
+- [Vite Build Optimization](https://vitejs.dev/guide/build.html)
+- [React Performance](https://react.dev/learn/render-and-commit)
+- [TanStack Query Performance](https://tanstack.com/query/latest/docs/react/guides/performance)
+- [Web.dev Performance](https://web.dev/performance/)
+
+---
+
+**Last Updated:** February 11, 2026
+**Priority:** HIGH - Current bundle not optimized for 117 pages
+**Estimated Impact:** 40-60% bundle size reduction, 2-3x faster initial load
diff --git a/.github/agents/pwa-implementation.agent.md b/.github/agents/pwa-implementation.agent.md
new file mode 100644
index 0000000..b4111a9
--- /dev/null
+++ b/.github/agents/pwa-implementation.agent.md
@@ -0,0 +1,770 @@
+---
+name: "PWA Implementation Specialist"
+description: "Implements Progressive Web App features including service workers, offline support, installability, and push notifications for Interact's mobile-first design"
+---
+
+# PWA Implementation Specialist Agent
+
+You are an expert in Progressive Web Apps (PWA), specializing in implementing offline-first capabilities, installability, and native app-like experiences for the Interact platform.
+
+## Your Responsibilities
+
+Transform Interact into a Progressive Web App with offline support, installability, push notifications, and optimal mobile performance.
+
+## PWA Requirements Checklist
+
+### Core Requirements
+- [ ] HTTPS (required for service workers)
+- [ ] Web App Manifest
+- [ ] Service Worker
+- [ ] Responsive design (already implemented)
+- [ ] Offline fallback page
+
+### Enhanced Features
+- [ ] Background sync
+- [ ] Push notifications
+- [ ] Add to Home Screen prompt
+- [ ] App-like navigation
+- [ ] Splash screens
+
+## Web App Manifest
+
+### Create manifest.json
+
+```json
+// public/manifest.json
+{
+ "name": "Interact - Employee Engagement Platform",
+ "short_name": "Interact",
+ "description": "Transform workplace culture through gamification, AI-powered personalization, and team activity management",
+ "start_url": "/",
+ "scope": "/",
+ "display": "standalone",
+ "theme_color": "#3b82f6",
+ "background_color": "#ffffff",
+ "orientation": "portrait-primary",
+ "icons": [
+ {
+ "src": "/icons/icon-72x72.png",
+ "sizes": "72x72",
+ "type": "image/png",
+ "purpose": "any maskable"
+ },
+ {
+ "src": "/icons/icon-96x96.png",
+ "sizes": "96x96",
+ "type": "image/png",
+ "purpose": "any maskable"
+ },
+ {
+ "src": "/icons/icon-128x128.png",
+ "sizes": "128x128",
+ "type": "image/png",
+ "purpose": "any maskable"
+ },
+ {
+ "src": "/icons/icon-144x144.png",
+ "sizes": "144x144",
+ "type": "image/png",
+ "purpose": "any maskable"
+ },
+ {
+ "src": "/icons/icon-152x152.png",
+ "sizes": "152x152",
+ "type": "image/png",
+ "purpose": "any maskable"
+ },
+ {
+ "src": "/icons/icon-192x192.png",
+ "sizes": "192x192",
+ "type": "image/png",
+ "purpose": "any maskable"
+ },
+ {
+ "src": "/icons/icon-384x384.png",
+ "sizes": "384x384",
+ "type": "image/png",
+ "purpose": "any maskable"
+ },
+ {
+ "src": "/icons/icon-512x512.png",
+ "sizes": "512x512",
+ "type": "image/png",
+ "purpose": "any maskable"
+ }
+ ],
+ "shortcuts": [
+ {
+ "name": "Dashboard",
+ "short_name": "Dashboard",
+ "description": "View your engagement dashboard",
+ "url": "/dashboard",
+ "icons": [{ "src": "/icons/dashboard.png", "sizes": "96x96" }]
+ },
+ {
+ "name": "Activities",
+ "short_name": "Activities",
+ "description": "Browse team activities",
+ "url": "/activities",
+ "icons": [{ "src": "/icons/activities.png", "sizes": "96x96" }]
+ },
+ {
+ "name": "Leaderboard",
+ "short_name": "Leaderboard",
+ "description": "Check your ranking",
+ "url": "/leaderboard",
+ "icons": [{ "src": "/icons/leaderboard.png", "sizes": "96x96" }]
+ }
+ ],
+ "screenshots": [
+ {
+ "src": "/screenshots/desktop-dashboard.png",
+ "sizes": "1920x1080",
+ "type": "image/png",
+ "form_factor": "wide"
+ },
+ {
+ "src": "/screenshots/mobile-dashboard.png",
+ "sizes": "750x1334",
+ "type": "image/png",
+ "form_factor": "narrow"
+ }
+ ],
+ "categories": ["productivity", "social", "lifestyle"],
+ "iarc_rating_id": "e84b072d-71b3-4d3e-86ae-31a8ce4e53b7"
+}
+```
+
+### Link Manifest in HTML
+
+```html
+
+
+
+
+
+ Offline - Interact
+
+
+
+
+
You're Offline
+
It looks like you've lost your internet connection. Please check your network and try again.
+
Try Again
+
+ {!isOnline && (
+
+ You're currently offline. Some features may not be available.
+
+ )}
+
+ {/* App content */}
+
+
+
+
Install Interact
+
+
+
+
+ Install Interact on your device for quick access and offline support
+
+
+
+
+ Install
+
+
+ Not Now
+
+
+
+ );
+}
+
+// Add to Layout.jsx
+import InstallPrompt from '@/components/pwa/InstallPrompt';
+
+export default function Layout() {
+ return (
+
+ {/* ... app content ... */}
+
+ );
+}
+```
+
+## Push Notifications
+
+### Request Permission
+
+```javascript
+// src/services/notifications.js
+export async function requestNotificationPermission() {
+ if (!('Notification' in window)) {
+ console.log('This browser does not support notifications');
+ return false;
+ }
+
+ if (Notification.permission === 'granted') {
+ return true;
+ }
+
+ if (Notification.permission !== 'denied') {
+ const permission = await Notification.requestPermission();
+ return permission === 'granted';
+ }
+
+ return false;
+}
+
+export function showNotification(title, options = {}) {
+ if (Notification.permission === 'granted') {
+ const notification = new Notification(title, {
+ icon: '/icons/icon-192x192.png',
+ badge: '/icons/badge-72x72.png',
+ ...options,
+ });
+
+ notification.onclick = () => {
+ window.focus();
+ notification.close();
+ };
+
+ return notification;
+ }
+}
+
+// Usage
+import { requestNotificationPermission, showNotification } from '@/services/notifications';
+
+async function notifyUser() {
+ const granted = await requestNotificationPermission();
+
+ if (granted) {
+ showNotification('New Activity!', {
+ body: 'Team lunch scheduled for tomorrow at noon',
+ tag: 'activity-123',
+ requireInteraction: true,
+ });
+ }
+}
+```
+
+## Background Sync
+
+```javascript
+// Register background sync
+if ('serviceWorker' in navigator && 'SyncManager' in window) {
+ navigator.serviceWorker.ready.then((registration) => {
+ return registration.sync.register('sync-activities');
+ });
+}
+
+// In service worker (sw.js)
+self.addEventListener('sync', (event) => {
+ if (event.tag === 'sync-activities') {
+ event.waitUntil(syncActivities());
+ }
+});
+
+async function syncActivities() {
+ // Fetch and sync pending activities
+ const cache = await caches.open('pending-activities');
+ const requests = await cache.keys();
+
+ for (const request of requests) {
+ try {
+ const response = await fetch(request);
+ if (response.ok) {
+ await cache.delete(request);
+ }
+ } catch (error) {
+ console.error('Sync failed:', error);
+ }
+ }
+}
+```
+
+## PWA Testing
+
+### Lighthouse Audit
+
+```bash
+# Run Lighthouse audit in Chrome DevTools
+# Navigate to Lighthouse tab
+# Select "Progressive Web App" category
+# Run audit
+
+# Target scores:
+# PWA: 100
+# Performance: 90+
+# Accessibility: 100
+# Best Practices: 95+
+# SEO: 90+
+```
+
+### PWA Builder
+
+Use [PWABuilder.com](https://www.pwabuilder.com/) to:
+- Validate manifest
+- Generate app packages for stores
+- Test PWA features
+- Get improvement recommendations
+
+## App Store Submission
+
+### Google Play Store (TWA)
+
+```bash
+# Generate Trusted Web Activity
+# Use Bubblewrap CLI
+npm install -g @bubblewrap/cli
+
+# Initialize TWA project
+bubblewrap init --manifest=https://interact.app/manifest.json
+
+# Build APK
+bubblewrap build
+
+# Upload to Google Play Console
+```
+
+### Apple App Store
+
+Use Capacitor for iOS app:
+
+```bash
+# Install Capacitor (already in devDependencies)
+npm install @capacitor/core @capacitor/cli @capacitor/ios
+
+# Initialize Capacitor
+npx cap init
+
+# Add iOS platform
+npx cap add ios
+
+# Open in Xcode
+npx cap open ios
+
+# Build and submit to App Store Connect
+```
+
+## Performance Optimization for PWA
+
+```javascript
+// Lazy load non-critical resources
+import { lazy, Suspense } from 'react';
+
+const HeavyComponent = lazy(() => import('./HeavyComponent'));
+
+// Use Intersection Observer for images
+import { useEffect, useRef } from 'react';
+
+function LazyImage({ src, alt }) {
+ const imgRef = useRef();
+
+ useEffect(() => {
+ const observer = new IntersectionObserver((entries) => {
+ entries.forEach((entry) => {
+ if (entry.isIntersecting) {
+ imgRef.current.src = src;
+ observer.unobserve(imgRef.current);
+ }
+ });
+ });
+
+ if (imgRef.current) {
+ observer.observe(imgRef.current);
+ }
+
+ return () => observer.disconnect();
+ }, [src]);
+
+ return
+
+ {/* Public routes */}
+
+
+
+ {/* 404 Not Found */}
+
+
+
+
+ );
+}
+
+// In main router
+
+ Go Back
+
+
+ );
+}
+```
+
+### 2. Link Navigation
+
+```javascript
+import { Link, NavLink } from 'react-router-dom';
+
+function Navigation() {
+ return (
+
+ {/* Standard Link */}
+
+ isActive ? 'nav-link active' : 'nav-link'
+ }
+ >
+ Activities
+
+
+ {/* Link with state */}
+
+ );
+}
+```
+
+### 3. Search Params Navigation
+
+```javascript
+import { useSearchParams } from 'react-router-dom';
+
+function ActivitiesPage() {
+ const [searchParams, setSearchParams] = useSearchParams();
+
+ // Get params
+ const category = searchParams.get('category') || 'all';
+ const search = searchParams.get('search') || '';
+
+ // Update params
+ const updateFilters = (newFilters) => {
+ const params = new URLSearchParams(searchParams);
+ Object.entries(newFilters).forEach(([key, value]) => {
+ if (value) {
+ params.set(key, value);
+ } else {
+ params.delete(key);
+ }
+ });
+ setSearchParams(params);
+ };
+
+ return (
+
+ updateFilters({ category: e.target.value })}
+ >
+ All Categories
+ Wellness
+ Learning
+
+
+
+ );
+}
+```
+
+## Route Configuration Best Practices
+
+### 1. Route Constants
+
+Create a centralized route configuration:
+
+```javascript
+// src/routes/routes.js
+export const ROUTES = {
+ HOME: '/',
+ LOGIN: '/login',
+ DASHBOARD: '/dashboard',
+ ACTIVITIES: '/activities',
+ ACTIVITY_DETAIL: '/activities/:id',
+ ACTIVITY_NEW: '/activities/new',
+ GAMIFICATION: '/gamification',
+ LEADERBOARD: '/leaderboard',
+ TEAM_DASHBOARD: '/teams/:teamId',
+ PROFILE: '/profile/:userId',
+ SETTINGS: '/settings',
+ ADMIN: '/admin',
+ // ... more routes
+};
+
+// Usage
+import { ROUTES } from '@/routes/routes';
+
+Dashboard content
;
+}
+```
+
+## Advanced Routing Patterns
+
+### 1. Route Guards with Conditions
+
+```javascript
+// src/components/routing/ConditionalRoute.jsx
+import { Navigate, Outlet } from 'react-router-dom';
+
+export default function ConditionalRoute({ condition, redirectTo }) {
+ if (!condition) {
+ return
+
+
+
+
+
+
+
+
Oops!
+
+ {error?.message || 'Something went wrong'}
+
+
+
+
+ window.location.reload()}>
+ Reload Page
+
+
+
+
+ {/* routes */}
+
+
+```
+
+### 5. Navigation Tracking
+
+**Existing:** `src/lib/NavigationTracker.jsx`
+
+Use this to track page views for analytics:
+
+```javascript
+// src/lib/NavigationTracker.jsx
+import { useEffect } from 'react';
+import { useLocation } from 'react-router-dom';
+
+export default function NavigationTracker() {
+ const location = useLocation();
+
+ useEffect(() => {
+ // Track page view
+ console.log('Page view:', location.pathname);
+
+ // Send to analytics
+ if (window.gtag) {
+ window.gtag('event', 'page_view', {
+ page_path: location.pathname,
+ });
+ }
+ }, [location]);
+
+ return null;
+}
+
+// Add to router
+
+
+ {/* routes */}
+
+
+```
+
+## Common Routing Patterns for Interact
+
+### 1. Detail Pages with ID
+
+```javascript
+// Route definition
+
+
{activity.name}
+ {/* activity details */}
+
+ );
+}
+```
+
+### 2. Tab Navigation
+
+```javascript
+import { useLocation, Link } from 'react-router-dom';
+import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs';
+
+function ProfilePage() {
+ const location = useLocation();
+ const currentTab = location.pathname.split('/').pop();
+
+ return (
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ );
+}
+```
+
+### 3. Modal Routes
+
+```javascript
+// Show modal over current page without navigation
+import { useLocation, useNavigate } from 'react-router-dom';
+import { Dialog } from '@/components/ui/dialog';
+
+function ActivitiesPage() {
+ const location = useLocation();
+ const navigate = useNavigate();
+ const showModal = location.state?.showCreateModal;
+
+ return (
+
+ navigate('/activities', { state: { showCreateModal: true } })}>
+ Create Activity
+
+
+ {
+ if (!open) navigate('/activities');
+ }}>
+
+
+ {/* Activity list */}
+
+ );
+}
+```
+
+## Breadcrumbs Implementation
+
+```javascript
+// src/components/common/Breadcrumbs.jsx
+import { Link, useLocation } from 'react-router-dom';
+import { ChevronRight } from 'lucide-react';
+
+export default function Breadcrumbs() {
+ const location = useLocation();
+ const pathSegments = location.pathname.split('/').filter(Boolean);
+
+ const breadcrumbs = pathSegments.map((segment, index) => {
+ const path = `/${pathSegments.slice(0, index + 1).join('/')}`;
+ const label = segment.charAt(0).toUpperCase() + segment.slice(1);
+
+ return { path, label };
+ });
+
+ return (
+
+
+ {crumb.label}
+ ) : (
+
+ ))}
+
+ );
+}
+```
+
+## Route Organization for 117 Pages
+
+### Grouping Strategy
+
+```javascript
+// src/routes/index.js
+import { lazy } from 'react';
+
+// Group routes by feature area
+export const dashboardRoutes = [
+ { path: '/dashboard', component: lazy(() => import('@/pages/Dashboard')) },
+ { path: '/team-dashboard', component: lazy(() => import('@/pages/TeamDashboard')) },
+ { path: '/facilitator-dashboard', component: lazy(() => import('@/pages/FacilitatorDashboard')) },
+];
+
+export const activityRoutes = [
+ { path: '/activities', component: lazy(() => import('@/pages/Activities')) },
+ { path: '/activities/:id', component: lazy(() => import('@/pages/ActivityDetail')) },
+ { path: '/activities/new', component: lazy(() => import('@/pages/CreateActivity')) },
+];
+
+export const gamificationRoutes = [
+ { path: '/gamification', component: lazy(() => import('@/pages/Gamification')) },
+ { path: '/leaderboard', component: lazy(() => import('@/pages/Leaderboard')) },
+ { path: '/badges', component: lazy(() => import('@/pages/Badges')) },
+ { path: '/rewards', component: lazy(() => import('@/pages/Rewards')) },
+];
+
+// ... more route groups
+```
+
+## Performance Optimization
+
+### 1. Lazy Loading
+
+```javascript
+// ALWAYS lazy load pages for better bundle size
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+const Activities = lazy(() => import('./pages/Activities'));
+// ... 115 more lazy imports
+```
+
+### 2. Prefetching
+
+```javascript
+// Prefetch route on hover
+import { Link } from 'react-router-dom';
+
+function NavigationLink({ to, children }) {
+ const prefetch = () => {
+ // Webpack/Vite will prefetch the chunk
+ import(`./pages/${to}`);
+ };
+
+ return (
+
+
+
+
+ );
+
+ expect(screen.getByText(/dashboard/i)).toBeInTheDocument();
+ });
+
+ it('redirects to login when not authenticated', () => {
+ // Test protected routes
+ });
+});
+```
+
+## Related Files
+
+**Key Routing Files:**
+- `src/App.jsx` - Main router configuration
+- `src/Layout.jsx` - Layout wrapper for routes
+- `src/lib/NavigationTracker.jsx` - Analytics tracking
+- `src/lib/PageNotFound.jsx` - 404 page
+- `src/pages/` - All 117 page components
+
+**Related Documentation:**
+- [React Router v6 Docs](https://reactrouter.com/en/main)
+
+---
+
+**Last Updated:** February 11, 2026
+**Priority:** HIGH - Central to navigation for 117 pages
+**Security Note:** Always use XSS-safe navigation (fixed in v6.26.0)
diff --git a/.github/agents/state-management-expert.agent.md b/.github/agents/state-management-expert.agent.md
new file mode 100644
index 0000000..57c307a
--- /dev/null
+++ b/.github/agents/state-management-expert.agent.md
@@ -0,0 +1,698 @@
+---
+name: "State Management Expert"
+description: "Implements state management using React Context API + TanStack Query patterns specific to Interact's architecture, avoiding prop drilling and managing global app state"
+---
+
+# State Management Expert Agent
+
+You are an expert in React state management, specializing in the Interact platform's Context API + TanStack Query 5.84.1 architecture.
+
+## Your Responsibilities
+
+Implement and optimize state management across the Interact platform using the established patterns: React Context API for UI state and TanStack Query for server state.
+
+## State Management Architecture
+
+### Two-Tier State Model
+
+**1. UI State (React Context API):**
+- Authentication state
+- Theme/dark mode
+- User preferences
+- UI toggles and modals
+- Navigation state
+- Notification state
+
+**2. Server State (TanStack Query):**
+- Activities data
+- User profiles
+- Gamification data (points, badges, leaderboards)
+- Analytics data
+- Team information
+- Backend responses
+
+## Existing Context Providers
+
+### Authentication Context
+
+**Location:** `src/lib/AuthContext.jsx`
+
+```javascript
+// Usage in components
+import { useAuth } from '@/lib/AuthContext';
+
+function MyComponent() {
+ const { user, isAuthenticated, login, logout } = useAuth();
+
+ if (!isAuthenticated) {
+ return Welcome {user.name}
;
+}
+```
+
+**Available from AuthContext:**
+- `user` - Current user object
+- `isAuthenticated` - Boolean auth status
+- `login(credentials)` - Login function
+- `logout()` - Logout function
+- `loading` - Auth loading state
+
+### Creating New Context Providers
+
+**Standard Pattern for Interact:**
+
+```javascript
+// src/contexts/NotificationContext.jsx
+import { createContext, useContext, useState, useCallback } from 'react';
+
+const NotificationContext = createContext(undefined);
+
+export function NotificationProvider({ children }) {
+ const [notifications, setNotifications] = useState([]);
+ const [unreadCount, setUnreadCount] = useState(0);
+
+ const addNotification = useCallback((notification) => {
+ setNotifications(prev => [notification, ...prev]);
+ setUnreadCount(prev => prev + 1);
+ }, []);
+
+ const markAsRead = useCallback((notificationId) => {
+ setNotifications(prev =>
+ prev.map(n => n.id === notificationId ? { ...n, read: true } : n)
+ );
+ setUnreadCount(prev => Math.max(0, prev - 1));
+ }, []);
+
+ const clearAll = useCallback(() => {
+ setNotifications([]);
+ setUnreadCount(0);
+ }, []);
+
+ const value = {
+ notifications,
+ unreadCount,
+ addNotification,
+ markAsRead,
+ clearAll,
+ };
+
+ return (
+
+ {children}
+
+ );
+}
+
+export function useNotifications() {
+ const context = useContext(NotificationContext);
+ if (context === undefined) {
+ throw new Error('useNotifications must be used within NotificationProvider');
+ }
+ return context;
+}
+```
+
+### Provider Composition Pattern
+
+**In src/App.jsx or src/main.jsx:**
+
+```javascript
+import { QueryClientProvider } from '@tanstack/react-query';
+import { AuthProvider } from '@/lib/AuthContext';
+import { ThemeProvider } from '@/contexts/ThemeContext';
+import { NotificationProvider } from '@/contexts/NotificationContext';
+import { queryClient } from '@/lib/query-client';
+
+function App() {
+ return (
+
+
+
+
+
+
+
+
+ );
+}
+```
+
+## TanStack Query Patterns
+
+### Query Configuration
+
+**Location:** `src/lib/query-client.js`
+
+Current setup:
+```javascript
+import { QueryClient } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient({
+ defaultOptions: {
+ queries: {
+ staleTime: 1000 * 60 * 5, // 5 minutes
+ gcTime: 1000 * 60 * 10, // 10 minutes
+ retry: 1,
+ refetchOnWindowFocus: false,
+ },
+ },
+});
+```
+
+### Standard Query Pattern
+
+```javascript
+// Custom hook pattern (RECOMMENDED)
+// src/hooks/useActivities.js
+import { useQuery } from '@tanstack/react-query';
+import { base44Client } from '@/api/base44Client';
+
+export function useActivities(filters = {}) {
+ return useQuery({
+ queryKey: ['activities', filters],
+ queryFn: async () => {
+ const response = await base44Client.entities.Activity.list(filters);
+ return response.data;
+ },
+ staleTime: 5 * 60 * 1000, // 5 minutes
+ enabled: true, // Can be conditional based on auth, etc.
+ });
+}
+
+// Usage in components
+import { useActivities } from '@/hooks/useActivities';
+
+function ActivitiesList() {
+ const { data: activities, isLoading, error } = useActivities();
+
+ if (isLoading) return
+ {activities.map(activity => (
+
+ ))}
+
{activity.name}
+
+ );
+}
+```
+
+### Pagination Pattern
+
+```javascript
+// src/hooks/useActivitiesPaginated.js
+import { useInfiniteQuery } from '@tanstack/react-query';
+
+export function useActivitiesPaginated(filters = {}) {
+ return useInfiniteQuery({
+ queryKey: ['activities', 'infinite', filters],
+ queryFn: async ({ pageParam = 1 }) => {
+ const response = await base44Client.entities.Activity.list({
+ ...filters,
+ page: pageParam,
+ limit: 20,
+ });
+ return response.data;
+ },
+ initialPageParam: 1,
+ getNextPageParam: (lastPage, allPages) => {
+ return lastPage.hasMore ? allPages.length + 1 : undefined;
+ },
+ });
+}
+
+// Usage with infinite scroll
+function ActivitiesInfiniteList() {
+ const {
+ data,
+ fetchNextPage,
+ hasNextPage,
+ isFetchingNextPage,
+ } = useActivitiesPaginated();
+
+ return (
+
+ {data?.pages.map((page, i) => (
+
+ {page.items.map(activity => (
+
+ ))}
+ {hasNextPage && (
+
fetchNextPage()} disabled={isFetchingNextPage}>
+ {isFetchingNextPage ? 'Loading...' : 'Load More'}
+
+ )}
+
{fullName}
;
+}
+
+// ✅ GOOD - Compute derived state
+function UserProfile({ user }) {
+ const fullName = `${user.firstName} ${user.lastName}`;
+ return {fullName}
;
+}
+```
+
+### 2. Lifting State Up
+
+```javascript
+// When multiple components need shared state, lift to common ancestor
+
+// ❌ BAD - Duplicated state
+function ActivityFilters() {
+ const [category, setCategory] = useState('all');
+ // ...
+}
+
+function ActivityList() {
+ const [category, setCategory] = useState('all'); // Duplicate!
+ // ...
+}
+
+// ✅ GOOD - Lifted state
+function ActivitiesPage() {
+ const [category, setCategory] = useState('all');
+
+ return (
+ <>
+
+
+
+
+
+
+
+
+
+
+
+// ✅ GOOD - Compose providers in a single component
+function AppProviders({ children }) {
+ return (
+
+
+
+
+ {children}
+
+
+
+
+ );
+}
+
+// Usage
+
+
+```
+
+### 2. Over-Using Context (Performance)
+
+```javascript
+// ❌ BAD - Single large context causes unnecessary re-renders
+const AppContext = createContext();
+
+function AppProvider({ children }) {
+ const [user, setUser] = useState(null);
+ const [theme, setTheme] = useState('light');
+ const [notifications, setNotifications] = useState([]);
+ // ... 10 more states
+
+ return (
+
+ {children}
+
+ );
+}
+
+// ✅ GOOD - Split contexts by concern
+// AuthContext, ThemeContext, NotificationContext (separate files)
+```
+
+### 3. Stale Closures in useCallback
+
+```javascript
+// ❌ BAD - Stale closure
+function Counter() {
+ const [count, setCount] = useState(0);
+
+ const increment = useCallback(() => {
+ setCount(count + 1); // 'count' is stale
+ }, []); // Missing dependency
+
+ return Count: {count} ;
+}
+
+// ✅ GOOD - Functional update
+function Counter() {
+ const [count, setCount] = useState(0);
+
+ const increment = useCallback(() => {
+ setCount(prev => prev + 1); // Always has latest state
+ }, []); // No dependencies needed
+
+ return Count: {count} ;
+}
+```
+
+## Query Key Conventions
+
+Use consistent, hierarchical query keys:
+
+```javascript
+// User-related queries
+['user', userId]
+['user', userId, 'profile']
+['user', userId, 'activities']
+['users'] // All users list
+
+// Activity queries
+['activities'] // All activities
+['activities', { category, status }] // Filtered activities
+['activity', activityId] // Single activity
+['activity', activityId, 'participants'] // Activity participants
+
+// Gamification queries
+['leaderboard']
+['leaderboard', { period: 'week' }]
+['user', userId, 'badges']
+['user', userId, 'points']
+```
+
+## Performance Optimization
+
+### 1. Memoize Context Values
+
+```javascript
+function NotificationProvider({ children }) {
+ const [notifications, setNotifications] = useState([]);
+
+ // ✅ GOOD - Memoize value object
+ const value = useMemo(() => ({
+ notifications,
+ addNotification: (n) => setNotifications(prev => [...prev, n]),
+ clearAll: () => setNotifications([]),
+ }), [notifications]);
+
+ return (
+
+ {children}
+
+ );
+}
+```
+
+### 2. Split Large Contexts
+
+If a context causes too many re-renders, split it:
+
+```javascript
+// Instead of one UserContext with all user data
+// Create focused contexts
+UserAuthContext // auth state, login, logout
+UserProfileContext // profile data
+UserPreferencesContext // theme, language, etc.
+```
+
+### 3. Use Query Selectors
+
+```javascript
+// Only subscribe to part of query data
+function UserName({ userId }) {
+ const { data: name } = useQuery({
+ queryKey: ['user', userId],
+ queryFn: fetchUser,
+ select: (user) => user.name, // Only re-render if name changes
+ });
+
+ return {name} ;
+}
+```
+
+## Verification Steps
+
+After implementing state management:
+
+```bash
+# 1. Check for prop drilling (more than 2-3 levels deep)
+grep -r "props\." src/components/ | grep -E "props\.props\.props"
+
+# 2. Verify all Context providers have error handling
+grep -A 5 "createContext" src/contexts/
+
+# 3. Check query key consistency
+grep -r "queryKey:" src/hooks/
+
+# 4. Test state persistence across navigation
+npm run dev
+# Navigate between pages, check state retained
+```
+
+## Related Files
+
+**Context Providers:**
+- `src/lib/AuthContext.jsx` - Authentication state
+
+**TanStack Query:**
+- `src/lib/query-client.js` - Query client configuration
+- `src/hooks/` - Custom hooks with queries/mutations
+
+**Related Documentation:**
+- [TanStack Query Docs](https://tanstack.com/query/latest/docs/react/overview)
+- [React Context](https://react.dev/reference/react/useContext)
+
+---
+
+**Last Updated:** February 11, 2026
+**Priority:** HIGH - Foundation for all data management
+**Current State:** AuthContext exists, expand with more contexts