SnackBase

The Problem

SnackBase is a self‑hosted BaaS that promises auto‑generated REST APIs, multi‑tenancy, row‑level security and an admin UI, yet the repository ships without any CI/CD configuration. Across 505 source files no automated build or test gate exists, so every merge lands un‑validated.

What This Does

SnackBase is a portfolio of five semi‑independent projects rather than a single monorepo. The top‑level layout groups code by concern:

Key entry points lives in the examples:

• examples/feature-voting-app/index.html
• examples/feature-voting-app/src/App.tsx
• examples/realtime-demo-app/index.html
• examples/realtime-demo-app/src/App.tsx

The backend is driven by FastAPI under src/snackbase/. Important modules (import‑graph Ca / Ce) include:

• src/snackbase/infrastructure/api/routes/__init__ – Ca 0 Ce 19 (instability 1) – the main router that wires all API endpoints.
• tests/security/conftest – Ca 8 Ce 1 (instability 0.11) – security test fixtures.
• src/snackbase/core/rules/__init__ – Ca 0 Ce 6 (instability 1) – rule‑engine core.

The frontend lives in ui/src/components; the most connected UI module is ui/src/components/collections/SchemaBuilder.tsx (deep nesting, 15‑level indent).

The repo also ships a Dockerfile, docker-compose.yml, and package.json files under each example, indicating a containerised deployment model and an npm‑based front‑end build.

How It Is Wired

Control flow starts at the FastAPI main module (exposed via uv run python -m snackbase serve). The router in src/snackbase/infrastructure/api/routes/__init__ registers all auto‑generated endpoints by scanning domain models; each endpoint ultimately calls the infrastructure layer (src/snackbase/infrastructure/persistence/database.py) which executes Alembic‑managed migrations (alembic/versions/…).

The multi‑tenancy hook is injected through src/snackbase/core/rules/__init__ and the rule engine (src/snackbase/core/rules/parser.py) evaluates SQL‑native row‑level policies.

On the UI side, ui/src/App.tsx mounts the React admin UI, which talks to the FastAPI /api/* endpoints via fetch. Real‑time demo stores (examples/realtime-demo-app/src/stores/realtime.store) subscribe to WebSocket events, but the real‑time feature is still marked “not started” in the roadmap.

Outside the repo, the system touches a PostgreSQL database (Docker‑compose defines db service) and, optionally, an OAuth/SAML identity provider for enterprise login.

How To Use It

Setup (from the README and present config files):

# 1️⃣ Clone your fork
git clone https://github.com/yourusername/snackbase.git
cd SnackBase

# 2️⃣ Install backend deps (uv) and front‑end deps (npm)
uv sync               # installs Python dependencies from pyproject.toml
# each example has its own package.json; run e.g.:
cd examples/feature-voting-app && npm install

# 3️⃣ Copy environment examples and adjust
cp .env.example .env   # contains SNACKBASE_SECRET_KEY, etc.
# examples also have .env.example files

# 4️⃣ Initialise the database and create the superadmin
uv run python -m snackbase init-db
uv run python -m snackbase create-superadmin

# 5️⃣ Start the server
uv run python -m snackbase serve   # defaults to http://localhost:8000

# 6️⃣ Open the admin UI
open http://localhost:8000

Docker alternative (Dockerfile present):

docker build -t snackbase .
docker compose up -d   # defined in docker-compose.yml

Environment variables referenced in .env.example (and per‑example files) are the only required configuration; no external secrets are committed.

Real‑World Use

A product team wants a quick backend for an internal “project‑tasks” app with row‑level access per‑company. They clone SnackBase, run uv sync, set SNACKBASE_SUPERADMIN_EMAIL/PASSWORD, and init-db. Using the admin UI they create a Collection called tasks, enable multi‑tenancy, and define a rule in src/snackbase/core/rules/parser.py that restricts each account_id to its own rows. The API instantly exposes /api/tasks with CRUD; the React admin UI auto‑generates list/create/edit forms. If they need OAuth login, they configure SNACKBASE_OAUTH_PROVIDERS in .env and the saml_router.py/oauth docs guide the IdP setup. Within minutes they have a production‑grade API + UI, ready for internal consumption.

Code Health & Issues

Measured findings (static analysis, 144 total):

• [HIGH/clarity] Duplicated code blocks – 2 562 repeated 6‑line blocks across 257 files, e.g. alembic/versions/038a7194dd07_enhance_password_reset_template.py and src/snackbase/infrastructure/persistence/database.py. Extract shared helpers.
• [HIGH/cognitive_load] Deep nesting – max indent 15 in ui/src/components/collections/SchemaBuilder.tsx, ui/src/components/records/DynamicFieldInput.tsx, examples/realtime-demo-app/src/components/realtime/ActionsPanel.tsx. Flatten with guard clauses.
• [MEDIUM/resilience] Broad exception handling x3 – tests/security/conftest.py, src/snackbase/infrastructure/api/routes/realtime_router.py, src/snackbase/infrastructure/api/routes/saml_router.py. Catch specific exceptions; log or re‑raise.
• [MEDIUM/cognitive_load] High branching density – src/snackbase/core/rules/lexer.py has 52 branch points over 180 lines. Decompose with a strategy dispatch.

Code‑health audit (6 findings, 0 critical):

• [HIGH] Add a CI/CD workflow that builds and tests on push & PR.
• [HIGH] Add a build gate for the Docker image – validate manifests automatically.
• [MEDIUM] Enable Dependabot/Renovate for Python and JavaScript manifests.
• [MEDIUM] Pin the container base image by digest (python:3.12-slim@sha256:…) and enable Docker‑ecosystem Dependabot.
• [MEDIUM] Add a non‑root USER to the Docker image; chown required paths and end Dockerfile with USER.
• [LOW] Add project convention files: .editorconfig, .gitattributes (text=auto eol=lf), formatter config (e.g., black, prettier).

The Bottom Line

SnackBase delivers a functional BaaS skeleton with auto‑generated APIs, multi‑tenancy and a ready‑to‑admin UI, making it attractive for teams that need a self‑hosted PocketBase alternative without building from scratch. The main drawback is the absence of automated testing and CI, plus several code‑quality hotspots (duplication, deep nesting, broad exception catches) that will require refactoring before it can be safely iterated in a production team. It is well‑suited for early‑stage products, internal tools, or prototypes where rapid deployment outweighs the need for a polished engineering pipeline.