Getting Started

Build your first Flowfull backend in 30 minutes! This guide will walk you through creating a production-ready backend with Pubflow.

🚀 Want a Full-Stack App?

Skip the setup and use our production-ready starter kits with Flowfull backend + Flowless auth + beautiful UI!

Full-Stack Starter Kits:

TanStack Start (React) - Complete web app ready to deploy
React Native Expo - Mobile app with offline support

Both include everything pre-configured! 🎉

👉 View All Starter Kits

🤖 AI Ready

This documentation is optimized for AI assistants and LLMs. Get complete context:

Documentation Overview - Quick navigation reference for browsing
Full Developer Context - Complete implementation guide with code examples

Both files are designed to be copied into your AI assistant for better code generation and support.

Prerequisites

Before you begin, make sure you have:

✅ Bun v1.0+ (Install) or Node.js 18+
✅ Database - PostgreSQL, MySQL, or LibSQL/Turso
✅ Pubflow Account - Sign up at pubflow.com
✅ Code Editor - VS Code, Cursor, or your favorite editor

Step 1: Create Flowless Instance

🔐 Authentication with Flowless

Flowfull uses Flowless for authentication - a managed auth service that handles user registration, login, sessions, and more.

Learn more about Flowless →

Visit pubflow.com
Sign up or log in
Click "Create Flowless Instance"
Copy your Bridge Secret (you'll need this later)

Your Flowless URL will be or your custom domain:

https://your-instance.pubflow.com

Step 2: Clone Flowfull Template

Official Starter Kit

We recommend using flowfull-node (Node.js/TypeScript) - the official starter kit:

bash

# Clone the official template
git clone https://github.com/pubflow/flowfull-node.git my-backend
cd my-backend

# Install dependencies
bun install

Official Starter Kit

flowfull-node is the official, production-ready starter kit maintained by the Pubflow team. It includes all core features, best practices, and is regularly updated.

Official Multi-Language Starter Kits

Flowfull is universal. Start from the language that matches your team:

GoPythonElixir

bash

git clone https://github.com/pubflow/flowfull-go-starter.git my-backend
cd my-backend
go mod download

bash

git clone https://github.com/pubflow/flowfull-python-starter.git my-backend
cd my-backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

bash

git clone https://github.com/pubflow/flowfull-elixir-starter.git my-backend
cd my-backend
mix deps.get
mix phx.server

Universal Custom Backend

Whichever starter you pick, Flowfull remains your custom backend layer. You can use middleware helpers or direct bridge.validate style integration in your routes.

Recommended reference stack: flowfull-node
Go starter: flowfull-go-starter
Python starter: flowfull-python-starter
Elixir starter: flowfull-elixir-starter
Request another starter/integration: pubflow.com/requests

Step 3: Configure Environment

Create a .env file:

env

# Flowless Configuration
FLOWLESS_URL=https://your-instance.pubflow.com
BRIDGE_SECRET=your-bridge-secret-here

# Database Configuration
DATABASE_TYPE=postgresql
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# Server Configuration
PORT=3000
NODE_ENV=development

# Cache Configuration (Optional)
CACHE_ENABLED=true
REDIS_URL=redis://localhost:6379

# Security Configuration
VALIDATION_MODE=STANDARD  # DISABLED, STANDARD, ADVANCED, STRICT

TIP

Get your BRIDGE_SECRET from your Flowless instance dashboard at pubflow.com

Step 4: Set Up Database

Run the database migrations:

Node.js/TypeScriptGoPythonRust

bash

# Run migrations
bun run migrate

# Seed database (optional)
bun run seed

bash

# Run migrations
go run cmd/migrate/main.go

# Seed database (optional)
go run cmd/seed/main.go

bash

# Run migrations
python manage.py migrate

# Seed database (optional)
python manage.py seed

bash

# Run migrations
cargo run --bin migrate

# Seed database (optional)
cargo run --bin seed

Step 5: Start Development Server

Node.js/TypeScriptGoPythonRust

bash

bun run dev

bash

go run cmd/server/main.go

bash

uvicorn main:app --reload

bash

cargo run

Your server should now be running at http://localhost:3000!

Step 6: Test Your Backend

Test Health Endpoint

bash

curl http://localhost:3000/health

Expected response:

json

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "database": "connected",
  "cache": "connected"
}

Test Protected Route

First, get a session ID from Flowless:

bash

# Login via Flowless
curl -X POST https://your-instance.pubflow.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

Response:

json

{
  "session_id": "abc123...",
  "user": { ... }
}

Now test your protected route:

bash

curl http://localhost:3000/api/profile \
  -H "X-Session-Id: abc123..."

Expected response:

json

{
  "user_id": "user_123",
  "email": "user@example.com",
  "name": "John Doe"
}

