member-console/docs/deployment-architecture.md

title, audience, summary

title	audience	summary
Deployment Architecture	admin developer	How member-console fits into a larger hosted service alongside a public site and identity provider, and the integration endpoints it exposes.

Deployment Architecture

How member-console fits into a larger service that includes a homepage, an IDP, and the console itself.

Member-console's role

Member-console is infrastructure, not the public-facing front door. It provides:

• Authentication mechanics — OIDC login/registration via a configurable IDP, session management (Valkey-backed), PKCE.
• Auto-provisioning — new users get a person, personal org, workspace, and default entitlements in a single transaction.
• Entitlement enforcement — what capabilities a user has (sites, storage) based on their grants.
• Operator tools — managing entitlement sets, org types, products, and billing.

Member-console is IDP-agnostic. It delegates authentication to whatever OIDC-compliant provider is configured.

External site's role

The public-facing site (e.g., example.com) owns:

• Tier messaging — explaining what Public and Standard tiers offer.
• Signup narrative — the marketing story that motivates registration.
• Navigation — linking to /register or /login on the console subdomain.
• Front door UX — landing pages, comparisons, CTAs.

Tiers are not hardcoded concepts in member-console. "Public" and "Standard" are human names for specific entitlement set configurations. The external site chooses how to present them.

Current integration points

Endpoint	Purpose	Notes
/register	Redirects to IDP registration page	OIDC registration endpoint with PKCE. After IDP registration, callback auto-provisions the user.
/login	Redirects to IDP login page	Standard OIDC authorization code flow with PKCE.
/callback	Handles IDP redirect	Exchanges code, verifies token, provisions new users or loads existing ones.
/logout	Initiates logout (POST only; a GET redirects to /)	Destroys the session, revokes the refresh token at the IDP, then sends the browser to the IDP's end-session endpoint with a valid id_token_hint where one can be had.
/logout-callback	Returns from IDP logout	Redirects to /login. Nothing is verified: the session ended at /logout.

An external site integrates by linking to these endpoints on the console's domain (e.g., console.example.com/register).

Typical flow

User visits example.com
    → Clicks "Get Started" (links to console.example.com/register)
    → IDP registration form
    → IDP redirects to console.example.com/callback
    → AutoProvision: user + person + org + workspace + default grants
    → Redirects to console.example.com/ (dashboard)

For returning users:

User visits example.com
    → Clicks "Sign In" (links to console.example.com/login)
    → IDP login form (or SSO if session exists)
    → IDP redirects to console.example.com/callback
    → Loads existing records, updates last login
    → Redirects to console.example.com/ (dashboard)

What member-console does NOT provide (yet)

See the backlog in status/milestones.md for these capabilities:

• Auth status endpoint — lets external sites check if the user has an active console session, so a link can dynamically say "Sign in" or "Console."
• Hosted landing page — for co-ops that don't want a separate website; a configurable welcome page served by member-console itself.
• Post-registration redirect — returning users to the originating site after signup instead of landing on the dashboard.