Flowless Docs

Appearance

On this page

Architecture ​

Understanding the Flowless architecture will help you design better integrations and make informed decisions about your application's structure.

System Overview ​

Flowless is part of the larger Pubflow ecosystem, which consists of three main components:

Components ​

  1. 🎨 Frontend - Flowfull Clients (Your Code)

    • Technology: React, Next.js, React Native using @pubflow/react, @pubflow/nextjs, or @pubflow/react-native
    • Purpose: User interface and interactions
    • What you build: Your app's UI, forms, navigation
    • Connects to: Your Flowfull backend for all API calls

  2. ⚡ Flowfull - Your Custom Backend (Your Code)

    • Technology: Node.js using flowfull-node (official starter kit)
    • Purpose: Your business logic, data management, custom APIs
    • What you build: Products API, orders, posts, custom features
    • Connects to: Flowless for session validation via Bridge API

  3. 🔐 Flowless - Authentication Backend (Managed by Pubflow)

    • Handles all authentication
    • Manages user sessions
    • Provides trust tokens
    • Fully managed and scaled by Pubflow

  4. Pubflow Dashboard (Managed by Pubflow)

    • Configure your Flowless instance
    • Monitor usage and analytics
    • View logs and alerts
    • Manage settings

Request Flow ​

Authentication Flow ​

Two-Factor (2FA) Module Flow ​

If the Two-Factor Authentication module is enabled for the instance, the Flowless server intercepts standard logins:

API Request Flow (with Bridge Validation) ​

Database Schema ​

Flowless uses a multi-database architecture supporting PostgreSQL, MySQL, LibSQL, and SQLite.

Core Tables ​

users ​

