Flowfull Clients

Appearance

Architecture ​

Understanding the architecture of Flowfull Clients will help you make the most of the libraries and build better applications.

Overview ​

Flowfull Clients use a layered architecture that separates concerns and makes the code maintainable, testable, and extensible.

Layers ​

1. Application Layer ​

Your application code that uses Flowfull Clients. This includes:

  • React components
  • React Native screens
  • Next.js pages
  • Business logic

2. Framework Layer ​

Framework-specific implementations:

  • @pubflow/react: React components and context
  • @pubflow/react-native: React Native components with mobile optimizations
  • @pubflow/nextjs: Next.js with SSR support

3. Hooks Layer ​

React hooks that provide a clean API for common operations:

  • useAuth() - Authentication state and methods
  • useBridgeQuery() - Data fetching with SWR
  • useBridgeMutation() - Data mutations
  • useBridgeCrud() - Complete CRUD operations
  • useBridgeApi() - Direct API access

4. Service Layer ​

Business logic services that handle complex operations:

  • AuthService: Login, logout, registration, session management
  • BridgeService: Backend-to-backend validation (for Flowfull)

5. Core Layer ​

Platform-agnostic functionality from @pubflow/core:

  • ApiClient: HTTP client with automatic authentication
  • Types: TypeScript definitions
  • Utilities: Helper functions

6. Storage Layer ​

Platform-specific storage adapters:

  • LocalStorageAdapter (React): Browser localStorage
  • SecureStorageAdapter (React Native): AsyncStorage + SecureStore
  • ServerStorageAdapter (Next.js): Cookie-based storage
  • ClientStorageAdapter (Next.js): Browser localStorage

7. HTTP Layer ​

Communication with backend services:

  • Automatic authentication headers
  • Request/response interceptors
  • Error handling
  • Retry logic

Data Flow ​

Authentication Flow ​

Data Fetching Flow ​

Mutation Flow ​

Package Dependencies ​

Storage Architecture ​

React (Web) ​

typescript
// LocalStorageAdapter
localStorage.setItem('pubflow_session_id', sessionId);
localStorage.setItem('pubflow_user_data', JSON.stringify(user));

React Native ​

typescript
// SecureStorageAdapter with fallback
try {
  await SecureStore.setItemAsync('pubflow_session_id', sessionId);
} catch {
  await AsyncStorage.setItem('pubflow_session_id', sessionId);
}

Next.js Server ​

typescript
// ServerStorageAdapter (cookies)
cookies().set('pubflow_session_id', sessionId, {
  httpOnly: true,
  secure: true,
  sameSite: 'lax',
});

Next.js Client ​

typescript
// ClientStorageAdapter (localStorage)
localStorage.setItem('pubflow_session_id', sessionId);

Session Management ​

Sessions are managed automatically across all platforms:

  1. Login: Session ID is stored in platform-specific storage
  2. API Calls: Session ID is automatically added to requests via X-Session-Id header
  3. Validation: Flowfull validates session with Flowless via Bridge API
  4. Refresh: Sessions are refreshed automatically before expiration
  5. Logout: Session is removed from storage and invalidated on server

Error Handling ​

Errors are handled at multiple levels:

Caching Strategy ​

SWR provides intelligent caching:

  • Stale-While-Revalidate: Show cached data immediately, fetch fresh data in background
  • Focus Revalidation: Refresh data when user returns to tab
  • Interval Revalidation: Automatically refresh data at intervals
  • Mutation Revalidation: Refresh related data after mutations
  • Optimistic Updates: Update UI immediately, rollback on error

Security ​

Session Storage ​

  • React: localStorage (accessible to JavaScript)
  • React Native: SecureStore (encrypted) with AsyncStorage fallback
  • Next.js Server: httpOnly cookies (not accessible to JavaScript)
  • Next.js Client: localStorage (accessible to JavaScript)

API Communication ​

  • Sessions are sent via X-Session-Id header (not in URL)
  • HTTPS required in production
  • CORS configured on backend
  • Session validation on every request

Best Practices ​

  1. Never store passwords - Only session IDs
  2. Use HTTPS - Always in production
  3. Validate sessions - On every API call
  4. Handle expiration - Implement onSessionExpired callback
  5. Clear on logout - Remove all stored data

Next Steps ​