Skip to content

Platform Overview

SMACKZ is a multi-tenant restaurant SaaS platform. Each restaurant gets a branded website, mobile app, admin dashboard, and analytics -- all powered by a shared backend and infrastructure.

High-Level Architecture

                    Customers                         Restaurant Owners
                   /    |    \                              |
          Website  Mobile  EnsembleUI              Smackz-Admin
              \      |      /                              |
               \     |     /                               |
                +----+----+                                |
                |         |                                |
                v         v                                v
          Page Renderer   MCP Server              Yum Backend API
                |              |                   /    |    \
                +--------------+------------------+     |     +---> POS Adapters
                                                        |              (Clover)
                                                        |
                                              +---------+---------+
                                              |         |         |
                                          PostgreSQL  Redis   Cloudflare R2
                                              |         |       (images)
                                              |    Redis Streams
                                              |         |
                                              |    Lakehouse Writer
                                              |         |
                                              |    Parquet on R2
                                              |         |
                                              |    DuckDB Query API
                                              |         |
                                              |      Metabase
                                              |   (analytics UI)
                                              |
                                          KDS-Web
                                     (kitchen display)

Tenancy Model

SMACKZ uses a shared-database, shared-schema multi-tenancy model. All restaurants share the same PostgreSQL database, with restaurant_id as the scoping key on every table. Each restaurant can optionally have its own Firebase project for authentication, enabling independent user pools.

Key Design Principles

  1. API-first -- All data mutations go through the Yum REST API. No direct SQL from clients.
  2. JSONB for flexibility -- Page sections, display properties, and restaurant config use JSONB columns, avoiding migrations for UI-level changes.
  3. Shared packages -- Common auth, API clients, types, and UI components live in @smackz-llc/shared-core and @smackz-llc/shared-ui.
  4. Separation of OLTP and OLAP -- The transactional database (PostgreSQL) is separate from the analytics platform (Lakehouse with DuckDB/Parquet).
  5. Dynamic pages -- Restaurant websites are built from configurable page/section definitions stored in the database, not hardcoded templates.

Environments

Environment Branch Purpose
QA qa Active development and testing
Staging staging Pre-production validation
Production main Live customer traffic

All development commits go to the qa branch. Promotion to staging and production happens through branch merges.

Key Files

  • CLAUDE.md (repo root) -- Team-wide conventions and project structure
  • yum/CLAUDE.md -- Backend-specific guidelines and documentation index
  • docs/ -- Cross-project FRDs and design documents