sql
CREATE TABLE users (
  id VARCHAR(255) PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  username VARCHAR(255) UNIQUE,
  password_hash VARCHAR(255),
  name VARCHAR(255),
  last_name VARCHAR(255),
  phone VARCHAR(50),
  picture TEXT,
  is_verified BOOLEAN DEFAULT FALSE,
  is_banned BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

sessions ​

sql
CREATE TABLE sessions (
  id VARCHAR(255) PRIMARY KEY,
  user_id VARCHAR(255) NOT NULL,
  session_hash VARCHAR(255) UNIQUE NOT NULL,
  ip_address VARCHAR(45),
  user_agent TEXT,
  device_id VARCHAR(255),
  expires_at TIMESTAMP NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

social_accounts ​

sql
CREATE TABLE social_accounts (
  id VARCHAR(255) PRIMARY KEY,
  user_id VARCHAR(255) NOT NULL,
  provider VARCHAR(50) NOT NULL,
  provider_user_id VARCHAR(255) NOT NULL,
  access_token TEXT,
  refresh_token TEXT,
  expires_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
  UNIQUE(provider, provider_user_id)
);

tokens ​

sql
CREATE TABLE tokens (
  id VARCHAR(255) PRIMARY KEY,
  user_id VARCHAR(255) NOT NULL,
  token_hash VARCHAR(255) UNIQUE NOT NULL,
  name VARCHAR(255),
  expires_at TIMESTAMP,
  last_used_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

Module Hub Mutations ​

Flowless instances only initialize the Core Tables above. When optional capabilities are activated through the Module Hub, specific database migrations occur in the background.

Two-Factor Activation (modules/two-factor) ​

If the Two-Factor (2FA) module is triggered, the Hub executes base.sql and ext-session.sql scripts simultaneously:

  1. two_factor Table Initialization (base.sql)
sql
CREATE TABLE IF NOT EXISTS two_factor (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    method TEXT NOT NULL,       -- 'email', 'sms', 'otp', 'passkeys'
    code TEXT,                  -- Hashed code (Argon2id)
    status TEXT NOT NULL DEFAULT 'active',
    metadata TEXT,              -- JSON
    token_prefix TEXT,
    created_at TEXT,
    updated_at TEXT,
    last_used_at TEXT NULL,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
    UNIQUE (user_id, method)
);
  1. sessions Extension (ext-session.sql)
sql
ALTER TABLE sessions ADD COLUMN IF NOT EXISTS two_factor_verified INTEGER NOT NULL DEFAULT 0;
ALTER TABLE sessions ADD COLUMN IF NOT EXISTS two_factor_verified_at TEXT NULL;
ALTER TABLE sessions ADD COLUMN IF NOT EXISTS two_factor_methods TEXT NULL;

If disabled later, these rows remain dormant but the API routes cease checking them, ensuring backward compatibility.

Onboarding Activation (modules/onboarding) ​

Optional ALTER TABLE on users (no new tables):

  • core — acquisition_* / team_size_range
  • ext-business — is_business, biz_name, biz_country, biz_state, biz_position, biz_postal_code
  • ext-privacy — gdpr_, ccpa_, privacy_region

API surface: /auth/user/me/onboarding/complete, /auth/user/me (PUT biz — see Business), /auth/user/me/privacy* (Privacy). Admin: /auth/admin/analytics/acquisition*, list filters on GET /auth/users, PATCH /auth/admin/users/:id/privacy. Docs: Onboarding, Business, Privacy, Admin API.

Security Architecture ​

Multi-Layer Security ​

Security Layers ​

  1. Rate Limiting

    • IP-based limits
    • Endpoint-specific rules
    • Redis-backed for distributed systems
    • Automatic DDoS protection

  2. Input Validation

    • Email format validation (RFC 5322)
    • Password strength requirements
    • SQL injection prevention (parameterized queries)
    • XSS prevention (HTML escaping)

  3. Authentication

    • Argon2id password hashing
    • Secure session generation
    • OAuth 2.0 for social login
    • Token-based API access

  4. Session Validation

    • SHA-256 session hashing
    • IP address validation (optional)
    • Device fingerprinting (optional)
    • User agent validation (optional)

  5. Authorization

    • Trust token validation (PASETO)
    • Bridge secret authentication
    • Role-based access (your backend)

Caching Strategy ​

Flowless uses a multi-tier caching strategy for optimal performance:

Cache Layers ​

What Gets Cached ​

  1. Sessions (5 minutes)

    • Session validation results
    • User data associated with session
    • Reduces database load

  2. Trust Tokens (5 minutes)

    • Validated trust tokens
    • User permissions
    • Cached in your backend (Flowfull)

  3. User Profiles (10 minutes)

    • User data for frequent lookups
    • Invalidated on profile updates
    • Manual invalidation: POST /auth/invalidate/me (10 req/5min rate limit)

  4. Rate Limit Counters (Real-time)

    • Request counts per IP/user
    • Sliding window algorithm

Cache Management ​

Automatic Updates:

  • Profile updates (PUT /auth/user/me) use SURGICAL strategy - updates specific fields
  • Critical changes (email, user_type) use ATOMIC strategy - full refresh with rollback
  • Picture uploads update cache immediately

Manual Invalidation:

  • Endpoint: POST /auth/invalidate/me
  • Use case: When backend updates data directly
  • Rate limit: 10 requests per 5 minutes
  • Clears both UnifiedCache (LRU) and Ultra/Redis

Cache Repopulation:

  • Automatic on next request after invalidation
  • Bridge validate endpoint repopulates cache on miss
  • Ensures consistency across distributed systems

Scalability ​

Horizontal Scaling ​

Flowless automatically scales horizontally:

┌─────────────────────────────────────┐
│         Load Balancer               │
└─────────────────────────────────────┘
         │         │         │
    ┌────▼───┐ ┌──▼────┐ ┌──▼────┐
    │ Node 1 │ │ Node 2│ │ Node 3│
    └────┬───┘ └───┬───┘ └───┬───┘
         │         │         │
    ┌────▼─────────▼─────────▼────┐
    │      Redis Cache Cluster     │
    └──────────────────────────────┘
         │         │         │
    ┌────▼───┐ ┌──▼────┐ ┌──▼────┐
    │  DB 1  │ │  DB 2 │ │  DB 3 │
    │(Primary)│ │(Read) │ │(Read) │
    └────────┘ └───────┘ └───────┘

Performance Characteristics ​

MetricValue
Latency< 50ms (p95)
Throughput10,000+ req/sec
Availability99.9% SLA
Session Validation< 10ms (cached)
Database Queries< 20ms (p95)

Next Steps ​