# 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., `wiki.cafe`) 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 | Destroys session, redirects to IDP logout. |

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

## Typical flow

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

For returning users:

```
User visits wiki.cafe
    → Clicks "Sign In" (links to console.wiki.cafe/login)
    → IDP login form (or SSO if session exists)
    → IDP redirects to console.wiki.cafe/callback
    → Loads existing records, updates last login
    → Redirects to console.wiki.cafe/ (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.