URD: User Management

Module	Version	Updated
CORE-01	v1.0	2026-07-15

What the User Management module does

Defines the user-facing requirements for User Management - the platform's foundation. Every other module trusts the identity and scope this module issues: how a person creates an account, authenticates, and manages a profile; how one user can belong to several organizers (Organizer) at once; and how an owner manages staff within their own organizer.

The three surfaces, Client, Sale, and Back Office, serve three very different audiences, sharing one sign-in mechanism but blocked cross-page by role tier - an internal administrative account cannot slip into the customer-facing page, and the reverse.

Five things to understand first

This is the most important part of the document. Understanding the five points below covers 80% of the module.

1. A user is an identity, separate from role and scope

A user is an authenticated identity - internal (operator) or external (owner, employee, customer). Role and scope are not baked into the user; they are assigned separately and carried in the session token on every sign-in.

The Session Token (JWT) is issued on sign-in and carries the user ID, roles, organizer (Organizer) ID, and merchant (Merchant) ID for stateless authorization - changing a user's role or scope only takes effect on their next sign-in, not immediately.

2. Three kinds of identifiers, each globally unique

An identifier (Identifier) is a login value tied to a user - username, email, or phone. Each is globally unique within its type: there are never two accounts sharing the same username, or the same verified email or phone number.

Identifier	Required	Initial state
Username	Required	Automatically considered verified
Email	Optional	Unverified, needs OTP
Phone	Required for Owner tier and below, after onboarding	Unverified, needs an SMS OTP (VNPAY)

Username is the primary identifier - signing up and signing in with a username always works, independent of email or phone.

3. Eight fixed roles, split into tiers that decide which page a user can enter

There are eight fixed roles (Role), pre-seeded and unable to be edited or deleted - from Guest (lowest) up to the highest internal roles. Role priority is enforced: no one can manage a role at their own level or above.

Roles split into two tiers, and the tier decides which page a user can sign into:

• Above Owner (Super Admin, Admin, Operator) - can only reach the Back Office. To act as a customer, a separate account must be created.
• Owner tier and below (Owner, Cashier, Employee, Customer) - can only reach Client or Sale, never the Back Office.

This blocking happens on the server, not just in the interface - calling the API directly is blocked too.

4. A user can belong to several organizers at once

A user is not confined to a single organizer (Organizer) - they can belong to multiple organizers at once, each holding its own role and merchant (Merchant) scope. After signing in, the user picks the organizer to work in at the launchpad, and can switch to another at any time using the switcher in the app.

A user added to another organizer this way still onboards like a normal user - phone verification still applies - and still keeps the right to create their own organizer.

5. Employees come in two kinds: with sign-in access and without

An owner creates employee accounts and assigns them to one or more merchants, but not every employee needs to sign in right away. An employee without sign-in access is still tracked in the system; granting them access later (a username plus a set-password mail) does not require recreating them from scratch.

The two kinds have different off-boarding lifecycles: an employee with sign-in access can be deactivated; an employee without sign-in access can only be removed - there is no status field to deactivate.

What the module covers

Five feature areas. Click an AREA code to jump to the Details tab and read that area's requirements.

AREA	Name	Status
AUTH	Authentication	Partial
USR	User Account	Partial
MORG	Multi-organizer Membership	Partial
EMP	Employee Management	Partial
OPS	Operations Staff Administration (BO)	Partial

1. Definitions

