Getting Started

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

🤖 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

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.

Community Starter Kits

The community is building starter kits for other languages:

Go (Coming Soon)Python (Coming Soon)Rust (Coming Soon)

bash

# Community starter kit - coming soon!
# Want to contribute? See "Community Contributions" below
git clone https://github.com/pubflow/flowfull-go.git my-backend
cd my-backend
go mod download

bash

# Community starter kit - coming soon!
# Want to contribute? See "Community Contributions" below
git clone https://github.com/pubflow/flowfull-python.git my-backend
cd my-backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

bash

# Community starter kit - coming soon!
# Want to contribute? See "Community Contributions" below
git clone https://github.com/pubflow/flowfull-rust.git my-backend
cd my-backend
cargo build

Community Contributions

Want to create a starter kit for your favorite language? Check out our Contribution Guide below!

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

Community Contributions

Want to create a Flowfull starter kit for your favorite language? We welcome community contributions!

How to Create a Starter Kit

Implement the 7 Core Concepts:
- Bridge Validation
- Validation Modes
- HybridCache
- Trust Tokens (PASETO)
- Auth Middleware
- Multi-Database Support
- Environment Configuration

Follow the Structure:

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

Include Examples:
- Basic CRUD operations
- Protected routes
- Caching examples
- Database queries
Submit Your Starter Kit:
- Create a repository: flowfull-{language}
- Add comprehensive README
- Include tests
- Submit to github.com/pubflow

Starter Kit Naming Convention

flowfull-node - Node.js/TypeScript (official)
flowfull-go - Go
flowfull-python - Python
flowfull-rust - Rust
flowfull-{your-language} - Your language!

Community Starter Kits

Language	Status	Repository	Maintainer
Node.js	✅ Official	flowfull-node	Pubflow Team
Go	🚧 Coming Soon	flowfull-go	Community
Python	🚧 Coming Soon	flowfull-python	Community
Rust	🚧 Coming Soon	flowfull-rust	Community

Want to be listed here? Create a starter kit and let us know!

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 ​

Community Starter Kits ​

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? ​

Community Contributions ​

How to Create a Starter Kit ​

Starter Kit Naming Convention ​

Community Starter Kits ​

Need Professional Support? ​

Getting Started

Prerequisites

Step 1: Create Flowless Instance

Step 2: Clone Flowfull Template

Official Starter Kit

Community Starter Kits

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?

Community Contributions

How to Create a Starter Kit

Starter Kit Naming Convention

Community Starter Kits

Need Professional Support?