SnackBase

Open-source Backend-as-a-Service (BaaS) - A self-hosted alternative to Supabase

SnackBase is a Python/FastAPI-based BaaS providing auto-generated REST APIs, multi-tenancy, row-level security, authentication, enterprise OAuth/SAML, and comprehensive admin UI.

Deployment

Setup Type	Link
SnackBase with SQLite
SnackBase with PostgreSQL

Project Statistics

Category	Count	Lines
Backend Code	~248 files	~130,000
Frontend Code	~268 files	~60,000
Tests	191 files	~30,000
Documentation	31+ files	~20,000
Total	~525 files	~195,000

---

Status

Phase 1: Foundation & MVP (100% Complete)

• F1.1: Project Scaffolding & Architecture Setup
• F1.2: Database Schema & Core System Tables
• F1.3: Account Registration
• F1.4: Account Login
• F1.5: JWT Token Management
• F1.6: Dynamic Collection Creation
• F1.7-F1.10: Dynamic Record CRUD
• F1.11: User Invitation System
• F1.12: Hook System Infrastructure (STABLE API v1.0)
• F1.13: Account ID Generator
• Full React Admin UI with Dashboard
• Rule Engine & Permission System
• Group Management
• User Management UI
• GxP-compliant audit logging
• Real-time subscriptions (WebSocket/SSE)

Phase 2: Security & Authorization (100% Complete)

• F2.1-F2.5: Permission System V2 (SQL-native RLS)
• F2.6-F2.7: SQL Macros & Group-Based Permissions
• F2.8: Authorization Middleware & Repository Integration
• F2.10: Collection-centric Rule Management
• F2.11-F2.13: Field-Level Access Control
• F2.14: GxP-compliant Audit Logging for Permissions

Phase 3: Operations (100% Complete)

• F3.1-F3.5: Dashboard & Management UIs (Dashboard, Accounts, Collections, Roles, Rules)
• F3.6-F3.8: Audit Log Storage, Capture & Query API
• F3.9-F3.12: Alembic Infrastructure & Migration Management UI

Phase 4: Advanced Features (60% Complete)

• F4.1-F4.2: Real-time Subscriptions (WebSocket/SSE)
• F4.3: PostgreSQL Support (SQLite + PostgreSQL with dialect-aware queries)
• F4.5: File Storage Engine (Local filesystem with account-scoped storage)
• F4.6: Basic Query Filters (Pagination, sorting, equality filters)
• F4.7: Advanced Query Filters (LIKE, IN, range queries, complex boolean logic)
• [~] Cloud Storage Providers (Local + Amazon S3 implemented, Azure Blob/GCS planned)

Phase 5: Enterprise Features (40% Complete)

• Rate Limiting (IP-based and user-based, configurable per endpoint)
• Security Headers (HSTS, CSP, Permissions-Policy)
• Advanced Monitoring (Prometheus metrics, distributed tracing)
• APM Integration (DataDog, New Relic)

Phase 6: Data Layer Competitiveness (100% Complete)

• F6.1: Advanced Filtering Operators (comparison >, <, >=, <=, !=, IN/NOT IN, IS NULL/IS NOT NULL, ~ LIKE; reuses rule engine grammar; type-safe comparisons)
• F6.2: Reference Expansion (populate reference fields inline via ?expand=field; deep/nested expansion; batch-loaded to avoid N+1)
• F6.3: Anonymous / Public Access (public collections accessible without authentication; per-operation public toggle; public badge in UI)
• F6.4: Bulk Operations (batch create, batch update, batch delete; JSON import/export for records; filter-aware export)
• F6.5: Aggregation Queries (COUNT, SUM, AVG, MIN, MAX with GROUP BY and HAVING; Analytics page with group-by builder)
• F6.6: Full-Text Search (skipped)
• F6.7: Cursor-Based Pagination (efficient pagination for large datasets; cursor/cursor_before params; page vs scroll mode in UI)

Phase 7: Background Processing (100% Complete)

• F7.2: Background Job Queue (async workers, retry logic, job monitoring UI)
• F7.3: Scheduled Tasks (cron-based scheduling, scheduler admin UI)
• F7.4: Computed/Virtual Fields (expression compiler, SQL injection at query time, filter/sort support)

Phase 8: Extensibility & Automation (100% Complete)

• F8.1: API-Defined Hooks (unified automation: event/schedule/manual triggers, action executor, execution log, hot-reload)
• F8.2: Custom Endpoints (serverless functions: DB-stored HTTP endpoints dispatched via /api/v1/x/{slug}/{path}, 30s timeout, path params, template vars)
• F8.3: Workflow Engine (multi-step automation: directed-graph steps, event/schedule/manual/webhook triggers, job-backed wait_delay)

---

Quick Start

New to SnackBase? Start with the 5-minute Quick Start Tutorial with screenshots and step-by-step instructions.

# Clone and install
git clone https://github.com/yourusername/snackbase.git
cd SnackBase
uv sync

# Initialize database and create superadmin
uv run python -m snackbase init-db
uv run python -m snackbase create-superadmin

