# User Onboarding Model (MVP -> Post-MVP)

## Purpose

Define the product and control-plane onboarding model so the platform feels complete
without waiting on MaaS or enterprise federation rollout.

This document separates:

1. **MVP onboarding path we can implement now**
2. **Post-MVP expansion paths** (tenant federation automation, multi-tenant switching)

## Current Constraints

1. Personal account signup/login exists and auto-bootstraps tenant/project context.
2. Seeded bootstrap users still exist for local/dev bring-up.
3. Tenant/project ownership and membership are now the authorization root.
4. MaaS onboarding is explicitly deferred (`A-MAAS-001`).

## MVP Onboarding Model (Implement Now)

### Identity and Role Boundaries

1. `users.role=admin` is platform-admin only (platform scope).
2. Tenant/project access is controlled by memberships:
   - `tenant_memberships`
   - `project_memberships`
3. Resource ownership is tenant/project-rooted; user id is attribution.
4. Extended role taxonomy and lifecycle (platform ops, tenant/project role sets, custom roles) are defined in:
   - `doc/architecture/Role_and_Policy_Lifecycle_Model.md`

### User Creation and Access Flow

1. **Work account path (MVP behavior)**:
   - uses platform OIDC login path backed by the shared realm setup.
   - tenant federation discovery/config is not required for MVP runtime.
   - tenant hints are advisory and server-validated.
   - UI behavior: `Continue with SSO` path with optional work-email/tenant-hint input; no personal username/password fields in this branch.
2. **Personal account path**:
   - user signs up/signs in with personal credentials.
   - personal sign-in must use public auth/session flows, not internal bootstrap endpoint `POST /api/v1/auth/login`.
   - signup atomically creates personal tenant + default project + owner memberships.
   - bootstrap role binding on success:
     - tenant role: `tenant_owner`
     - project role: `project_owner`
   - UI behavior: personal username/password sign-in and sign-up controls; no SSO redirect in this branch.
3. Platform admin can create tenant admin user using current admin path:
   - `POST /api/v1/admin/users` for identity creation, then
   - membership binding via `scripts/ops/bind_tenant_admin_membership.sh` (single controlled scripted operation, no ad-hoc SQL) until tenant-admin membership APIs land.
   - script requirements: correlation_id input, explicit actor/target fields, and audit log write in the same operation path.
4. Tenant admin manages tenant users and project memberships within tenant scope.
5. API resolves user -> active tenant membership -> request-scoped project context.
6. If project context is missing for project-owned operations:
   - return deterministic `400 invalid_request` with canonical envelope.

### Failure and Deactivation Paths

1. Personal signup bootstrap is transactionally atomic:
   - any failure returns canonical error and no partial tenant/project/membership state is committed.
2. If membership is revoked or account is deactivated mid-session:
   - subsequent protected calls return canonical authz/auth errors,
   - client clears local session and routes user back to sign-in.

### UX Expectations (MVP)

1. Login screen presents two account paths: `Work account` and `Personal account`.
2. Authenticated user sees current tenant/project context in shell/header.
3. First-run zero-balance user is routed to billing onboarding CTA (already defined in product UX docs).
4. User-management surfaces clearly show actor scope (`platform` vs `tenant/project`) and deterministic membership/context errors.
5. MVP-activated tenant roles in onboarding flows are:
   - `tenant_owner`, `tenant_admin`, `tenant_member`.
6. Defined-but-not-activated-by-default roles in onboarding UX are:
   - `tenant_billing_manager`, `tenant_billing_viewer`, `tenant_viewer`.

## Post-MVP Expansion (Not Blocking MVP)

1. **Enterprise SSO federation admin UX** (ADR-010 baseline):
   - per-tenant OIDC/SAML provider config,
   - invite/pre-authorization gate before membership activation.
2. **Multi-tenant user context switching UX**:
   - remove MVP single-tenant uniqueness guard when enabled.
   - guard location today: partial unique active-membership constraint `ux_platform_access_tenant_memberships_user_active` on `platform_access_tenant_memberships(user_id)` in `doc/architecture/db_schema_v1.sql`; removal means dropping/relaxing that constraint and updating membership selection UX.
3. **Self-service tenant-admin membership APIs/UI**:
   - replace internal runbook/SQL fallback.
   - tracking anchor: this follow-up must be represented in `doc/governance/Agent_Work_Queue.yaml` before implementation kickoff; architectural dependency is `doc/architecture/adrs/ADR-008-tenant-project-ownership-baseline.md`.

## Onboarding-Specific Contract Requirements

1. Personal signup endpoint must be idempotent by key and safe to retry.
2. Personal signup bootstrap must be atomic across user+tenant+project+membership creation.
3. Work/personal onboarding failures must always return canonical error envelopes.
4. Audit for onboarding mutations must include full authz context fields from role lifecycle baseline:
   - `correlation_id`, `actor_type`, `actor_id`, `platform_role`, `tenant_id`, `project_id`, `resource_name` (when applicable), `reason_code`.

## Out of Scope for This Sprint

1. MaaS node onboarding integration.
2. Full enterprise IdP admin UX.
3. Service-account onboarding UX.

## References

1. `doc/architecture/adrs/ADR-008-tenant-project-ownership-baseline.md`
2. `doc/architecture/Tenant_Federation_SSO_Model.md`
3. `doc/product/UX_Implementation_Spec.md`
4. `doc/product/UX_Journeys.md`
5. `doc/architecture/Role_and_Policy_Lifecycle_Model.md`