✅ Success! Your Flowfull backend is connected to Flowless!

Step 7: Build Your First Feature

Let's create a simple "items" API:

Node.js/TypeScript

typescript

// src/routes/items.ts
import { Hono } from 'hono';
import { requireAuth } from '../lib/auth/middleware';
import { db } from '../lib/database';

const app = new Hono();

// Get all items for authenticated user
app.get('/', requireAuth(), async (c) => {
  const userId = c.get('user_id');
  
  const items = await db
    .selectFrom('items')
    .where('user_id', '=', userId)
    .selectAll()
    .execute();
  
  return c.json({ items });
});

// Create new item
app.post('/', requireAuth(), async (c) => {
  const userId = c.get('user_id');
  const { name, description } = await c.req.json();
  
  const item = await db
    .insertInto('items')
    .values({
      user_id: userId,
      name,
      description,
      created_at: new Date().toISOString()
    })
    .returningAll()
    .executeTakeFirst();
  
  return c.json({ item }, 201);
});

export default app;

Next Steps

Congratulations! You've built your first Flowfull backend. 🎉

Learn More

📖 Core Concepts - Understand the architecture
⚡ HybridCache Guide - Add caching for performance
🔐 Trust Tokens Guide - Implement secure tokens
🚀 Deployment Guide - Deploy to production

Build More Features

Protected Routes - Secure your APIs
Database Setup - Advanced database configuration
Multi-Database - Switch between databases

Need Help?

📧 Email: support@pubflow.com
🌐 Website: pubflow.com
💼 GitHub: github.com/pubflow

Official Flowfull Starter Kits

Use official starters to launch faster with Flowfull concepts already wired.

Flowfull Node Starter (recommended first)

github.com/pubflow/flowfull-node

Flowfull Python Starter

github.com/pubflow/flowfull-python-starter

Flowfull Go Starter

github.com/pubflow/flowfull-go-starter

Flowfull Elixir Starter

github.com/pubflow/flowfull-elixir-starter

Need another starter language or framework?

Request it at pubflow.com/requests

How to Create a Starter Kit (Updated)

Want to publish a starter kit for another language or framework? Follow this checklist:

Implement the 7 Flowfull core concepts

Bridge Validation
Validation Modes
HybridCache
Trust Tokens (PASETO)
Auth Middleware
Multi-Database Support
Environment Configuration

Use a clear starter structure

flowfull-{language}/
├── src/
│   ├── lib/
│   │   ├── bridge/      # Bridge validation
│   │   ├── cache/       # HybridCache
│   │   ├── auth/        # Middleware
│   │   └── database/    # Database abstraction
│   └── routes/          # Example routes
├── migrations/
├── .env.example
└── README.md

Include practical examples

Basic CRUD routes
Protected endpoints
Caching examples
Database query patterns

Publish and share

Use a clear repo name (example: flowfull-{language}-starter)
Add setup docs and tests
Open a request at pubflow.com/requests so the team can review and link it from docs

Starter Naming References

flowfull-node (official reference starter)
flowfull-python-starter
flowfull-go-starter
flowfull-elixir-starter
flowfull-{language}-starter (new community language)

Need Professional Support?

If you need assistance, professional support, or want us to build your backend for you:

🌐 Notside.com - Technology firm specializing in Pubflow implementations
📧 Email: contact@notside.com
💼 Services: Custom backend development, consulting, and enterprise support

Getting Started ​

Prerequisites ​

Step 1: Create Flowless Instance ​

Step 2: Clone Flowfull Template ​

Official Starter Kit ​

Official Multi-Language Starter Kits ​

Starter Backends Quick Navigation ​

Step 3: Configure Environment ​

Step 4: Set Up Database ​

Step 5: Start Development Server ​

Step 6: Test Your Backend ​

Test Health Endpoint ​

Test Protected Route ​

Step 7: Build Your First Feature ​

Next Steps ​

Learn More ​

Build More Features ​

Need Help? ​

Official Flowfull Starter Kits ​

How to Create a Starter Kit (Updated) ​

Starter Naming References ​

Need Professional Support? ​

Getting Started

Prerequisites

Step 1: Create Flowless Instance

Step 2: Clone Flowfull Template

Official Starter Kit

Official Multi-Language Starter Kits

Starter Backends Quick Navigation

Step 3: Configure Environment

Step 4: Set Up Database

Step 5: Start Development Server

Step 6: Test Your Backend

Test Health Endpoint

Test Protected Route

Step 7: Build Your First Feature

Next Steps

Learn More

Build More Features

Need Help?

Official Flowfull Starter Kits

How to Create a Starter Kit (Updated)

Starter Naming References

Need Professional Support?