The domain layer contains pure business logic with entities and value objects that enforce invariants and encapsulate domain rules.
Entities
Entities represent core business concepts with unique identity and lifecycle.
User
Core user entity with authentication, authorization, and profile management.
Domain entity representing a user in the system.
Structure
pub struct User {
pub id: String,
pub email: EmailAddress,
pub username: Username,
pub password_hash: String,
pub role: Role,
pub is_active: bool,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
UUID identifier generated on entity creation
Email value object with domain validation
Username value object with format validation
Bcrypt hashed password (never store plain text)
User role enum (Admin, User, Moderator, Premium)
Account activation status
Smart Constructors
Constructors enforce invariants and return Result for safe creation.
new
pub fn new(
email: EmailAddress,
username: Username,
password_hash: String
) -> Result<Self, DomainError>
pub fn new_with_role(
email: EmailAddress,
username: Username,
password_hash: String,
role: Role
) -> Result<Self, DomainError>
Business Logic Methods
Methods that encapsulate domain rules and queries.
pub fn is_admin(&self) -> bool
pub fn can_moderate(&self) -> bool
pub fn is_active(&self) -> bool
pub fn is_admin(&self) -> bool {
self.role.is_admin()
}
pub fn can_moderate(&self) -> bool {
self.role.can_moderate()
}
Mutation Methods
Mutation methods automatically update the updated_at timestamp.
pub fn update_email(&mut self, email: EmailAddress)
pub fn update_username(&mut self, username: Username)
pub fn update_password_hash(&mut self, password_hash: String)
pub fn change_role(&mut self, role: Role)
pub fn activate(&mut self)
pub fn deactivate(&mut self)
pub fn update_email(&mut self, email: EmailAddress) {
self.email = email;
self.updated_at = Utc::now();
}
Conversions
to_response
pub fn to_response(&self) -> UserResponse
SQLx Integration
Implements FromRow for automatic deserialization from database:
impl sqlx::FromRow<'_, PgRow> for User {
fn from_row(row: &PgRow) -> Result<Self, sqlx::Error> {
// Uses from_trusted for value objects from DB
Ok(User {
email: EmailAddress::from_trusted(row.try_get("email")?),
username: Username::from_trusted(row.try_get("username")?),
// ...
})
}
}
TestItem
Simple entity demonstrating CRUD patterns.
Example entity for testing and demonstration.
Structure
pub struct TestItem {
pub id: String,
pub subject: String,
pub optional_field: Option<String>,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
Methods
new
pub fn new(subject: String, optional_field: Option<String>) -> Self
pub fn update_subject(&mut self, subject: String)
pub fn update_optional_field(&mut self, optional_field: Option<String>)
pub fn to_response(&self) -> TestItemResponse
Claims
JWT claims entity for authentication tokens.
JWT token claims for user authentication.
Structure
pub struct Claims {
pub sub: String, // Subject (user ID)
pub email: String,
pub role: String,
pub exp: i64, // Expiration timestamp
pub iat: i64, // Issued at timestamp
}
Methods
new
pub fn new(user_id: String, email: String, role: String, exp: i64) -> Self
pub fn is_admin(&self) -> bool
pub fn has_role(&self, required_role: &str) -> bool
pub fn has_any_role(&self, roles: &[&str]) -> bool
Value Objects
Value objects encapsulate domain concepts with validation and are immutable.
EmailAddress
Validated email address value object.
Newtype wrapper around String with email validation.
Methods
new
pub fn new(value: String) -> Result<Self, DomainError>
- Cannot be empty
- Must contain ’@’ symbol
Example from source (email_address.rs:9-14):
if value.trim().is_empty() || !value.contains('@') {
return Err(DomainError::Validation("Invalid email format".into()));
}
Ok(Self(value))
pub fn from_trusted(value: String) -> Self
pub fn as_str(&self) -> &str
Username
Validated username value object.
Newtype wrapper around String with username validation.
Methods
new
pub fn new(value: String) -> Result<Self, DomainError>
pub fn from_trusted(value: String) -> Self
pub fn as_str(&self) -> &str
Role
User role enumeration with permission logic.
User role with four variants: Admin, User, Moderator, Premium.
Variants
pub enum Role {
Admin,
User,
Moderator,
Premium,
}
Methods
as_str
pub fn as_str(&self) -> &str
pub fn from_str(s: &str) -> Option<Self>
match s.to_lowercase().as_str() {
"admin" => Some(Role::Admin),
"user" => Some(Role::User),
"moderator" => Some(Role::Moderator),
"premium" => Some(Role::Premium),
_ => None,
}
pub fn is_admin(&self) -> bool
pub fn can_moderate(&self) -> bool
pub fn can_moderate(&self) -> bool {
matches!(self, Role::Admin | Role::Moderator)
}
Trait Implementations
impl Default for Role // Returns Role::User
impl Display for Role // Uses as_str()
impl From<Role> for String // Converts to String
Design Patterns
Smart Constructors
All value objects and entities use smart constructors that return Result to enforce invariants at creation time.
Encapsulation
Value objects wrap primitives to provide type safety and domain-specific validation.
Immutability
Value objects are immutable. Entities use mutation methods that update timestamps automatically.
Separation from Infrastructure
Domain types have no dependencies on web frameworks or databases (except SQLx FromRow for convenience).