Term	Definition
User	An authenticated identity - internal (operator) or external (owner, employee, customer).
Credential	A secret used to authenticate - a hashed password today; a 2FA scheme is defined but not enforced.
Identifier	A login value tied to a user - username, email, or phone. Each is globally unique within its type.
User Profile	Personal info attached to a user - name, birthday, locale, contact details. One per user.
User Configuration	A per-user key-value setting, grouped by code. A default set is created on registration.
Role	A classification that determines access level and data scope. Eight fixed roles exist.
Owner	The user who creates a business during onboarding; has full access to their organizer.
Cashier	A merchant-level staff role for cashiers, scoped to specific merchants (same tier as Employee).
Employee	A staff member scoped to specific merchants within an organizer.
Customer	A role for an end-customer linked to an organizer; the customer account lifecycle is owned by the Customer module.
Guest	An unauthenticated-style global role with no backend permissions; lowest priority.
OTP	A one-time code delivered via email or SMS for identifier verification, password reset, or sign-in activation.
Recovery Channel	The channel used whenever the system needs to restore a user's access - email if the account has a verified email, otherwise an SMS OTP to a verified phone. The two channels are never sent in parallel.
Launchpad	The screen shown right after sign-in where a user picks the organizer (and merchant) to work in; for users belonging to multiple organizers, it is also where they pick their first organizer after signing in.
Session Token (JWT)	Issued on sign-in; carries user ID, roles, organizer ID, and merchant ID for stateless authorization.

2. Conceptual Model

Conceptual only - full schema lives in the developer domain model. The User-Organizer relationship is many-to-many: one user can belong to several organizers.

3. Features

AUTH - Authentication Partial

Spec: PRD-AUTH-001 · 20 requirements · 6 acceptance scenarios

Username is the system's primary identifier - people sign up and sign in with a username plus a password. After finishing onboarding, users at the Owner role or below must verify a phone number with an OTP sent by SMS (VNPAY is the provider); email is an optional identifier. Users change their password, or recover access through exactly one recovery channel: email if the account already has a verified email, otherwise an SMS OTP to a verified phone - the two channels are never sent in parallel.

ID	Priority	Requirement	Status
URD-AUTH-001	Must	User can sign up with a username and password	Built
URD-AUTH-002	Must	Sign-up creates account, profile, identifiers, and default settings in one operation	Built
URD-AUTH-003	Must	If any part of sign-up fails, nothing is created (all-or-nothing)	Built
URD-AUTH-004	Must	User can sign in with any verified identifier (username / email / phone) + password	Built
URD-AUTH-005	Must	Successful sign-in returns a session token carrying roles and organizer / merchant scope	Partial
URD-AUTH-006	Must	Passwords are stored only as a one-way hash using a password-specific hashing algorithm - the plain-text value is never stored or logged	Built
URD-AUTH-007	Must	User can change their password (current password verified first)	Built
URD-AUTH-008	Must	User can verify their email via OTP (request → receive code → submit)	Built
URD-AUTH-009	Must	User verifies a phone number with an OTP sent by SMS when linking that number to the account during onboarding	Built
URD-AUTH-010	Must	User can reset a forgotten password (request → verify code → set new password)	Built
URD-AUTH-011	Should	User can add (link) a verified email or phone to an authenticated account	Not built
URD-AUTH-012	Should	System records the last sign-in timestamp	Built
URD-AUTH-013	Could	Two-factor authentication is enforced	Not built
URD-AUTH-015	Must	Username is the system's primary identifier; signing up and signing in with a username is always available, independent of email or phone	Built
URD-AUTH-016	Must	After finishing onboarding, users at the Owner role or below must verify at least one phone number; email remains an optional identifier	Built
URD-AUTH-017	Must	A password-reset request over the email channel sends a single email containing both a 6-digit code and a reset link; entering the code or clicking the link both lead to the same set-new-password step	Built
URD-AUTH-018	Must	Every password-recovery or sign-in-activation flow picks exactly one recovery channel: email if the account has at least one verified email, otherwise an SMS OTP to a verified phone - the two channels are never sent in parallel	Partial
URD-AUTH-019	Could	User can sign in with an OTP sent to a verified phone, without a password	Not built
URD-AUTH-020	Must	Users with a system role above Owner (Super Admin, Admin, Operator) cannot sign in to the Client or Sale surfaces; to act as a customer they must create a separate account	Not built
URD-AUTH-021	Must	Users at the Owner role or below (Owner, Cashier, Employee, Customer) cannot sign in to the Back Office	Not built