# Start server
uv run python -m snackbase serve

# Access the UI
open http://localhost:8000

---

Features

Core Platform

• Clean Architecture - Domain, application, and infrastructure layer separation (~120K LOC)
• Multi-Tenancy - Row-level isolation with account-scoped data
• Single-Tenant Mode - Support for dedicated instances where all users join a pre-configured account (optional account identifier for login/registration)
• Configuration Management - Environment variables and .env file support
• Structured JSON Logging - Correlation ID tracking for request tracing
• Health Checks - /health, /ready, /live endpoints

Authentication System

• Account Registration - Multi-tenant account creation with unique XX#### ID format
• User Registration - Per-account user registration with email/password
• Login - Timing-safe password verification with account resolution
• JWT Token Management - Access tokens (1 hour) and refresh tokens (7 days) with rotation
• Password Hashing - Argon2id (OWASP recommended)
• Multi-Account Support - Users can belong to multiple accounts
• OAuth 2.0 - Google, GitHub, Microsoft, Apple
• SAML 2.0 - Okta, Azure AD, Generic SAML

Dynamic Collections & Records

• Collection Management - Create, read, update, delete collections with custom schemas
• Auto-Generated CRUD APIs - RESTful endpoints for any collection
• Field Types - Text, number, boolean, datetime, email, url, json, reference, file
• Schema Builder UI - Visual interface for designing collection schemas
• Batch Operations - Bulk create, update, delete with filtering
• Advanced Query Filters - Complex boolean expressions (AND, OR, NOT), comparison (=, !=, <, >, ~ LIKE), IN/NOT IN, IS NULL, grouping with parentheses
• Aggregation Queries - COUNT, SUM, AVG, MIN, MAX with GROUP BY and HAVING support
• Cursor-Based Pagination - Efficient pagination for large datasets alongside offset pagination
• Reference Field Expansion - Populate reference fields inline via ?expand=field (supports deep/nested expansion)
• Public Collections - Anonymous read access for public data without authentication
• Reference Fields - Foreign keys to other collections with cascade options

Authorization & Security

• Database-Centric RLS - SQL-native row-level security inspired by Supabase/PocketBase
• 5-Operation Model - Granular control for list, view, create, update, and delete
• Collection-Centric Rules - Define rules per collection instead of per role
• SQL-Native Rule Engine - Rules compile directly to efficient SQL WHERE clauses
• Field-Level Access Control - Operation-specific field visibility (show/hide fields per operation)
• PII Masking - 6 mask types (email, ssn, phone, name, full, custom) with group-based access
• SQL Macros - Reusable expression fragments (e.g., @owns_record, @has_role)

Extensibility & Automation

• Hook System (Stable API v1.0) - Event-driven extensibility
  • 40+ hook events across 8 categories
  • Built-in hooks: timestamp, account_isolation, created_by, audit_capture
  • Custom hooks with priority-based execution
• API-Defined Hooks (F8.1) - Create and manage hooks via API or Admin UI
  • Trigger types: event (data events), schedule (cron), manual (explicit API call)
  • Action executor pipeline with execution log and hot-reload
• Custom Endpoints (F8.2) - Serverless functions stored in the database
  • Define HTTP endpoints with custom path, method, and action pipeline
  • Dispatched via /api/v1/x/{slug}/{path} with 30-second timeout
  • Path parameters, template variables, and execution history tracking
• Workflow Engine (F8.3) - Multi-step automation with directed-graph steps
  • Trigger types: event, schedule, manual, webhook
  • Job-backed wait_delay for asynchronous step execution
  • Workflow instances with step-by-step logging, cancel/resume, status tracking
• Outbound Webhooks - HTTP webhook delivery with retry logic and delivery logs
• SQL Macros - Reusable SQL snippets with safe execution
  • Built-in permission macros: @has_role(), @has_group(), @owns_record(), @in_time_range(), @has_permission()
  • Timeout protection (5 seconds) and test mode with rollback
• Group Management - User groups for easier permission assignment

Admin UI

• React 19 + TypeScript - Modern admin interface with 28+ pages
• Dashboard - Platform statistics and metrics with auto-refresh
• Account Management - Create and manage accounts (superadmin)
• User Management - Full CRUD for users across accounts (superadmin)
• Role Management - Create roles and assign permissions
• Permission Management - Matrix view and bulk operations
• Collection Builder - Visual schema designer
• Records Browser - Data grid with filtering and editing
• Group Management - Organize users into groups
• Macros Management - SQL macro editor with test execution
• Migrations Viewer - Alembic revision history and status
• Audit Logs - Filterable, exportable audit trail with PII masking
• Configuration Dashboard - System/account-level provider configs (OAuth, SAML, Email, Storage)
• Email Templates - Customizable email template management
• API Keys - Create, list, and revoke service API keys
• Hooks - Create and manage user-defined hooks (event/schedule/manual)
• Custom Endpoints - Build and test serverless function endpoints
• Workflows - Design multi-step workflows and track execution instances
• Webhooks - Configure outbound webhooks and view delivery history
• Background Jobs - Monitor job queue status, retries