BAASIX - Backend as a Source

Introduction

BAASIX is a powerful, flexible Backend as a Source (BaaS) platform that enables rapid development of web and mobile applications. It provides a comprehensive API for common backend functionality, allowing developers to focus on building frontend experiences without worrying about the underlying infrastructure.

This documentation is designed to be AI-friendly, with clear cross-links between conceptual guides and API references.

Key Features

Dynamic Database Management: Create and modify data models on the fly with a flexible schema system
Powerful Query API: Complex filtering, sorting, pagination, aggregation, and full-text search capabilities
Authentication & Authorization: Complete user management with JWT, cookie-based auth, and role-based permissions
Database Migrations: Version-controlled migrations with rollback support, auto-upgrade detection, and admin UI
Workflow Automation: Visual workflow builder with 17 node types, 4 trigger types, and real-time monitoring
Notification System: Built-in user notification system with real-time delivery via Socket.IO
File Storage & Processing: Upload, manage and transform files with image optimization and video metadata
PostGIS Geospatial Support: Advanced spatial data operations with PostGIS integration
Reporting & Analytics: Generate complex reports and statistics with grouping and aggregation
Hooks System: Extend functionality with custom hooks that trigger on specific events
Task Management System: Built-in background task coordination with caching and state management
Multi-tenant Architecture: Host multiple isolated client organizations within a single instance
Real-time Updates: Socket.IO integration with Redis clustering for live data synchronization
Caching System: Redis-based caching with configurable TTL for improved performance
Rate Limiting & Security: Comprehensive security with CORS management and rate limiting
Pino Logger: High-performance structured logging with configurable transports (Datadog, Loki, Elasticsearch)
Extensibility: Add custom endpoints, services, and business logic through extensions
AI Integration (MCP): Connect AI assistants like Claude, GitHub Copilot, and Cursor directly to your backend

Documentation

JavaScript SDK

The official TypeScript/JavaScript SDK for web, Node.js, and React Native applications:

JavaScript SDK Guide - Complete SDK documentation with TypeScript support, realtime subscriptions, and all modules

👉 npm: @baasix/sdk | GitHub

npm install @baasix/sdk

Shared Types Package

The @baasix/types package provides shared TypeScript type definitions for SDK, plugin development, and API integration:

👉 npm: @baasix/types

npm install @baasix/types

Includes types for:

Authentication (User, Role, Permission, Accountability)
Query operations (Filter, Sort, QueryParams, Aggregation)
Schema definitions (FieldDefinition, RelationshipType)
Plugin development (PluginDefinition, PluginContext, Service interfaces)
Files, Workflows, Spatial data (GeoJSON), and more

Command-Line Interface (CLI)

The official CLI for project scaffolding, type generation, and migrations:

CLI Guide - Complete CLI documentation with all commands

👉 npm: baasix

# Install globally
npm install -g baasix

# Or use with npx
npx baasix init

Key Features:

baasix init - Interactive project scaffolding with API, Next.js templates
baasix generate - Generate TypeScript types from schemas
baasix extension - Scaffold hooks, endpoints, and schedules
baasix migrate - Run database migrations

Core Concepts

Database Schema Guide - Complete schema system with relationships and field types
Database Migrations - Version-controlled schema changes with rollback support
Advanced Query Guide - Master complex filtering, aggregation, and spatial queries
Item Query Reference Guide - Operator-by-operator reference (pairs with Advanced Query Guide)
Complete Filter Reference - Comprehensive list of filter operators and syntax
Hooks and Endpoints Guide - Custom hooks and endpoints with service access patterns
Integration Guide - Complete client integration with practical examples
Error Handling Guide - Robust error handling and recovery strategies
Schema Reference Guide - Learn how to define data models
Item Query Reference Guide - Basic query capabilities
Hooks System - Extend functionality with custom code
Multi-tenant Guide - Understand the multi-tenant features
Socket.IO Integration - Implement real-time features

API Routes Documentation