AC-AUTH-01: Sign-in

Given	When	Then
Valid credentials, verified identifier	User signs in	Session token issued with roles and scope
Invalid password	User signs in	Authentication rejected
Unverified identifier	User signs in	Sign-in rejected - identifier not verified
Deactivated / blocked user	User signs in	Access denied
Successful sign-in	-	Last sign-in timestamp updated

AC-AUTH-02: Sign-up

Given	When	Then
New username + password + profile	User signs up	Account created with Owner role
Username already exists	User signs up	Conflict error
Successful registration	-	Default settings auto-created
Any step fails	-	Entire registration rolls back

AC-AUTH-03: OTP verification

Given	When	Then
Unverified email or phone	User requests OTP	Code delivered, session token returned
Valid session + correct code	User submits	Identifier marked verified
Expired code	User submits	Error - code expired
Too many attempts	User retries	Error - max attempts exceeded

AC-AUTH-04: Forgot password and sign-in activation

Given	When	Then
Account has a verified email	Requests password reset or sign-in activation	A single email is sent, containing both a 6-digit code and a reset link
Account has no verified email	Requests password reset or sign-in activation	An OTP is sent by SMS to the verified phone
User enters the code or clicks the link from the email	Verifies	Reset session confirmed
Verified session	User sets new password	Password updated (hashed)

AC-AUTH-05: Sign-in by role tier and surface

Given	When	Then
User with role Super Admin, Admin, or Operator	Signs in to the Client or Sale surface	Blocked
User with role Owner or below	Signs in to the Back Office	Blocked
An internal user wants to act as a customer	-	Must create a separate account for that

AC-AUTH-06: Sign-in by phone OTP

Given	When	Then
Verified phone number	Requests a sign-in OTP	Code is sent by SMS
Correct, unexpired code	User submits code	Session token issued, no password needed

USR - User Account Partial

Spec: PRD-USR-001 · PRD-USR-002 · 23 requirements · 4 acceptance scenarios

Each user has a unique account that can hold several identifiers (username, emails, phones), an editable profile, a language preference, and a status lifecycle - account data is always preserved via soft-delete. Identifiers are themselves a managed resource: a user can list and add their own, each typed by a scheme, starting unverified. Removing the last identifier in a scope is blocked - the last verified email, or the last verified phone of a user at the Owner role or below - so the account always keeps a way to re-authenticate. Each user also has a personal configuration store - their own settings and custom table views - readable right after sign-in, before an organizer or merchant is selected.

