Flowless

Appearance

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 ​

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
);

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

  4. Rate Limit Counters (Real-time)

    • Request counts per IP/user
    • Sliding window algorithm

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 ​