saafe-redirection-flow 2.0.0

package/docs/architecture.md

@@ -0,0 +1,432 @@
+# SAAFE Redirection Flow - Technical Architecture
+
+This document outlines the technical architecture of the SAAFE Redirection Flow application, including its structure, state management, and key technical decisions.
+
+## Application Architecture
+
+The SAAFE Redirection Flow follows a modern React application architecture with the following key characteristics:
+
+- **Component-Based Architecture**: UI elements are broken down into reusable components
+- **Custom Hooks**: Business logic is encapsulated in custom hooks
+- **Context API**: Used for theme management and global state that doesn't require complex updates
+- **Store Management**: Zustand for state that requires more complex updates
+- **Routing**: React Router for navigation between screens
+
+```
+SAAFE Redirection Flow
+│
+├── Core
+│   ├── Routing (React Router)
+│   ├── API Integration (Axios + React Query)
+│   └── State Management (Zustand + Context API)
+│
+├── Features
+│   ├── Authentication
+│   ├── Account Discovery
+│   ├── Consent Management
+│   └── Platform-Specific Behavior
+│
+└── UI Layer
+    ├── Components
+    ├── Pages
+    └── Theming
+```
+
+## Folder Structure
+
+The application follows a feature-based folder structure:
+
+```
+src/
+├── assets/          # Static assets like images and icons
+├── components/      # Reusable UI components
+│   ├── auth/        # Authentication-related components
+│   ├── ui/          # Base UI components (buttons, inputs, etc.)
+│   └── ...
+├── config/          # Configuration files and constants
+├── contexts/        # React context providers
+├── hooks/           # Custom React hooks
+├── interfaces/      # TypeScript interfaces and type definitions
+├── lib/             # Core utilities and helper functions
+├── locales/         # Internationalization resources
+├── pages/           # Page components
+│   ├── accounts/    # Account-related pages
+│   ├── consent/     # Consent flow pages
+│   └── ...
+├── providers/       # Service providers (Query, Toast, etc.)
+├── services/        # API services
+├── store/           # Zustand stores
+├── styles/          # Global styles and theme definitions
+├── utils/           # Utility functions
+├── App.tsx          # Main app component with routing
+└── main.tsx         # Entry point
+```
+
+## State Management
+
+The application uses a hybrid state management approach:
+
+### Local Component State
+
+Used for component-specific state that doesn't need to be shared.
+
+```tsx
+function Counter() {
+  const [count, setCount] = useState(0);
+  
+  return (
+    <button onClick={() => setCount(count + 1)}>
+      Count: {count}
+    </button>
+  );
+}
+```
+
+### Context API
+
+Used for theme management and other global states that don't require complex updates.
+
+```tsx
+// src/contexts/ThemeContext.tsx
+export const ThemeProvider: React.FC<ThemeProviderProps> = ({ 
+  children, 
+  defaultTheme = "system" 
+}) => {
+  // Implementation details
+  
+  return (
+    <ThemeContext.Provider value={{ theme, setTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+};
+```
+
+### Zustand Stores
+
+Used for more complex state management needs, particularly for data that needs to be accessed across multiple components.
+
+```tsx
+// src/store/redirect.store.ts
+export const useRedirectStore = create<RedirectStore>((set, get) => ({
+  decodedInfo: null,
+  setDecodedInfo: (info) => set({ decodedInfo: info }),
+  getCustomStyle: () => {
+    const { decodedInfo } = get();
+    if (!decodedInfo?.styleOptions) return null;
+    return decodedInfo.styleOptions;
+  }
+}));
+```
+
+## Data Fetching
+
+The application uses React Query for data fetching and caching:
+
+```tsx
+// Example of a query hook
+export function useAccounts() {
+  const { decodedInfo } = useRedirectStore();
+  
+  return useQuery({
+    queryKey: ['accounts', decodedInfo?.userId],
+    queryFn: () => fetchAccounts(decodedInfo?.userId),
+    enabled: !!decodedInfo?.userId,
+  });
+}
+```
+
+## Routing and Navigation
+
+React Router v7 is used for routing, with route protection provided by an `AuthGuard` component:
+
+```tsx
+// Protected route example from App.tsx
+<Route
+  path="link-accounts/discovery"
+  element={
+    <AuthGuard>
+      <Discover />
+    </AuthGuard>
+  }
+/>
+```
+
+## Theming
+
+The application supports multiple themes (light, dark, system) using CSS variables and the Context API:
+
+```tsx
+// Theme switching logic
+const switchTheme = (newTheme: Theme) => {
+  // Update theme in context
+  setTheme(newTheme);
+  
+  // Apply theme to document
+  const root = document.documentElement;
+  if (newTheme === 'dark' || (newTheme === 'system' && prefersDarkMode)) {
+    root.classList.add('dark');
+  } else {
+    root.classList.remove('dark');
+  }
+};
+```
+
+## Internationalization
+
+The application uses i18next for internationalization:
+
+```tsx
+// i18n setup
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import LanguageDetector from 'i18next-browser-languagedetector';
+
+i18n
+  .use(LanguageDetector)
+  .use(initReactI18next)
+  .init({
+    resources: {
+      en: { translation: enTranslation },
+      hi: { translation: hiTranslation },
+      // other languages...
+    },
+    fallbackLng: 'en',
+    interpolation: {
+      escapeValue: false,
+    },
+  });
+```
+
+## Form Handling
+
+The application uses React Hook Form with Zod validation:
+
+```tsx
+// Form with validation example
+const formSchema = z.object({
+  username: z.string().min(3, "Username must be at least 3 characters"),
+  password: z.string().min(8, "Password must be at least 8 characters"),
+});
+
+function LoginForm() {
+  const form = useForm<z.infer<typeof formSchema>>({
+    resolver: zodResolver(formSchema),
+    defaultValues: {
+      username: "",
+      password: "",
+    },
+  });
+  
+  // Form handling logic...
+}
+```
+
+## Analytics
+
+The application integrates with PostHog for analytics:
+
+```tsx
+// Analytics tracking example
+import { trackEvent, EVENTS } from "@/utils/posthog";
+
+// In component
+useEffect(() => {
+  trackEvent(EVENTS.PAGE_VIEW, {
+    page: "login",
+    timestamp: new Date().toISOString()
+  });
+}, []);
+```
+
+## Security Features
+
+### URL Parameter Decoding
+
+The application securely decodes URL parameters to extract information:
+
+```tsx
+// URL decoding hook
+export function useUrlDecode() {
+  const [isLoading, setIsLoading] = useState(true);
+  const [isError, setIsError] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const { setDecodedInfo } = useRedirectStore();
+  
+  useEffect(() => {
+    const decodeUrlParams = async () => {
+      try {
+        // Get URL parameters
+        const params = new URLSearchParams(window.location.search);
+        const fi = params.get('fi');
+        const ecreq = params.get('ecreq');
+        const reqdate = params.get('reqdate');
+        
+        // Validate required parameters
+        if (!fi || !ecreq || !reqdate) {
+          throw new Error('Missing required URL parameters');
+        }
+        
+        // Decode encrypted request
+        const decodedInfo = await decodeRequest(fi, ecreq, reqdate);
+        setDecodedInfo(decodedInfo);
+        
+      } catch (err) {
+        setIsError(true);
+        setError(err instanceof Error ? err : new Error('Unknown error'));
+      } finally {
+        setIsLoading(false);
+      }
+    };
+    
+    decodeUrlParams();
+  }, [setDecodedInfo]);
+  
+  return { isLoading, isError, error };
+}
+```
+
+### Navigation Protection
+
+The application prevents accidental navigation away from the flow:
+
+```tsx
+// Navigation block logic
+useEffect(() => {
+  const handleBeforeUnload = (e: BeforeUnloadEvent) => {
+    e.preventDefault();
+    e.returnValue = '';
+  };
+
+  window.addEventListener('beforeunload', handleBeforeUnload);
+  return () => {
+    window.removeEventListener('beforeunload', handleBeforeUnload);
+  };
+}, []);
+```
+
+## Platform-Specific Behavior
+
+The application adapts its behavior based on the platform parameter:
+
+```tsx
+// Platform detection hook
+export function usePlatform() {
+  const { decodedInfo } = useRedirectStore();
+  const platform = decodedInfo?.platform || 'web';
+  
+  const isNativeSDK = ['ios', 'android', 'react-native', 'flutter'].includes(platform);
+  
+  return {
+    platform,
+    isNativeSDK,
+    isIOS: platform === 'ios',
+    isAndroid: platform === 'android',
+    isReactNative: platform === 'react-native',
+    isFlutter: platform === 'flutter',
+    isWeb: platform === 'web',
+  };
+}
+```
+
+## Performance Optimizations
+
+### Code Splitting
+
+React's lazy loading is used for code splitting:
+
+```tsx
+// Lazy loaded components
+const ReviewConsent = React.lazy(() => import('./pages/consent/ReviewConsent'));
+const Success = React.lazy(() => import('./pages/consent/success'));
+```
+
+### Memoization
+
+React.memo and useMemo/useCallback are used to prevent unnecessary re-renders:
+
+```tsx
+// Memoized component example
+const MemoizedComponent = React.memo(({ value }) => {
+  return <div>{value}</div>;
+});
+
+// In parent component
+const handleClick = useCallback(() => {
+  // Handle click
+}, []);
+
+const computedValue = useMemo(() => {
+  return expensiveComputation(value);
+}, [value]);
+```
+
+## Testing Strategy
+
+The application is set up for comprehensive testing:
+
+- **Unit Tests**: For individual components and hooks
+- **Integration Tests**: For feature workflows
+- **Visual Tests**: Using Storybook
+- **E2E Tests**: Using Playwright
+
+```tsx
+// Example test
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import Button from './Button';
+
+test('button calls onClick when clicked', async () => {
+  const handleClick = vi.fn();
+  render(<Button onClick={handleClick}>Click me</Button>);
+  
+  await userEvent.click(screen.getByText('Click me'));
+  
+  expect(handleClick).toHaveBeenCalledTimes(1);
+});
+```
+
+## Build and Deployment
+
+The application uses Vite for fast development and optimized production builds:
+
+```js
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    minify: 'terser',
+    sourcemap: true,
+  },
+  resolve: {
+    alias: {
+      '@': '/src',
+    },
+  },
+});
+```
+
+## Technical Decisions and Tradeoffs
+
+### Why React Router v7?
+
+React Router v7 was chosen for its declarative routing and improved performance over previous versions. The application benefits from nested routes and route-level code splitting.
+
+### Why Zustand over Redux?
+
+Zustand was selected for its simplicity and minimal boilerplate compared to Redux, while still providing powerful state management capabilities. It integrates well with React's hooks and has a smaller bundle size.
+
+### Why React Query?
+
+React Query simplifies data fetching with built-in caching, loading and error states, and automatic refetching. It helps keep components clean by separating data fetching concerns.
+
+### Why CSS-in-JS Approach?
+
+The application uses a CSS-in-JS approach for styling to:
+- Keep styles close to components
+- Enable theme variables to be accessed in JavaScript
+- Allow dynamic styling based on props
+- Prevent style conflicts through scoped CSS 