ID	Priority	Requirement	Status
URD-USR-001	Must	Each user has a unique system-generated ID	Built
URD-USR-002	Must	A user can have multiple identifiers (username, emails, phones)	Built
URD-USR-003	Must	Each identifier is globally unique within its type	Built
URD-USR-004	Must	Username is required and automatically considered verified	Built
URD-USR-005	Must	Email and phone identifiers start unverified and require OTP to verify	Built
URD-USR-006	Must	User can view and update their own profile (name, birthday, locale, contacts)	Built
URD-USR-007	Must	Authorized users can change a user's status (activate, deactivate, block, archive)	Partial
URD-USR-008	Must	Deactivated and blocked users cannot sign in	Built
URD-USR-009	Must	User data is always preserved - accounts are never permanently deleted (soft-delete)	Built
URD-USR-010	Should	User can set a language / locale preference	Built
URD-USR-011	Could	ARCHIVED is a terminal status and cannot be reactivated	Partial
URD-USR-012	Must	Each identifier declares a scheme that types it - username, email, phone number - drawn from a fixed, validated set (alongside system-issued schemes)	Built
URD-USR-013	Must	Identifiers are a managed resource: list, search, count, and single-record read, scoped to the caller's access	Built
URD-USR-014	Must	Adding an identifier always binds it to the requesting user and creates it unverified; a supplied user reference or verified flag cannot override this	Built
URD-USR-015	Should	Identifiers can be updated and removed (single or by filter) via soft-delete; identifier data is preserved	Built
URD-USR-016	Must	Every identifier operation (read / create / update / delete) is individually permission-gated and merchant-scoped	Built
URD-USR-017	Must	Removing a verified email is refused if the account still has a verified email and this is the last one	Not built
URD-USR-018	Must	A user at the Owner role or below must always keep at least one verified phone; removing the last verified phone is refused, regardless of whether the account still has an email	Not built
URD-USR-019	Must	Each user has a personal configuration store keyed by code, grouped under system or table (for example a seen-the-tour flag, a display preference)	Built
URD-USR-020	Should	A user can create a custom view for a table - adjust its columns and filters and save them as their own view for that table; the view auto-saves on every change, and its name cannot repeat within the same table	Built
URD-USR-021	Must	A user's configuration is readable right after sign-in, before an organizer or merchant is selected; create, update, and delete are permission-gated	Built
URD-USR-022	Must	A default set of configurations is pre-created by the system as soon as a user registers	Built
URD-USR-023	Must	For accounts created by the operations team in Back Office: a phone number can be entered at creation without requiring verification; Back Office shows each identifier's verification state and an authorized operations staff can change that state manually, with no SMS or email involved	Not built

AC-USR-01: Account identity & lifecycle

Given	When	Then
A new account	Created	A unique system-generated ID is assigned; data is soft-deletable, never permanently deleted
A deactivated or blocked user	Attempts sign-in	Access is denied

AC-USR-02: Identifier management

Given	When	Then
A signed-in user	Lists their identifiers	Only identifiers within the caller's scope are returned, each labelled by its scheme
A user adds an identifier	Create is submitted	The identifier is owned by the requesting user and stored unverified
A create request naming another user or pre-set as verified	Submitted	The owner is still the caller and the identifier is still unverified - the request values are ignored
An identifier is removed	Delete is submitted	The row is soft-deleted and preserved, never physically removed

AC-USR-03: Identifier-removal guard by scope

Given	When	Then
Account has exactly one verified email	Removes that email	Refused - this is the last verified email
Account has several verified emails	Removes one of them	Allowed - another verified email remains
A user at the Owner role or below has exactly one verified phone left	Removes that phone	Refused - at least one verified phone must always remain

AC-USR-04: Personal configuration & custom table views

Given	When	Then
A new user	Registers	A default set of configurations is created automatically
A signed-in user, before an organizer or merchant is selected	Reads their configurations	The configurations are returned
A user, a table, adjusted columns/filters	Saves as a custom view	A per-user view is created and auto-saved for that table
A view name that duplicates an existing one in the same table	Saved	Refused - the name already exists

MORG - Multi-organizer Membership Partial

Spec: PRD-EMP-001 · 4 requirements · 1 acceptance scenario

A user is not confined to a single organizer - they can belong to multiple organizers at once, each holding its own role and merchant scope. After signing in, the user picks the organizer to work in at the launchpad, and can switch to another at any time using the organizer switcher in the app. The definitions of the eight fixed roles, the priority system, and data scoping live in ROLE - Permissions URD.

ID	Priority	Requirement	Status
URD-MORG-001	Must	A user can belong to multiple organizers at once, each holding its own merchants and role assignment for that user	Built
URD-MORG-002	Must	A user is added to another organizer through that organizer's Employee screen - assigned to a merchant and a role just like a regular employee (see EMP)	Not built
URD-MORG-003	Must	After signing in, a user who belongs to multiple organizers picks the one to work in at the launchpad; while using the app they can switch to another organizer with the organizer switcher	Built
URD-MORG-004	Must	A user added to another organizer this way still onboards like a normal user - phone verification still applies - and can still create their own organizer, with a headquarters merchant (see ORG / MER in the Commerce URD)	Built

