πŸ—‚οΈ 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

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Data Model: PayrollMatch
    1. Class-Level Attributes
    2. Properties
    3. Data Annotations Explained
  4. Usage Examples
    1. Creating a New PayrollMatch
    2. Querying & Updating Records
  5. UML Class Diagram
  6. Key Considerations & Best Practices
  7. 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 the irby.PayrollMatch table 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]
    Marks PayrollMatchId as the primary key.
  • [ForeignKey("EmployeeId")]
    Defines a one-to-many relationship to the Employee class using EmployeeId.
  • [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

PayrollMatch UML


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
    The AddedBy/AddedDate and ModifiedBy/ModifiedDate fields 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! πŸš€