Architecture

This page explains the architecture of Flowfull Client (@pubflow/flowfull-client) and how it works under the hood.

Overview

Flowfull Client is a universal HTTP client designed to work across all JavaScript environments. It provides a simple, consistent API for making HTTP requests while handling sessions, storage, and platform-specific details automatically.

Core Components

1. HTTP Client

The HTTP client handles all HTTP requests (GET, POST, PUT, PATCH, DELETE) and provides:

• Automatic session management - Sessions are automatically stored and sent with requests
• Request/Response interceptors - Transform data before sending or after receiving
• Error handling - Comprehensive error handling with helpful messages
• Retry logic - Configurable retry logic for failed requests

const api = createFlowfull('https://api.example.com');

// All HTTP methods available
await api.get('/users');
await api.post('/users', data);
await api.put('/users/123', data);
await api.patch('/users/123', data);
await api.delete('/users/123');

2. Storage Layer

The storage layer automatically detects your platform and uses the appropriate storage mechanism:

Platform	Storage Used	Automatic Detection
Browser	localStorage	✅ Yes
React Native	AsyncStorage	✅ Yes
Next.js Server	Manual session management	⚠️ Manual
Custom	Custom storage adapter	🔧 Configurable

What's Stored:

• flowfull_session_id - User session ID
• flowfull_user_data - Cached user data (optional)

// Storage is automatic - no configuration needed!
const api = createFlowfull('https://api.example.com');

// Login - session is automatically stored
await api.post('/auth/login', { email, password });

// All future requests include the session
await api.get('/profile'); // Session sent automatically

3. Query Builder

The query builder provides an intuitive API for building complex queries:

const users = await api.query('/users')
  .filter('status', 'active')
  .filter('role', 'admin')
  .orderBy('created_at', 'desc')
  .limit(10)
  .offset(20)
  .execute();

Supported Operations:

• filter(field, value) - Filter by field value
• filter(field, operator, value) - Filter with operator (eq, ne, gt, lt, gte, lte, like, in, nin)
• orderBy(field, direction) - Sort by field (asc/desc)
• limit(number) - Limit results
• offset(number) - Skip results
• page(number) - Pagination
• execute() - Execute the query

Data Flow

Making a Request

Authentication Flow

Platform-Specific Behavior

Browser (React, Vue, etc.)

• Storage: localStorage
• Session Key: flowfull_session_id
• Automatic: Yes

import { createFlowfull } from '@pubflow/flowfull-client';

const api = createFlowfull('https://api.example.com');
// Uses localStorage automatically

React Native (Expo)

• Storage: AsyncStorage
• Session Key: flowfull_session_id
• Automatic: Yes

import { createFlowfull } from '@pubflow/flowfull-client';

const api = createFlowfull(process.env.EXPO_PUBLIC_API_URL!);
// Uses AsyncStorage automatically

Next.js Server Components

• Storage: Manual session management
• Session: Passed explicitly
• Automatic: No

import { createFlowfull } from '@pubflow/flowfull-client';
import { cookies } from 'next/headers';

export async function getServerApi() {
  const sessionId = cookies().get('session_id')?.value;
  return createFlowfull(process.env.NEXT_PUBLIC_API_URL!, { sessionId });
}

Next Steps

• How to Use - Learn how to use Flowfull Client
• Custom Storage - Create custom storage adapters
• Multi-Instance - Use multiple API instances