package/docs/components.md

@@ -0,0 +1,199 @@
+# SAAFE Components Documentation
+
+This document provides an overview of the UI components used throughout the SAAFE Redirection Flow application.
+
+## Core Components
+
+### Layout Components
+
+- **FrostedPanel**: A glass-like container with backdrop blur effect for modern UI elements
+- **Card**: Basic container with shadow and rounded corners for content grouping
+- **Dialog**: Modal dialog component for displaying information that requires user attention
+- **BottomSheet**: Mobile-first slide-up panel for displaying contextual content
+- **Sheet**: Slide-in panel from the side of the screen
+- **Modal**: Centered modal dialog with backdrop
+- **Sidebar**: Navigation sidebar with collapsible sections
+
+### Input Components
+
+- **Button**: Primary action component with multiple variants (primary, secondary, ghost, etc.)
+- **AnimatedButton**: Button with loading animation states
+- **Input**: Text input field with validation support
+- **Checkbox**: Selectable checkbox input component
+- **RadioGroup**: Group of radio button inputs for mutually exclusive selection
+- **Select**: Dropdown select component for choosing from a list of options
+- **OTPInput**: One-time password input with individual character fields
+- **Calendar**: Date picker component with day/month/year selection
+
+### Navigation Components
+
+- **Step**: Step component for multi-step flows with progress indicators
+- **Stepper**: Container for multi-step processes with navigation controls
+- **DotStepper**: Minimal stepper with dots for indicating progress
+- **StepperProgress**: Progress bar for multi-step flows
+- **Tabs**: Tabbed navigation interface for switching between content sections
+
+### Feedback Components
+
+- **Alert**: Alert component for displaying information, warnings, or errors
+- **Skeleton**: Loading placeholder for content that is being loaded
+- **Tooltip**: Informational tooltip that appears on hover
+- **Progress**: Progress indicator for operations
+
+### Document Components
+
+- **DocumentLink**: Component for linking to external documents with platform-specific handling
+- **ScrollArea**: Scrollable container with custom scrollbar styling
+
+### Utility Components
+
+- **Separator**: Visual divider between content sections
+- **Avatar**: User avatar component with fallback support
+- **Label**: Form label component with accessibility features
+- **Popover**: Floating content that appears relative to a trigger element
+- **Collapsible**: Expandable/collapsible content section
+- **DropdownMenu**: Menu that appears relative to a trigger element
+
+## Platform-Specific Components
+
+- **MobileFooter**: Footer component optimized for mobile devices
+- **WebFooter**: Footer component optimized for web browsers
+- **PlatformSpecificBehavior**: Component that renders different content based on the platform
+- **MobileBackground**: Background component with mobile-specific styling
+- **UrlDecodeLoader**: Loading component displayed during URL parameter decoding
+
+## Form Components
+
+- **Form**: Form container with validation and submission handling
+- **FormField**: Field wrapper with label and error handling
+- **FormItem**: Individual form item container
+- **FormLabel**: Accessible form label
+- **FormControl**: Form control wrapper with accessibility attributes
+- **FormDescription**: Descriptive text for form fields
+- **FormMessage**: Error or validation message for form fields
+
+## Authentication Components
+
+- **AuthGuard**: Component that restricts access to protected routes
+
+## Specialized Components
+
+- **ModeToggle**: Theme toggle switch between light and dark modes
+- **PageHeader**: Header component with title and optional back button
+- **StepNavigation**: Navigation component for multi-step flows
+- **SDKParamsDocs**: Documentation component for SDK parameters
+- **DummyFooter**: Simple footer component for demo purposes
+- **MobileAppDownload**: Component for promoting mobile app downloads
+
+## Usage Examples
+
+### Basic Button
+
+```tsx
+import { Button } from "@/components/ui/button";
+
+export function MyComponent() {
+  return (
+    <Button variant="primary" size="default" onClick={() => console.log("Clicked")}>
+      Click Me
+    </Button>
+  );
+}
+```
+
+### Form with Validation
+
+```tsx
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@/components/ui/form";
+import { Input } from "@/components/ui/input";
+import { useForm } from "react-hook-form";
+import { z } from "zod";
+import { zodResolver } from "@hookform/resolvers/zod";
+
+const formSchema = z.object({
+  email: z.string().email("Invalid email address"),
+});
+
+export function LoginForm() {
+  const form = useForm({
+    resolver: zodResolver(formSchema),
+    defaultValues: {
+      email: "",
+    },
+  });
+
+  const onSubmit = (data) => {
+    console.log(data);
+  };
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        <FormField
+          control={form.control}
+          name="email"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Email</FormLabel>
+              <FormControl>
+                <Input placeholder="Enter your email" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit">Submit</Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+### Multi-step Flow
+
+```tsx
+import { Stepper, Step } from "@/components/ui/stepper";
+
+export function OnboardingFlow() {
+  const [currentStep, setCurrentStep] = useState(0);
+  
+  return (
+    <Stepper currentStep={currentStep} totalSteps={3}>
+      <Step 
+        title="Personal Details" 
+        description="Enter your personal information"
+        isActive={currentStep === 0}
+      >
+        {/* Step 1 content */}
+      </Step>
+      <Step 
+        title="Account Setup" 
+        description="Set up your account"
+        isActive={currentStep === 1}
+      >
+        {/* Step 2 content */}
+      </Step>
+      <Step 
+        title="Confirmation" 
+        description="Confirm your details"
+        isActive={currentStep === 2}
+      >
+        {/* Step 3 content */}
+      </Step>
+    </Stepper>
+  );
+}
+```
+
+## Component Customization
+
+Most components support customization through props. Common customization options include:
+
+- **variant**: Changes the visual style (primary, secondary, ghost, etc.)
+- **size**: Changes the size (sm, md, lg, etc.)
+- **disabled**: Disables the component
+- **className**: Allows for additional CSS classes for custom styling
+
+## Theming
+
+Components automatically adapt to the current theme (light/dark) based on the ThemeProvider configuration. Custom themes can be applied by modifying CSS variables in the root document element. 

package/docs/index.md

@@ -0,0 +1,69 @@
+# SAAFE Redirection Flow Documentation
+
+Welcome to the SAAFE Redirection Flow documentation. This documentation provides comprehensive information about the application's features, components, and integration options.
+
+## Table of Contents
+
+- [Architecture](./architecture.md) - Technical architecture and design decisions
+- [Components](./components.md) - UI components library documentation
+- [Routes](./routes.md) - Available routes and pages
+- [SDK Integration](./sdk-integration.md) - Guide for integrating the SAAFE Redirection Flow into your applications
+- [User Journey](./user-flow.md) - Detailed explanation of the end-to-end user flow
+
+## Project Overview
+
+The SAAFE Redirection Flow is a modern React application that provides a secure account linking experience for the SAAFE (Secure Account Access Financial Environment) platform. It is designed to be embedded in mobile and web applications via an SDK.
+
+The application facilitates secure account linking between financial institutions and third-party applications through a user-friendly interface, with features including:
+
+- Multi-platform support (iOS, Android, React Native, Flutter, Web)
+- Theming options (light, dark, system)
+- Internationalization
+- Responsive design
+- Secure authentication
+- Account discovery and linking
+- Consent management
+
+## Getting Started
+
+Before diving into specific sections, we recommend understanding the basic flow of the application:
+
+1. **Integration**: Embed the application in your platform using the appropriate integration method
+2. **Configuration**: Configure the application using URL parameters
+3. **Authentication**: Users authenticate with their financial institution
+4. **Account Discovery**: Users select accounts to link
+5. **Consent**: Users review and approve data sharing
+6. **Completion**: The flow completes with success or rejection
+
+## Core Features
+
+### Multi-platform Support
+
+The application is designed to work seamlessly across different platforms:
+
+- **iOS/Android**: Optimized for mobile WebViews with adjusted UI elements
+- **React Native/Flutter**: Suitable configurations for cross-platform SDKs
+- **Web**: Default desktop experience with navigation safeguards
+
+### Theming
+
+The application supports multiple themes:
+
+- **Light**: Bright interface with dark text
+- **Dark**: Dark interface with light text
+- **System**: Adapts to the user's system preferences
+
+### Document Handling
+
+The application handles document displays differently based on the platform:
+
+- **Web**: Terms and conditions, privacy policy and other documents open in new tabs
+- **Mobile/SDK platforms**: Documents are displayed in a modern, centered modal dialog with local React components
+
+### Navigation Protection
+
+To prevent accidental exits, the application implements navigation protection that warns users before leaving the flow.
+
+## Contributing
+
+For information on contributing to the SAAFE Redirection Flow, please contact the development team.