Technical reference. For task-based help, see the corresponding user guide.

Documentation status: complete for the current implementation

Reviewed: 2026-07-21

Primary users: visitors, family members and coaches

Surfaces: mobile web app, coach admin portal and platform API

This feature takes a person from first launch to the correct authenticated workspace. It explains the product before registration, creates either a family or coach identity, restores existing sessions, supports password recovery, and prevents a signed-in user from entering a workspace their role cannot use.

Supabase Auth issues the identity and session token. The platform API then resolves that identity to the trusted Littles Baby Tracker user, roles and capabilities. Client-side routing improves the experience, but it is not the authorization boundary.

1. The mobile introduction is swipeable and also supports explicit next-step buttons and progress dots.
2. Reduced-motion preference is respected when moving between slides.
3. The welcome screen separates registration from login.
4. Registration asks whether the person is a Family user who tracks a baby or a Coach who supports families.
5. A safe next parameter is preserved through login or registration only when it is an internal path beginning with /.

1. The form collects full name, email and password.
2. Terms and Conditions acceptance and Privacy Policy acknowledgement are mandatory.
3. Optional hints and tips, app-update/new-feature, and promotions preferences are collected independently and default off.
4. Supabase creates the auth identity. If email confirmation is required and no session is returned, the app shows a confirmation state instead of attempting product onboarding.
5. Once authenticated, POST /auth/onboard-family creates the platform family profile, applies the device timezone when available, and returns the trusted session context.
6. The default destination is /family, unless a safe invite or other internal continuation route was supplied.

1. The form collects coach name, email and password and displays an optional practice-name field.
2. Terms and Conditions, Privacy Policy, and the separate Coach Terms of Use are all mandatory.
3. POST /auth/onboard-coach creates the coach profile and independent practice context, then returns the trusted session.
4. The default destination is /coach.
5. Registration does not itself grant a paid client-sharing entitlement; subscription and capacity gates are documented in Feature 04.

Current implementation note: the mobile form displays an optional practice-name field, but the registration intent currently forwards the coach name and communication preferences, not that field. Practice/business naming is available after sign-in in Feature 23.

1. Mobile and coach portal both support email/password sign-in.
2. The mobile app first attempts ordinary Supabase sign-in. On an invalid-password response it may attempt the one-time legacy password upgrade, then retries sign-in.
3. On app start, stored auth state is restored, refreshed when necessary, and resolved through GET /auth/me.
4. /auth/me returns either authenticated with a session or onboardingNeeded with no product session. It also carries server capability state used by rollout-gated features.
5. The mobile default route follows the actor's available roles and preferred context. A coach-only actor enters /coach; a normal family actor enters /family.
6. Logout clears local product state and signs out the local Supabase session. The platform does not rely on a client-side role check to protect data.

The coach portal has no registration screen. A coach account is created through the mobile registration journey or an approved administrative workflow, then signs in here.

After authentication, the portal resolves /auth/me and presents a deliberate state:

• Authenticated coach: continue to the requested safe coach route.
• Onboarding needed: block the portal because the auth identity has no platform profile.
• Family-only actor: deny the coach dashboard.
• Pure super-admin: direct the user to the separate owner portal.
• Backend unavailable: explain that sign-in succeeded but account lookup failed, with retry and login actions.
• Invalid or expired authentication: return to login.
• Owner view-as: show the delegated-session banner and enforce the platform's read-only restrictions.

1. From mobile login, Forgot password? requires an email and calls the public platform reset endpoint. The recovery email returns through the platform's mobile recovery bridge so a new password can be set without storing credentials in the native wrapper.
2. From coach portal login, Supabase sends a reset email whose callback resumes at /change-password-recovery.
3. Replacement passwords require at least eight characters and matching confirmation.
4. A signed-in mobile user can change a password from account settings using current, new and confirmation fields.
5. Reset submission reports the same success shape regardless of account-discovery details; rate limiting is enforced server-side.

1. After two failed mobile login attempts, the user can open a login-help form.
2. The form requires a valid email and 5–2,000 characters of detail. Device/app context and the failed-attempt count may accompany the request.
3. Legacy Firebase password credentials are consumed through the dedicated upgrade route and are not a second long-term login system.
4. Migrated Apple identities can be claimed by a signed-in identity. A failed match signs the temporary session out and advises the user to use email/password or reset the password.

Apple native/OAuth callback and migrated-identity handling are implemented in the mobile app, but the social sign-in controls are currently hidden by SHOW_SOCIAL_SIGN_IN = false. Google is also hidden. The current reachable, promoted sign-in method is email and password.

Profile editing, communication-preference changes, self-family enablement and deletion are related account operations, but their full behavior belongs to Feature 02 and Feature 24.

1. Supabase Auth is used for identity and JWT issuance only. Trusted tenant data and authorization are resolved by the platform API.
2. Family, coach and super-admin roles are explicit booleans in the session contract; a user may be dual-role.
3. A client route never grants record access. Later family and coach operations still require their own subject and assignment checks.
4. Owner view-as is a synthetic, expiring session and is enforced read-only by the platform for normal data mutations.
5. Password reset, login support and legacy upgrade endpoints are rate limited. Login-support details are length-limited and telemetry avoids sensitive auth fields.
6. The native wrapper receives only minimal runtime information and does not store Supabase tokens.

1. A new family can register, satisfy required consent, complete platform onboarding and reach /family.
2. A new coach can register, satisfy coach-specific consent, complete onboarding and reach /coach.
3. A returning user reaches the correct role-aware home and a safe internal next route is preserved.
4. Email-confirmation, invalid-credential, timeout and API-lookup failures do not reveal protected screens.
5. Mobile and coach portal recovery links set an eight-character-or-longer matching password.
6. Family-only users cannot enter the coach portal; pure super-admins are directed to the owner portal.
7. Public recovery/support endpoints remain schema validated and rate limited.

• mobile-web/src/routes/WelcomeFlow.tsx
• mobile-web/src/routes/AuthScreen.tsx
• mobile-web/src/routes/AuthCallbackScreen.tsx
• mobile-web/src/routes/ChangePasswordScreen.tsx
• mobile-web/src/App.tsx
• mobile-web/src/api/supabase-auth.ts
• mobile-web/src/api/client.ts

• admin-web/src/routes/AuthScreen.tsx
• admin-web/src/routes/AuthCallbackScreen.tsx
• admin-web/src/routes/PasswordRecoveryScreen.tsx
• admin-web/src/App.tsx
• admin-web/src/api/supabase-auth.ts

• platform/apps/api/src/routes/auth-routes.ts
• platform/apps/api/src/routes/mobile-web-auth-routes.ts
• platform/apps/api/src/services/authorization-service.ts
• platform/packages/shared/src/auth.ts
• platform/packages/shared/src/access.ts
• platform/packages/shared/src/communication-preferences.ts
• platform/docs/multi-tenancy/05-development-plan.md

• 02 — Profiles, settings and account lifecycle
• 03 — Coach invitations and family linking
• 04 — Subscriptions, billing and premium access
• 24 — Coach's own family tracker