AC-MORG-01: User belonging to multiple organizers

Given	When	Then
An existing user	Is added to another organizer via its Employee screen	The user is assigned to a merchant + role in that organizer
A user belonging to multiple organizers	Signs in	The launchpad shows up to choose the organizer to work in
A user working within one organizer	Uses the organizer switcher	Switches to another organizer's context within the same session
A user added this way, phone not yet verified	Onboards	Must still complete phone verification like regular onboarding

EMP - Employee Management Partial

Spec: PRD-EMP-001 · PRD-EMP-002 · 8 requirements · 2 acceptance scenarios

Owners create employee accounts on the Client app, assign them to one or more merchants in their organizer, and update or deactivate those assignments; each employee signs in with their own credentials and sees only the merchants they are assigned to. Operations staff have an equivalent screen on the Back Office to do the same work across every merchant when they need to help - that side is still being built, see PRD-EMP-002.

ID	Priority	Requirement	Status
URD-EMP-001	Must	Owner can create employee accounts	Built
URD-EMP-002	Must	Employee is linked to an organizer and one or more merchants	Partial
URD-EMP-003	Must	Employee can access only merchants they are assigned to	Built
URD-EMP-004	Must	Employee can sign in with their own credentials	Built
URD-EMP-005	Must	Data queries for an employee are filtered by their merchant assignments	Built
URD-EMP-006	Must	Owner can update employee merchant assignments (replaces all previous assignments)	Partial
URD-EMP-007	Must	Owner can deactivate or remove an employee account	Partial
URD-EMP-008	Must	System validates that the owner actually owns the organizer and all listed merchants	Partial

AC-EMP-01: Employee creation

Given	When	Then
Owner	Creates employee with merchant list	Account created with Employee role, linked to org + merchants
Owner does not own the organizer	Creates employee	Forbidden
Merchant not under owner's organizer	Included in list	Validation error

AC-EMP-02: Merchant reassignment

Given	When	Then
Existing employee	Owner updates assignments	Previous assignments replaced with new ones
-	-	Employee sees only the new merchants

OPS - Operations Staff Administration (BO) Partial

Spec: PRD-OPS-001 · 12 requirements · 2 acceptance scenarios

An operations-team member administers internal staff accounts - the people who run the platform - from the Back Office. These are the holders of the internal fixed roles (Super Admin / Admin / Operator), distinct from a merchant's own staff (EMP) and from end customers (the Customer module). The operator creates an internal account, assigns it an internal role within the role hierarchy, resets passwords, and activates/deactivates it.

ID	Priority	Requirement	Status
URD-OPS-001	Must	An operator can create an internal (system) staff account from the Back Office	Partial
URD-OPS-002	Must	Internal staff accounts are flagged as system users and listed separately from merchant users and customers	Partial
URD-OPS-003	Must	An internal account is assigned one of the internal fixed roles - Super Admin / Admin / Operator - per the role hierarchy (see ROLE in the Permissions URD)	Partial
URD-OPS-004	Must	A user cannot create or assign a role equal to or higher than their own priority (inherits URD-CROLE-003 in the Permissions URD)	Not built
URD-OPS-005	Must	An operator can update an internal account (profile, identifiers, role, status)	Built
URD-OPS-006	Must	An operator can change an internal account's status (activate / deactivate); deactivated accounts cannot sign in	Built
URD-OPS-007	Must	An operator can trigger a password-reset for an internal account	Not built
URD-OPS-008	Must	Internal accounts are soft-deleted - data is preserved, never hard-deleted	Built
URD-OPS-009	Must	Every internal-account operation (list / read / create / update / delete / reset-password) is individually permission-gated	Not built
URD-OPS-010	Should	The Back Office shows, per internal account, its effective access (role + scope) for review	Not built
URD-OPS-011	Should	Internal accounts can be filtered / searched (by role, status) and counted	Partial
URD-OPS-012	Could	Last sign-in is shown per internal account for audit	Partial

