Query API

The Query API is the analytics serving layer of the SMACKZ Lakehouse. It provides a FastAPI application with embedded DuckDB that reads Parquet files from Cloudflare R2 and serves analytics endpoints.

Tech Stack

• FastAPI -- HTTP framework
• DuckDB -- Embedded SQL engine with httpfs extension for reading Parquet from R2
• Firebase Auth -- Token verification and RBAC middleware

Architecture

Clients (Admin, Metabase)
         |
         v
   FastAPI (uvicorn)
         |
         v
   DuckDB (embedded)
         |
         | httpfs extension
         v
   Cloudflare R2 (Parquet files)

DuckDB reads Parquet files directly from R2 using its httpfs extension. There is no intermediate database -- queries run against the raw Parquet files.

Route Modules

Module	Path	Description
spending.py	/spending/	Average order value, cohort analysis, spending habits
menu.py	/menu/	Item popularity, rankings, demand patterns
operations.py	/operations/	Order phase timing (p50/p95), fulfillment rate
platform.py	/platform/	Cross-restaurant metrics (admin only)
adhoc.py	/adhoc/	Ad-hoc SQL queries (admin only)

Authentication

The Query API uses Firebase token verification with role-based access control:

• Restaurant owners can query their own restaurant's data
• Platform admins can query cross-restaurant and use ad-hoc SQL
• Auth middleware in query/middleware/auth.py

Deployment

Runs as a serverless workload (smackz-lakehouse-query) on Control Plane, auto-scaling from 1 to 5 replicas based on request rate. Each replica has its own embedded DuckDB instance -- there is no shared state between replicas.

Key Files

• smackz-lakehouse/query/main.py -- FastAPI entry point
• smackz-lakehouse/query/duckdb_client.py -- DuckDB connection manager
• smackz-lakehouse/query/routes/ -- Analytics route handlers
• smackz-lakehouse/query/middleware/auth.py -- Firebase + RBAC