ποΈ PayrollMatch Domain Model Documentation
Welcome to the comprehensive documentation for the PayrollMatch domain class (file: IrbyImaging.DomainClasses/EmployeeMatch.cs). This guide covers everything you need to know about its purpose, structure, usage, and integration within the IrbyImaging solution.
π Table of Contents
- Overview & Purpose
- Dependencies & Technologies
- Data Model:
PayrollMatch - Usage Examples
- UML Class Diagram
- Key Considerations & Best Practices
- Conclusion
1. Overview & Purpose
The PayrollMatch class represents a record of employer and employee contribution matches in the payroll system.
It lives in the database schema irby.PayrollMatch and is part of the IrbyImaging.DomainClasses assembly.
Primary uses
- Store details about how much the employer and the employee have each contributed (matched) for a given period or event.
- Track who added or modified each record and when.
2. Dependencies & Technologies
| Technology / Package | Purpose |
|---|---|
System |
Core .NET types (e.g., Guid, DateTime). |
System.Collections.Generic |
Collections support |
System.ComponentModel.DataAnnotations |
Validation & display attributes |
System.ComponentModel.DataAnnotations.Schema |
Database mapping attributes (Table, Key, ForeignKey) |
| Entity Framework (Core) | ORM for data persistence (inferred) |
Note: Although EF Core is not explicitly imported in the file, the presence of
[Key],[Table], and[ForeignKey]implies usage within an EF-based data layer.
3. Data Model: PayrollMatch
namespace IrbyImaging.DomainClasses
{
[Table("PayrollMatch", Schema = "irby")]
public class PayrollMatch
{
[Key]
public Guid PayrollMatchId { get; set; }
[Display(Name = "Employee Id")]
public Guid EmployeeId { get; set; }
[ForeignKey("EmployeeId")]
public Employee Employee { get; set; }
public string EmployeeNumber { get; set; }
public decimal EmployerMatch { get; set; }
public decimal EmployeeMatch { get; set; }
[Display(Name = "Added By")]
public string AddedBy { get; set; }
[Display(Name = "Added Date")]
public DateTime AddedDate { get; set; }
[Display(Name = "Modified By")]
public string ModifiedBy { get; set; }
[Display(Name = "Modified Date")]
public DateTime ModifiedDate { get; set; }
}
}
3.1 Class-Level Attributes
[Table("PayrollMatch", Schema = "irby")]
Maps this class to theirby.PayrollMatchtable in the database.
3.2 Properties
| Property | Type | Description |
|---|---|---|
PayrollMatchId |
Guid |
Primary key for each match record. |
EmployeeId |
Guid |
Foreign key referencing an Employee. |
Employee |
Employee |
Navigation property to the employee entity. |
EmployeeNumber |
string |
Business identifier (e.g., badge or payroll number). |
EmployerMatch |
decimal |
Amount contributed by the employer. |
EmployeeMatch |
decimal |
Amount contributed by the employee. |
AddedBy |
string |
Username or identifier of the user who created the record. |
AddedDate |
DateTime |
Timestamp when the record was created. |
ModifiedBy |
string |
Username or identifier of the last user who modified the record. |
ModifiedDate |
DateTime |
Timestamp when the record was last updated. |
3.3 Data Annotations Explained
[Key]
MarksPayrollMatchIdas the primary key.[ForeignKey("EmployeeId")]
Defines a one-to-many relationship to theEmployeeclass usingEmployeeId.[Display(Name = "...")]
Provides friendly UI/display names (helps in scaffolding and code-first migrations).
4. Usage Examples
4.1 Creating a New PayrollMatch
using (var context = new IrbyDbContext())
{
var newMatch = new PayrollMatch
{
PayrollMatchId = Guid.NewGuid(),
EmployeeId = someEmployeeId,
EmployeeNumber = "EMP-00123",
EmployerMatch = 150.00m,
EmployeeMatch = 75.00m,
AddedBy = "system_admin",
AddedDate = DateTime.UtcNow,
ModifiedBy = "system_admin",
ModifiedDate = DateTime.UtcNow
};
context.PayrollMatches.Add(newMatch);
context.SaveChanges();
}
4.2 Querying & Updating Records
// Fetch all matches for a given employee
var matches = context.PayrollMatches
.Where(pm => pm.EmployeeId == employeeId)
.OrderByDescending(pm => pm.AddedDate)
.ToList();
// Update an existing match
var match = matches.First();
match.EmployerMatch += 25.00m;
match.ModifiedBy = currentUser;
match.ModifiedDate = DateTime.UtcNow;
context.SaveChanges();
5. UML Class Diagram
@startuml
class PayrollMatch {
+ Guid PayrollMatchId
+ Guid EmployeeId
+ string EmployeeNumber
+ decimal EmployerMatch
+ decimal EmployeeMatch
+ string AddedBy
+ DateTime AddedDate
+ string ModifiedBy
+ DateTime ModifiedDate
}
class Employee {
+ Guid EmployeeId
+ string FirstName
+ string LastName
...
}
PayrollMatch "1" --> "1" Employee : ForeignKey(EmployeeId)
@enduml
6. Key Considerations & Best Practices
- Validation
Consider adding[Required],[Range], or custom validation attributes to enforce business rules (e.g., non-negative matches). - Concurrency
If concurrent updates are likely, incorporate rowβversion or timestamp fields to avoid update collisions. - Auditing
TheAddedBy/AddedDateandModifiedBy/ModifiedDatefields form a simple audit trail. Extend with a full audit log if needed. - Decimal Precision
Ensure EF Core column precision matches your business requirements (e.g.,.HasColumnType("decimal(18,2)")).
7. Conclusion
The PayrollMatch class is a straightforward, EF Core-friendly domain model for tracking employer/employee contributions. With clear data annotations and navigational links to the Employee entity, it forms a key part of the payroll subsystem in the IrbyImaging solution. By following the examples and best practices above, you can confidently create, query, and maintain PayrollMatch records in your application. π
Happy coding! π