Authentication Routes - User registration, login, and session management
- Session Limits Feature - Control concurrent sessions per user and device type
Notification Routes - User notification system
Settings Routes - Application configuration management
Item Routes - CRUD operations for your data
Reports Routes - Analytics and reporting with aggregation
File Routes - File upload and management
Schema Routes - Create and modify data models
Permission Routes - Control access to your data
Workflow Routes - Workflow automation with 17 node types and real-time monitoring
- Custom Workflow Modules - Extend script nodes with custom modules via extensions
Utils Routes - Utility endpoints
API Routes Reference - Complete list of all API endpoints

AI Integration

MCP Server Integration - Connect AI assistants (Claude, Copilot, Cursor) to your Baasix backend

Setup and Deployment

Deployment Guide - Production deployment with Docker, PM2, and Kubernetes
Baasix Extensions - Create custom extensions
TasksService Documentation - Background task management and coordination
Additional Features - Email templates, caching, and more

Quick Start

Prerequisites

Node.js (v18+)
PostgreSQL (v14+) with PostGIS extension
Redis (v6+)
npm or yarn

Installation

Create a new project:

mkdir my-baasix-app
cd my-baasix-app
npm init -y

Install Baasix:
```
npm install @baasix/baasix
```

Create server.js:

import { startServer } from '@baasix/baasix';

startServer().catch((error) => {
  console.error('Failed to start server:', error);
  process.exit(1);
});

Update package.json to use ES modules:
```
{
  "type": "module"
}
```

Configure environment variables (create a .env file):

# Database connection
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/baasix"

# Authentication
SECRET_KEY=your-secret-key-min-32-chars

# Server
PORT=8056

# Cache (optional - defaults to memory)
# CACHE_ADAPTER=redis
# CACHE_REDIS_URL=redis://localhost:6379

Start the server:
```
npm run dev
```

Visit http://localhost:8056/ to verify the server is running.

Variable	Description	Default
NODE_ENV	Application environment	development
PORT	Server port	8056
SECRET_KEY	JWT secret key (min 32 chars)	-
LOG_LEVEL	Log level (fatal/error/warn/info/debug/trace)	info

Database Configuration

Variable	Description	Default
DATABASE_URL	PostgreSQL connection URL	-
DATABASE_MAX_RETRY	Connection retry attempts	3
DATABASE_POOL_MAX	Max pool connections	20
DATABASE_POSTGIS	Enable PostGIS extension	false

Cache Configuration

Variable	Description	Default
CACHE_ENABLED	Enable caching	true
CACHE_ADAPTER	Cache adapter (memory/redis/upstash)	memory
CACHE_REDIS_URL	Redis connection URL	-
CACHE_TTL	Cache TTL in seconds	300

Security & CORS

Variable	Description	Default
AUTH_CORS_ALLOWED_ORIGINS	Allowed CORS origins (comma-separated)	localhost:8056
AUTH_CORS_ALLOW_ANY_PORT	Allow any port for CORS	false
RATE_LIMIT	Max requests per window	100
RATE_LIMIT_INTERVAL	Rate limit window (ms)	5000
RATE_LIMIT_BY_USER	Rate limit by user ID instead of IP (for authenticated users)	false

Features

Variable	Description	Default
MULTI_TENANT	Enable multi-tenant mode	false
SOCKET_ENABLED	Enable Socket.IO	false
PUBLIC_REGISTRATION	Allow public user registration	true

For complete configuration options, see the Deployment Guide.

Examples

Creating a Schema

POST /schemas
Content-Type: application/json
Authorization: Bearer <token>

{
  "collectionName": "products",
  "schema": {
    "name": "Product",
    "timestamps": true,
    "fields": {
      "id": {
        "type": "UUID",
        "primaryKey": true,
        "defaultValue": {
          "type": "UUIDV4"
        }
      },
      "name": {
        "type": "String",
        "allowNull": false
      },
      "price": {
        "type": "Decimal",
        "values": {
          "precision": 10,
          "scale": 2
        }
      }
    }
  }
}

Creating an Item

POST /items/products
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "Awesome Product",
  "price": 19.99
}

Querying Items

GET /items/products?filter={"price":{"gt":10}}&sort={"price":"desc"}&fields=id,name,price&limit=20
Authorization: Bearer <token>

Security

BAASIX includes comprehensive security features:

JSON Web Token (JWT) authentication
Cookie-based authentication
Role-based access control (RBAC)
Field-level permissions
Conditional permissions using dynamic variables
Input validation and sanitization

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.