User Management Phase A In-progress

Account lifecycle, authentication, and role-scoped access for every user type — internal operators, business owners, store employees, and customers. It is the platform's foundation: every other module trusts the identity and scope this module issues.

1. Identity

Property	Value
Module ID	CORE-01
Tier	Core
Status	In-progress
Phase	P1 (auth + owner) shipped · P2 (employee + customer) in progress
Priority	HIGH
Primary users	Owner · Cashier · Employee · Customer · Internal operators (Super Admin / Admin / Operator)

2. Purpose & Scope

Included	Excluded
Sign-up, sign-in (username / email / phone + password)	OAuth / third-party login (scheme defined, no provider)
Password change + forgot-password reset	Session revocation / remote logout (stateless JWT)
Email & phone verification via OTP	Two-factor enforcement (scheme defined, not enforced)
User profile, identifiers, and per-user settings	Custom role creation → Permissions
Employee lifecycle + merchant assignment	User invitations
Customer lifecycle + promote-to-user	Multi-organization access for one user
Eight fixed roles + role-scoped data filtering	Audit / login history

3. Capabilities

Capability	What the user can do	Status
Sign-up	Create an account with username + password; profile, identifiers, and default settings are created together	Built
Sign-in	Authenticate with any verified identifier + password; receive a scoped session token	Built
Change password	Verify current password, then set a new one	Built
Forgot password	Reset a forgotten password via OTP (request → verify code → set new)	Built
Email / phone verification	Verify an email or phone identifier with a one-time code	Built
Link account	Add a verified email or phone to an existing account	Built
User profile & identifiers	Maintain name, birthday, locale, and multiple emails / phones	Built
Per-user settings	Default settings auto-created on registration; user can read / update them	Built
Fixed roles & scoping	Eight system roles; list / count operations filtered by the caller's scope	Built
Employee management	Owner creates, assigns to merchants, updates, deactivates, removes employees	In-progress
Customer management	Owner creates / updates / soft-deletes customers; promote a sale customer to a full user	In-progress
Two-factor auth	Credential scheme exists; enforcement not built	Planned
OAuth login	Credential scheme exists; login flow not built	Planned

Known gaps (status-honest): email verification on sign-up is currently disabled in code, so a fresh sign-up may not be able to sign in by email until verified through a separate flow; customer accounts are created without credentials, so they cannot sign in yet. See the developer docs for details.

4. Module Dependencies

Depends on	Why
Permissions	Roles, permissions, and policy edges that define what each user can do
Commerce	Owners and employees belong to organizations; employees and customers scope to merchants
CRM	Customer accounts feed customer relationship management

5. Backend Packages

Implementation detail lives in the developer docs — this section only maps the module to the services that power it.

Package	Role	Developer docs
@nx/identity	JWKS issuer (ES256); owns users, credentials, identifiers, roles, employees, customers, OTP	identity

Feature deep-dives: Authentication · User Management · Customer Management · RBAC · MFA & OTP.

6. Key User Flows

Sign-in

Sign-up & onboarding

Employee lifecycle

7. Roles & Permissions

Eight fixed system roles, ordered by priority. They are pre-seeded and cannot be edited or deleted. Custom roles are out of scope here — see Permissions.

Role	Type	Scope	Can	Cannot
Super Admin	Internal	System-wide	Everything; bypasses all data filters	—
Admin	Internal	System-wide	Everything; bypasses all data filters	—
Operator	Internal	System-wide	Read-focused platform operations	Mutate beyond support scope
Owner	External	Own organization	Manage own org and all its merchants, employees, customers	Touch other organizations
Cashier	External	Assigned merchants	Operate assigned merchants (same tier as Employee)	Access unassigned merchants
Employee	External	Assigned merchants	Operate only assigned merchants	Access unassigned merchants
Customer	External	Linked organization	Customer-scoped access	Operate stores
Guest	External	Global	Unauthenticated-style access	Any backend permission (lowest priority)

Rule: a user can never create, grant, or manage a role with priority equal to or higher than their own.

8. Status & Roadmap

Phase	Capabilities
P1	Sign-up / sign-in, password change & reset, email/phone OTP, profile & identifiers, per-user settings, fixed roles & scoping, Owner auto-assignment
P2	Employee lifecycle + merchant assignment, customer lifecycle + promote-to-user, full user status lifecycle, role-based data filtering
P3	Custom role creation (→ Permissions), OAuth / third-party login, two-factor enforcement, login history, session revocation, user invitations, multi-organization

9. Related Pages

• URD
• Test Cases
• PRDs
• Permissions — roles & access control
• Commerce — organizations & merchants
• Identity developer docs