Core Concepts

This guide explains the fundamental concepts and architecture of Baasix to help you build applications effectively.

What is Baasix?

Baasix is a Backend as a Source (BaaS) platform that provides a complete API for common backend functionality. Unlike hosted BaaS solutions, Baasix runs on your own infrastructure, giving you full control over your data and deployment.

Key Components

Collections

A collection is a database table that stores your application data. Each collection has:

• A unique name (e.g., posts, products, users)
• A schema defining its fields and types
• Optional relationships to other collections
• Configurable permissions

Collections are created dynamically through the Schema API or defined in code via migrations.

{
  "collectionName": "products",
  "schema": {
    "name": "Product",
    "fields": {
      "id": { "type": "UUID", "primaryKey": true },
      "name": { "type": "String" },
      "price": { "type": "Decimal" }
    }
  }
}

Items

Items are individual records within a collection. The Items API provides full CRUD operations with powerful querying capabilities:

• Create: Add new records
• Read: Query with filters, sorting, pagination, and field selection
• Update: Modify existing records (full or partial updates)
• Delete: Remove records

# Get items with filtering
GET /items/products?filter={"price":{"gt":10}}&sort={"name":"asc"}

Schemas

Schemas define the structure of your collections:

• Field types (String, Integer, Boolean, JSON, etc.)
• Constraints (required, unique, default values)
• Relationships (one-to-many, many-to-one, many-to-many)
• Indexes for query optimization

Schemas can be modified at runtime, automatically updating the underlying database tables.

Users & Authentication

Baasix includes a complete authentication system:

• Users - Stored in the baasix_User system collection
• Roles - Define permission sets (admin, user, custom roles)
• Sessions - JWT or cookie-based authentication
• SSO - Google, GitHub, Microsoft, Apple, and custom OAuth providers

Permissions

Permissions control access to collections and operations:

Example permission: "Users can read their own posts"

{
  "role_Id": "user-role-id",
  "collection": "posts",
  "action": "read",
  "condition": { "author_Id": { "eq": "$CURRENT_USER" } }
}

Hooks

Hooks are custom code that executes during item operations:

• Before hooks - Modify data before saving, validate input, prevent operations
• After hooks - Trigger side effects, send notifications, sync external services

Hooks are defined as extensions in the extensions/ directory:

// extensions/baasix-hook-audit/index.js
export default (hooksService, context) => {
  hooksService.registerHook('orders', 'items.create', async ({ data, accountability }) => {
    data.created_by = accountability?.user?.id;
    return { data };
  });
};

Workflows

Workflows provide visual automation with a node-based editor:

• Triggers: HTTP webhook, schedule (cron), manual, or item events
• Nodes: 17+ node types for conditions, loops, API calls, scripts, and more
• Execution: Real-time monitoring and logging

Workflows are ideal for complex business logic, integrations, and scheduled tasks.

Extensions

Extensions let you add custom functionality:

Extensions have full access to Baasix services for database operations, file handling, and more.

Files

The Files system handles uploads and storage:

• Multiple storage drivers (local, S3-compatible)
• Image processing and optimization
• Video metadata extraction
• Access control via permissions

Files are stored in the baasix_File system collection with references to your items.

System Collections

Baasix includes built-in collections for core functionality:

How Components Work Together

Here's how a typical request flows through Baasix:

1. Request arrives at an endpoint (e.g., POST /items/products)
2. Authentication validates the JWT/cookie and loads user context
3. Permissions check if the user's role allows the operation
4. Before hooks execute, potentially modifying the data
5. Database operation creates/reads/updates/deletes the item
6. After hooks execute for side effects
7. Response returns the result to the client

Multi-Tenancy

Baasix supports multi-tenant deployments where multiple organizations share a single instance:

• Each tenant has isolated data
• Users belong to a specific tenant
• Schemas and permissions can be tenant-specific
• Enable with MULTI_TENANT=true environment variable

Real-Time Updates

With Socket.IO integration, clients can subscribe to live updates:

• Item creation, updates, and deletions
• User notifications
• Custom events from workflows

Enable with SOCKET_ENABLED=true and use the SDK's subscription methods.

Next Steps

Now that you understand the core concepts:

• Quick Start - Build your first API
• Schema Design - Model your data
• Authentication - Secure your API
• Hooks - Add custom logic
• Permissions - Control access