Auth Service Orchestration

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/src/module/auth/services/auth-orchestrator.service.ts
• apps/api/src/module/auth/auth.controller.ts
• apps/api/src/module/auth/auth.module.ts
• apps/api/src/module/auth/services/google-auth.service.ts
• apps/api/src/module/auth/services/login/login.chain.ts
• apps/api/src/module/auth/services/register/register.chain.ts
• apps/api/src/module/auth/services/password-reset/password-request.chain.ts

The authentication system in the ever-rec API is architected around a central orchestrator, the AuthOrchestratorService. This service acts as a facade, simplifying the API controller layer by abstracting the complexities of user authentication, registration, profile management, and other auth-related operations. It delegates tasks to specialized services and employs a Chain of Responsibility design pattern for multi-step workflows like login, registration, and password updates.

This orchestration approach provides a clean separation of concerns, making the system more modular and extensible. Each major authentication flow is encapsulated within a "chain," which is composed of individual "state" handlers (e.g., FirebaseLoginState, GauzyLoginState). This allows for flexible and maintainable logic, where different back-end services (like Firebase and Gauzy) can be part of the same workflow.

Core Components

The AuthModule is the heart of the authentication system, providing all the necessary services, controllers, and configurations.

Sources: apps/api/src/module/auth/auth.module.ts

AuthOrchestratorService

The AuthOrchestratorService is the primary entry point for all authentication and user management logic initiated from the AuthController. It coordinates a variety of specialized services and workflow chains.

The diagram below shows the dependencies injected into AuthOrchestratorService, illustrating its role as a central coordinator.

AuthModule Providers

The AuthModule registers all the necessary providers for the orchestration to function. This includes the orchestrator itself, various specialized services, and the components for the Chain of Responsibility pattern (chains and states).

Provider	Description
AuthOrchestratorService	The main facade service for all auth operations.
UserService	Manages user records in Firebase and the local database.
AuthenticationService	Handles core authentication logic like re-authentication.
GoogleAuthService	Manages the Google Sign-In flow.
EmailService	Handles sending verification and other emails.
UserProfileService	Manages user profile data and files.
LoginChain	Chain of Responsibility for the login workflow.
RegisterChain	Chain of Responsibility for the user registration workflow.
RequestPasswordChain	Chain of Responsibility for the password reset request workflow.
PasswordUpdateChain	Chain of Responsibility for updating a user's password.
UpdateUserProfileChain	Chain of Responsibility for updating user profile information (name, email, avatar).
FirebaseLoginState	A state/handler within the LoginChain for Firebase authentication.
GauzyLoginState	A state/handler within the LoginChain for Gauzy-specific logic.
FirebaseRegisterState	A state/handler within the RegisterChain for Firebase user creation.
GauzyRegisterState	A state/handler within the RegisterChain for Gauzy-specific logic.

Sources: apps/api/src/module/auth/auth.module.ts:77-133

Chain of Responsibility Pattern

The system heavily utilizes the Chain of Responsibility pattern to process complex, multi-step authentication workflows. Each workflow (e.g., login, register) is represented by a Chain class (e.g., LoginChain). The chain executes a sequence of State objects, where each state performs a specific part of the process.

This pattern is evident in the auth.module.ts file, where chains like LoginChain and RegisterChain are provided, along with their constituent states (e.g., FirebaseLoginState, GauzyLoginState).

The following diagram illustrates the generic flow of a request through a chain.

Key Authentication Flows

User Registration

The user registration process is handled by the register method in the AuthOrchestratorService, which delegates the entire workflow to the RegisterChain.

User Login

Standard email/password login is handled by the login method, which delegates to the LoginChain.

Google Login

Google authentication is a distinct flow that does not use the chain pattern. The AuthOrchestratorService delegates directly to the GoogleAuthService. This service handles the exchange of the Google ID token for a Firebase session, creates a new user if one doesn't exist, and generates a custom token for the client.

Password Reset

The password reset flow is initiated via the sendPasswordResetEmail method, which uses the RequestPasswordChain to handle the logic of generating and sending a reset link.

API Endpoints Summary

The AuthController exposes several endpoints that are handled by the AuthOrchestratorService.

Method	Endpoint	AuthOrchestratorService Method	Description
POST	/auth/register	register	Registers a new user.
POST	/auth/login	login	Logs in a user with email and password.
POST	/auth/login-google	processGoogleLogin	Logs in or registers a user via Google credentials.
GET	/auth/user-data	getUserData	Retrieves the current user's profile data.
PUT	/auth/user-data	updateUserData	Updates the user's display name.
POST	/auth/upload-avatar	uploadAvatar	Uploads and updates the user's avatar.
PUT	/auth/email	changeUserEmail	Changes the user's email address.
PUT	/auth/password	changeUserPassword	Changes the user's password.
DELETE	/auth/user	deleteUser	Deletes the user's account and all associated data.
POST	/auth/send-password-reset-email	sendPasswordResetEmail	Sends a password reset link to the user's email.
GET	/auth/refresh-token	(Handled by TokenService)	Refreshes the user's authentication token.

Sources: apps/api/src/module/auth/auth.controller.ts

Conclusion

The Auth Service Orchestration, centered around AuthOrchestratorService and the Chain of Responsibility pattern, provides a robust and maintainable architecture for handling authentication and user management. It effectively decouples the API controller from the underlying business logic and service integrations (like Firebase and Gauzy). This design promotes modularity, allowing new authentication strategies or steps to be added with minimal changes to the existing codebase by simply creating new State handlers and adding them to the appropriate Chain.