|
|
| Line 1: |
Line 1: |
| == Developers/Workflow/User Invitation Flow ==
| |
|
| |
|
| This page describes the current invitation flow used by Storlye.
| |
|
| |
|
| === Purpose === | | === Why user_invitations.invited_user_id exists === |
| Allow a superadmin to invite a new user by email, WhatsApp context, or QR sharing using the same invitation token context in the active modal.
| | * The invitation starts without a target account, so invited_user_id is NULL at creation time. |
| | | * After signup starts, backend binds the invitation to the real created account by setting invited_user_id. |
| === Entry Points ===
| | * During signup confirmation, backend uses email plus invited_user_id to attach the pending user connection safely. |
| * POST /v1/admin/invitations/preview-link | | * This avoids ambiguity when emails are reused/resubmitted and preserves invitation audit traceability. |
| * POST /v1/admin/invitations/send
| |
| * POST /auth/signup (with optional inviteToken)
| |
| * POST /auth/signup-confirmation/verify
| |
| * GET /v1/widgets/pending-people-invites
| |
| * PATCH /v1/user-connections/:connectionId/respond-me
| |
| | |
| === Flow ===
| |
| # Superadmin opens invite modal.
| |
| # Frontend requests POST /v1/admin/invitations/preview-link.
| |
| # Backend creates a pending invitation row in user_invitations with token hash and TTL, then returns invitationId, inviteToken, and inviteLink.
| |
| # Frontend renders a QR code from the invite link. The link is already valid before pressing Send.
| |
| # If Send Invite is pressed, frontend calls POST /v1/admin/invitations/send reusing invitationId plus inviteToken and optional contact fields (email/whatsapp).
| |
| # Backend updates or creates invitation data and returns final inviteLink. If email is provided, email delivery is attempted.
| |
| # Invitee signs up using inviteToken in POST /auth/signup.
| |
| # Invitation status moves to signup_pending_confirmation and gets associated with invited user id.
| |
| # Invitee confirms account with POST /auth/signup-confirmation/verify.
| |
| # Backend attaches pending connection based on invitation context.
| |
| # Invitee can accept or decline in pending people invites widget via PATCH /v1/user-connections/:connectionId/respond-me.
| |
| | |
| === Data Notes ===
| |
| * user_invitations stores token hash (never plain token), contact channels, status lifecycle, and inviter/invitee references. | |
| * user_connections is updated after signup confirmation and finalized on invite response (confirmed or declined).
| |
| | |
| === Current Behavior ===
| |
| * QR and Send in the same modal reuse the same token context.
| |
| * WhatsApp is stored as invitation context; automatic WhatsApp delivery is not integrated yet.
| |
| | |
| === Maintenance Rule ===
| |
| * Update this page in the same change cycle whenever invitation endpoints, statuses, or flow steps change.
| |
| | |
| Last update: 2026-06-15 14:32:05 UTC
| |
Why user_invitations.invited_user_id exists
- The invitation starts without a target account, so invited_user_id is NULL at creation time.
- After signup starts, backend binds the invitation to the real created account by setting invited_user_id.
- During signup confirmation, backend uses email plus invited_user_id to attach the pending user connection safely.
- This avoids ambiguity when emails are reused/resubmitted and preserves invitation audit traceability.
