Architecture Overview

HelloJohn is structured as two distinct planes: a Control Plane that manages tenants and configuration, and a Data Plane that handles authentication for users within each tenant. This separation is what enables true multi-tenancy with full data isolation.

The two-plane model

┌─────────────────────────────────────────────────────┐
│                   Your Application                  │
│         (React, Vue, RN, Node, Go, Python)          │
└───────────────────┬─────────────────────────────────┘
                    │ SDK calls
                    ▼
┌─────────────────────────────────────────────────────┐
│              HelloJohn API Server                   │
│    ┌──────────────────┬──────────────────────────┐  │
│    │  Control Plane   │      Data Plane          │  │
│    │  (global DB)     │  (tenant DB per tenant)  │  │
│    │  - Tenants       │  - Users                 │  │
│    │  - Clients       │  - Sessions              │  │
│    │  - CP Admins     │  - MFA Factors           │  │
│    │  - Billing ☁️   │  - Organizations         │  │
│    └──────────────────┴──────────────────────────┘  │
└─────────────────────────────────────────────────────┘
                    │
         ┌──────────┴──────────┐
         ▼                     ▼
  PostgreSQL (global)   PostgreSQL (per tenant)
  Redis (sessions/RL)   SMTP / OAuth providers

Control Plane

The Control Plane is the operator layer. It manages the entities that configure HelloJohn itself:

• Tenants — a tenant is one deployment of HelloJohn (one product or one environment)
• Clients — an OAuth2 client (your web app, mobile app, backend service)
• CP Admins — operators who can create and manage tenants
• Billing ☁️ — subscription and usage management (Cloud only)

CP Admin requests require a CP Admin token (not a regular user JWT). See Control Plane →.

Data Plane

The Data Plane handles the auth for end users within a tenant:

• Authentication (email/password, OAuth, MFA)
• Session management and token issuance
• User profiles and metadata
• Organizations and memberships

Each tenant gets its own isolated database (or schema). User data from Tenant A never touches Tenant B's database. See Data Plane →.

Request lifecycle

A typical sign-in request follows this path:

1. User submits credentials in your app
2. SDK calls POST /v1/auth/sign-in (Data Plane)
3. HelloJohn validates credentials against tenant DB
4. HelloJohn issues JWT (access token) + refresh token
5. SDK stores tokens (memory + secure storage)
6. Your app sends JWT in Authorization header to your backend
7. Your backend verifies JWT locally using JWKS public key
8. No network call to HelloJohn needed for verification

Key design decisions

Local JWT verification — Your backend verifies tokens locally using the public key from the JWKS endpoint. HelloJohn doesn't need to be in the critical path for every request. See Tokens & JWT →.

Database-per-tenant — Each tenant's user data lives in its own database (or schema). This provides hard isolation that row-level security cannot guarantee. See Data Plane →.

EdDSA signatures — HelloJohn uses Ed25519 (EdDSA) for JWT signing. Faster and more compact than RSA (RS256), with equivalent cryptographic security.

Stateless access tokens — Access tokens are short-lived JWTs (15 minutes by default). Refresh tokens are long-lived opaque tokens stored server-side.

Components

Next steps

• Control Plane →
• Data Plane →
• Multi-Tenancy →
• Tokens & JWT →
• Database Schema →