cgalo5758
cbd08b45aa
Rewrite the README around purpose, architecture, quickstart, and status. Add contributing/security policies plus a docs index with audience front matter across existing docs.
73 lines
3.3 KiB
Markdown
73 lines
3.3 KiB
Markdown
---
|
|
title: "Deployment Architecture"
|
|
audience: [admin, developer]
|
|
summary: "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 | Destroys session, redirects to IDP 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.
|