FR-01 — IAM Architecture
Introduction
The FR-01 IAM Architecture defines how Authentication, Identity & Access Management is structured within the SalesFam backend. It establishes the separation of responsibilities between authentication, authorization, onboarding, session management, verification, password recovery, business profiles, and data access.
Scope
The IAM architecture covers the components and interactions required to support:
- User registration and verification
- Account-type onboarding
- Authentication and session management
- Password recovery
- Role-based access control
- Resource authorization
- Company and Sales Representative profiles
- IAM-related data access and communication services
The architecture is designed as a foundation for the functional areas that depend on authenticated identity and authorization.
1. Architecture Objective
The IAM architecture defines how SalesFam handles identity, authentication, onboarding, authorization, and session management while keeping these responsibilities separated and maintainable. The architecture should allow the IAM functionality to serve Company, Sales Representative, and Admin users without creating separate authentication systems.
2. High-Level Request Flow
For protected requests:
For public authentication operations:
3. IAM Components
Authentication Controller — handles incoming authentication requests and returns the appropriate API response (Register, Verify, Resend verification, Login, Logout, Refresh, Forgot password, Reset password). The controller should not contain business logic.
Authentication Service — contains the core IAM business logic: creating users, verifying accounts, selecting account type, authenticating credentials, creating/revoking sessions, password recovery, enforcing account lifecycle rules.
Authorization Middleware — runs before protected operations: identifying the authenticated user, verifying the user's role, rejecting unauthorized access. Conceptually: Request → Authenticate → Identify User → Check Role → Continue / Reject.
Resource Authorization — RBAC alone is not enough. Where a protected resource belongs to a specific Company or Rep, the application must also verify ownership or explicit access: Authentication → RBAC → Resource Ownership → Operation. This becomes especially important for orders, contracts, commissions, and financial records later.
Session Service — responsible for creating sessions, refreshing sessions, revoking sessions, checking session validity, and managing session expiration. It isolates session lifecycle logic from the rest of authentication.
Verification Service — responsible for generating verification codes, storing their protected representation, validating codes, expiring codes, resending codes, and applying resend/attempt limits.
Password Recovery Service — responsible for creating password-reset credentials, validating reset credentials, expiring reset credentials, resetting passwords, and invalidating applicable sessions after a successful reset.
Email Service — responsible for sending IAM-related emails such as verification codes and password recovery instructions. The IAM services request an email; the Email Service handles delivery. This keeps email-provider logic out of the authentication logic.
User / Profile Data Access — the data-access layer handles persistence for User, Company, Sales Representative, Verification Code, Session, and Password Reset. Services should communicate with the database through this layer rather than embedding database operations directly inside controllers.
4. Recommended Backend Structure
backend/
├── routes/
│ └── auth/
├── controllers/
│ └── auth/
├── services/
│ └── auth/
├── middleware/
│ ├── authentication/
│ └── authorization/
├── validators/
├── utilities/
└── infrastructure/
└── email/
The exact folder naming can follow the project's established backend conventions. The important part is separation of responsibility, not the folder names themselves.
5. IAM Responsibility Flow
Registration:
Login:
Protected Request:
6. Account-Type Onboarding Flow
The onboarding services create the appropriate profile while the central User identity remains unchanged.
7. Error Handling Boundary
IAM services should return meaningful application errors to a centralized error-handling layer: Service → Application Error → Error Handler → Standard API Error Response. This prevents controllers and individual services from implementing different error-response formats.
8. Architecture Principles
The FR-01 architecture should follow these principles:
- Single identity system: One User identity supports Company, Rep, and Admin.
- Separation of concerns: Controllers, services, authorization, and persistence have distinct responsibilities.
- Server-side authorization: The client never determines its own permissions.
- Resource-level protection: Role checks are combined with ownership checks where required.
- Reusable IAM services: Verification, sessions, and password recovery remain independently manageable.
- Future extensibility: IAM should support later features such as additional verification or stronger authentication without redesigning the entire platform.