Architecture
ZendBX is a multi-layer system. Each layer has a single responsibility. Here's how everything fits together.
System Layers
Client Layer
API Gateway
Services
Data Layer
Request Flow
Request arrives
Client sends HTTP request with apikey + Authorization headers.
CORS check
CORSMiddleware validates the Origin header.
Project resolution
ProjectContextMiddleware resolves the project from the URL slug or path. Validates the apikey against the project.
Authentication
resolve_principal() tries platform JWT first, then project JWT. Returns a normalized principal.
RLS context
User ID and role are set via SET app.current_user_id on the database connection.
Query execution
SQL is executed inside the project schema with RLS active.
Response
Result is serialized to JSON and returned.
Schema Isolation
Each project gets its own PostgreSQL schema. The schema name equals the project slug. All queries run with SET search_path TO "{project_slug}", public, ensuring complete data isolation without separate databases.
Authentication Architecture
ZendBX has two token namespaces:
settings.SECRET_KEY. Used by dashboard users, team members, project owners.auth.signIn(), signed with the project's jwt_secret. Used by end users of applications built on ZendBX.The resolve_principal() dependency tries both secrets and returns a normalized principal — endpoint code never needs to know which token type was used.
anon key identifies the project but does not authenticate a user. It is never accepted as a Bearer token for authenticated operations.