FR-01 — Authentication, Identity & Access Management (IAM)

Introduction

This section defines the Domain & Data Model for FR-01 — Authentication, Identity & Access Management.

The IAM domain establishes the foundation for identifying users, managing their account lifecycle, supporting onboarding, and determining their access to the SalesFam platform.

The model is centered around a single User identity. Depending on the account type selected during onboarding, that User may be associated with either a Company profile or a Sales Representative profile. Authentication and account-supporting concepts such as verification codes, sessions, and password resets are also represented as separate domain entities.

Purpose

Defines the core identity and account-related entities required to support SalesFam authentication, onboarding, account management, and access control. The model separates the user's platform identity from their business profile and authentication-related records.

Scope

The FR-01 domain model covers:

• User identity
• Company profile
• Sales Representative profile
• Email verification
• Authentication sessions
• Password recovery
• Account roles
• Account status
• Onboarding status
• Relationships between these entities

This model provides the foundation for the later database and API designs for IAM.

Entities

1. User

Purpose: Represents the central identity of a person who interacts with the authenticated parts of SalesFam.

Key data:

• User ID
• Email
• Password credential
• Role
• Account status
• Email verification timestamp
• Created timestamp
• Updated timestamp

Role values: Company, Sales Representative, Admin.

A User is the owner of the authentication identity. Company and Sales Representative information is represented through separate profiles.

2. Company

Purpose: Represents the merchant profile created when a verified User selects Company during onboarding.

Key data:

• Company ID
• User ID
• Onboarding status
• Created timestamp
• Updated timestamp

The full Company business data will be extended under FR-02 — Merchant & Product Management.

3. Sales Representative

Purpose: Represents the sales promoter profile created when a verified User selects Sales Representative during onboarding.

Key data:

• Sales Representative ID
• User ID
• Onboarding status
• Created timestamp
• Updated timestamp

The full Sales Representative business data will be extended under FR-03 — Rep Onboarding & Commission Contracts.

4. Verification Code

Purpose: Represents a temporary verification record used to confirm control of the email address provided during registration.

Key data:

• Verification Code ID
• User ID
• Verification code
• Expiration time
• Used time
• Created timestamp

A User may have multiple verification records because a new code may be requested.

5. Session

Purpose: Represents an authenticated access session belonging to a User.

Key data:

• Session ID
• User ID
• Refresh credential
• Expiration time
• Revocation time
• Created timestamp

A User may have multiple active or historical sessions.

6. Password Reset

Purpose: Represents a temporary password-recovery record associated with a User.

Key data:

• Password Reset ID
• User ID
• Reset credential
• Expiration time
• Used time
• Created timestamp

A password-reset record is temporary and must not represent the user's permanent credential.

Entity Relationships

• User → Company: A User may have zero or one Company profile, created when the User selects the Company account type during onboarding.
• User → Sales Representative: A User may have zero or one Sales Representative profile, created when the User selects the Sales Representative account type during onboarding.
• User → Verification Code: A User may have multiple verification records, supporting verification-code resend and expiration.
• User → Session: A User may have multiple sessions, supporting multiple devices or active sessions.
• User → Password Reset: A User may have multiple password-reset records over time.

Identity and Onboarding Model

The identity lifecycle is:

The account type is selected after email verification, not during initial registration.

Role Model

SalesFam has three authenticated roles: COMPANY, REP, ADMIN.

• Company: Represents the merchant side of the platform.
• Rep: Represents the sales/promoter side of the platform.
• Admin: Represents SalesFam's internal platform operator.
• Guest: Not an authenticated role — a Guest is simply an unauthenticated visitor who can access functionality explicitly available to unauthenticated users.

Account Status Model

Account status represents the condition of the User account itself:

PENDING_VERIFICATION → EMAIL_VERIFIED → ACTIVE → SUSPENDED → DEACTIVATED

Account status controls whether the User can access authenticated platform functionality.

Onboarding Status Model

Onboarding status represents the progress of the Company or Sales Representative profile:

NOT_STARTED → IN_PROGRESS → COMPLETED

Account status and onboarding status are separate concepts. For example, a User can have Account Status ACTIVE with Role COMPANY, while its Company profile still has Onboarding Status IN_PROGRESS. The User may be authenticated while the Company profile is still incomplete.

Domain Rules

Rule 1 — Single Identity. Authentication is based on the User entity. Company and Sales Representative do not have separate authentication identities.

Rule 2 — Account Type After Verification. The User must complete email verification before selecting the Company or Sales Representative account type.

Rule 3 — One Business Profile. A normal User selects one account type during MVP onboarding and receives the corresponding business profile.

Rule 4 — Admin. An Admin does not require a Company or Sales Representative profile.

Rule 5 — Guest Boundary. A Guest has no authenticated User identity and therefore has no access to protected Company, Rep, or Admin resources.

Rule 6 — Identity Persistence. The User identity remains associated with its business profile and historical platform activity even when the account becomes suspended or deactivated.

Domain Summary

Entity	Main Responsibility
User	Central platform identity
Company	Merchant business profile
Sales Representative	Sales promoter profile
Verification Code	Email verification
Session	Authenticated access session
Password Reset	Password recovery

This completes the FR-01 Domain & Data Model. It defines what exists in the IAM domain and how the entities relate, without deciding how they will be physically stored or exposed through APIs.