Email Verification Flow

Relevant source files

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

• src/main/java/org/example/coding_convention/user/model/EmailVerify.java
• src/main/java/org/example/coding_convention/user/repository/EmailVerifyRepository.java
• src/main/java/org/example/coding_convention/user/service/UserService.java
• src/main/java/org/example/coding_convention/user/model/User.java
• src/main/resources/data.sql

The Email Verification Flow in PhanesEditor is a security mechanism designed to validate user-provided email addresses during the registration process. It ensures that users have access to the email accounts they use for signing up, thereby enhancing system security and preventing unauthorized account creation.

This process involves generating a unique identifier (UUID) upon registration, sending a verification link via email, and updating the user's status to enabled once the link is accessed. The flow bridges the gap between the User entity and the EmailVerify persistence layer to manage the lifecycle of an unverified account.

Sources: src/main/java/org/example/coding_convention/user/service/UserService.java:101-140, README.md

Architecture and Data Components

The system utilizes a dedicated entity to track verification attempts and link them to specific user accounts.

Data Models

• User Entity: Stores the primary user information, including an enabled flag which remains false until verification is complete.
• EmailVerify Entity: A mapping table that links a unique UUID to a specific User idx.

Field	Type	Description
idx	Integer	Primary key for the verification record.
uuid	String	Unique identifier sent to the user's email.
user	User	Many-to-one relationship linking to the user being verified.

Sources: src/main/java/org/example/coding_convention/user/model/EmailVerify.java:14-22, src/main/java/org/example/coding_convention/user/model/User.java:82

Database Schema

The underlying MariaDB structure enforces referential integrity through foreign keys, ensuring that verification records are deleted if a user account is removed.

Verification Process Logic

The verification flow is split into two primary phases: the Signup Phase (trigger) and the Verification Phase (execution).

Phase 1: Signup and Email Dispatch

When a user registers, the UserService performs the following steps:

1. Saves the User entity with an initial enabled status of false.
2. Generates a random UUID.
3. Constructs an HTML email containing a link to the /user/verify endpoint with the UUID as a query parameter.
4. Persists the UUID and User reference in the email_verify table.

Sources: src/main/java/org/example/coding_convention/user/service/UserService.java:102-126

Phase 2: Token Validation

When the user clicks the link in their email, the system processes the request:

Implementation Details

User Activation Logic

The User entity contains a domain method userVerify() specifically for this flow. This method is the only way the enabled field is updated during the verification process.

// From User.java
public void userVerify() {
    this.enabled = true;
}

Sources: src/main/java/org/example/coding_convention/user/model/User.java:82

Repository Layer

The EmailVerifyRepository facilitates the lookup of verification tokens. It extends JpaRepository to provide standard CRUD operations and a custom finder for the UUID.

// From EmailVerifyRepository.java
public interface EmailVerifyRepository extends JpaRepository<EmailVerify, Integer> {
    Optional<EmailVerify> findByUuid(String uuid);
}

Sources: src/main/java/org/example/coding_convention/user/repository/EmailVerifyRepository.java:11-13

Summary

The Email Verification Flow effectively manages user onboarding by decoupling account creation from account activation. By using a UUID-based token system persisted in the email_verify table, PhanesEditor ensures that only users with valid, accessible email addresses can fully utilize the platform's features. The flow concludes by invoking the userVerify() method, which transitions the user to an enabled state.

Sources: src/main/java/org/example/coding_convention/user/service/UserService.java:132-134, src/main/java/org/example/coding_convention/user/model/User.java:82