<img width="2816" height="1536" alt="SnackBase" src="https://github.com/user-attachments/assets/71d1b9b7-1b31-44c7-8520-eb748f788190" />

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)

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

Phase 2: Security & Authorization (100% Complete)

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

Phase 3: Operations (100% Complete)

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

Phase 4: Advanced Features (60% Complete)

• [x] F4.1-F4.2: Real-time Subscriptions (WebSocket/SSE)
• [x] F4.3: PostgreSQL Support (SQLite + PostgreSQL with dialect-aware queries)
• [x] F4.5: File Storage Engine (Local filesystem with account-scoped storage)
• [x] 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)

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

Phase 6: Data Layer Competitiveness (100% Complete)

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

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

Phase 8: Extensibility & Automation (100% Complete)

• [x] F8.1: API-Defined Hooks (unified automation: event/schedule/manual triggers, action executor, execution log, hot-reload)
• [x] F8.2: Custom Endpoints (serverless functions: DB-stored HTTP endpoints dispatched via /api/v1/x/{slug}/{path}, 30s timeout, path params, template vars)
• [x] 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