AC-OPS-01: Internal account creation

Given	When	Then
Operator with sufficient priority	Creates an internal account with an internal role	System user created, flagged as system user, role assigned
Operator	Assigns a role ≥ their own priority	Forbidden (URD-OPS-004)
Operator	Lists Back-Office users	Sees only internal/system users, separate from merchant users

AC-OPS-02: Lifecycle & reset

Given	When	Then
Existing internal account	Operator deactivates it	Account cannot sign in; data preserved
Existing internal account	Operator triggers password-reset	Reset flow starts for that account

4. Constraints

ID	Constraint
C-01	Passwords are stored only as a one-way hash using a password-specific hashing algorithm; plain-text storage or logging is forbidden
C-02	The eight fixed roles are pre-seeded and cannot be modified or deleted
C-03	Role priority is enforced - no user can manage a role at their level or above
C-04	Account creation is atomic - partial creation is not allowed
C-05	All records use soft-delete - physical deletion is never performed
C-06	Each identifier type is globally unique (one email belongs to only one user)
C-07	Employees must be linked to both an organizer and at least one merchant
C-08	Session tokens are stateless - permission changes take effect on next sign-in
C-09	All operations except sign-in / sign-up require authentication

5. Non-Goals

• Custom role creation and dynamic permission management → Permissions
• Session management and remote revocation
• User invitation via email or phone
• Login history and audit logging
• MFA enforcement policies
• Customer account lifecycle → Customer

Version History

Date	Author	Description	Ver
2026-02-26	P. Do - Product Owner	Initial user stories	v0.1
2026-04-16	Product	Restructured into URD with requirement IDs	v0.3
2026-05-29	Product	Migrated to module-docs convention; corrected status (BLOCKED, no IDSAFE), added link-account + status-honest gaps	v0.4
2026-06-04	Claude (AI pair)	Reorganize by feature (Feature Spine); each feature carries its own requirements + acceptance; constraints moved to cross-cutting CON	v0.5
2026-06-15	Product	Extend USR (identifier-management resource) + CFG (config resource, pre-merchant reads, custom views); link PRD-USR-002	v0.6
2026-07-05	P. Nguyen	Dropped OAuth (URD-AUTH-014, code left retired); username is the primary identifier, mandatory phone verification via SMS (VNPAY) after onboarding for Owner and below, email optional; two-channel forgot-password (email carries both code and link, SMS OTP when there is no email, never both in parallel); last-identifier-removal guard by scope (email, phone); role-tier sign-in blocks (above Owner cannot enter Client/Sale, Owner and below cannot enter the Back Office); added multi-organizer membership for one user (launchpad + organizer switcher); retired CUS (moved fully to the Customer module); folded CFG into the end of USR; formatting cleanup (dropped em-dashes, backtick-wrapped codes, dropped the company name from "operations team")	v0.7
2026-07-06	P. Nguyen	Added URD-USR-023: accounts created by the operations team in Back Office take a phone number without verification; Back Office shows each identifier's verification state and authorized operations staff can change it manually, no SMS or email involved	v0.8
2026-07-06	P. Nguyen	Merged role definitions into the Permissions URD: dropped URD-ROLE-001..008 (duplicated across two URDs, facts had drifted); split URD-ROLE-009..012 into the new MORG area (Multi-organizer membership, URD-MORG-001..004); updated every PRD reference	v0.9
2026-07-15	Claude (AI pair)	Migrated presentation to the Inventory module's 3-tab URD standard (Overview / Details / History): merged Purpose + Scope into a "5 things to understand first" narrative; replaced the FeatureCatalog component with a feature table in the Overview tab; added a per-row Status column (badge honesty per rule 14e), derived from the FR status already ratified in the related PRDs; merged the Scope table and the Non-Goals list into one Non-Goals section; no requirement, code, or decision was changed	v1.0