1. Platform Overview & Scope

An HR and People Management Platform is the operational backbone of every organization. It consolidates employee lifecycle management — from recruiting through offboarding — into a single, integrated system. Platforms like BambooHR, Gusto, Workday, and Rippling serve companies ranging from 10-person startups to 100,000+ employee enterprises, and each tier demands fundamentally different architectural trade-offs.

At its core, an HR platform must answer five questions:

1. Who works here? — Employee directory, profiles, org charts
2. When do they work? — Time tracking, PTO, scheduling
3. What do we owe them? — Payroll, benefits, compensation
4. How are they performing? — Goals, reviews, feedback
5. Are we compliant? — Tax filings, labor laws, data privacy

Target Scale

This guide targets the SMB-to-enterprise transition — a multi-tenant SaaS platform supporting up to 50,000 employees per tenant, with strict compliance requirements for US, EU, and UK labor markets.

2. High-Level Architecture

Architecture Principles

• Multi-tenant isolation: Each company's data is isolated at the database schema level. Shared infrastructure with row-level security as defense-in-depth.
• Event-driven cascades: Employee lifecycle events (hire, transfer, termination) are published to Kafka and consumed by downstream services to maintain eventual consistency.
• Modular monolith option: For teams under 20 engineers, a modular monolith with clear domain boundaries is preferable to full microservices.
• Audit everything: Every data mutation is recorded in an immutable audit log. HR data is legally sensitive — "who changed what, when" must be provable.
• Idempotent payroll: Payroll runs must be idempotent. A retry of the same pay period must not double-pay employees.

Service Communication Pattern

Text
Sync calls (gRPC):  Client → API Gateway → Service → Service
                    Used for: reads, simple writes, real-time lookups

Async events (Kafka): Service → Topic → Consumer Group
                    Used for: lifecycle cascades, notifications, audit logging
                    Guarantees: at-least-once delivery, idempotent consumers

Outbox pattern:     Service writes to DB + outbox table in same transaction
                    Debezium CDC reads outbox → publishes to Kafka
                    Eliminates dual-write problem

3. Employee Directory & Profiles

The employee directory is the foundational data model from which nearly every other module derives its data. It must handle rich profiles, employment history, custom fields, and document attachments while remaining performant for search-heavy access patterns.

Data Model

C#
public class Employee
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public string EmployeeNumber { get; set; }
    public EmployeeStatus Status { get; set; }

    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string PreferredName { get; set; }
    public string Email { get; set; }
    public string PersonalEmail { get; set; }
    public string PhoneNumber { get; set; }
    public DateTime DateOfBirth { get; set; }
    public string Gender { get; set; }
    public string Ethnicity { get; set; }
    public string Pronouns { get; set; }

    public Guid DepartmentId { get; set; }
    public Guid PositionId { get; set; }
    public Guid LocationId { get; set; }
    public Guid ManagerId { get; set; }
    public DateTime HireDate { get; set; }
    public DateTime? TerminationDate { get; set; }
    public EmploymentType EmploymentType { get; set; }
    public string EmploymentClassification { get; set; }

    public decimal AnnualSalary { get; set; }
    public string Currency { get; set; }
    public string PayFrequency { get; set; }

    public Address HomeAddress { get; set; }
    public List<EmergencyContact> EmergencyContacts { get; set; }
    public Dictionary<string, object> CustomFields { get; set; }
}

public class EmployeeProfile : Employee
{
    public string FullName => $"{FirstName} {LastName}";
    public int TenureDays => (DateTime.UtcNow - HireDate).Days;
    public string OrgPath { get; set; }
    public int DirectReportsCount { get; set; }
    public ProfilePhoto Photo { get; set; }
    public List<Skill> Skills { get; set; }
}

Employee Lifecycle State Machine

Search & Directory Features

• Full-text search: Elasticsearch index across name, email, job title, department, skills, location.
• Filtered views: Filter by department, location, status, manager, hire date range.
• Directory browsing: Hierarchical org tree view with expand/collapse. Lazy loading for large orgs.
• Profile completeness: Dashboard widget showing completion percentage to drive self-service data collection.
• Privacy controls: SSN, salary, personal email visible only to HR admins and the employee themselves.

Indexing Strategy

SQL
CREATE INDEX idx_employee_search ON employees
    USING GIN (
        to_tsvector('english',
            coalesce(first_name, '') || ' ' ||
            coalesce(last_name, '') || ' ' ||
            coalesce(email, '') || ' ' ||
            coalesce(job_title, '')
        )
    )
    WHERE tenant_id = $1 AND status = 'Active';

CREATE INDEX idx_employee_org_path ON employees (tenant_id, org_path)
    WHERE status = 'Active';

CREATE INDEX idx_employee_dashboard ON employees
    (tenant_id, department_id, status, hire_date DESC);

4. Organizational Chart

The org chart visualizes reporting relationships and organizational structure. It must support multiple hierarchy types (solid-line, dotted-line), matrix organizations, and dynamic restructuring without data loss.

Hierarchy Model

C#
public class OrgNode
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public Guid EmployeeId { get; set; }
    public Guid? ParentNodeId { get; set; }
    public string OrgPath { get; set; }
    public int Depth { get; set; }
    public string HierarchyType { get; set; }
    public string CostCenter { get; set; }
    public bool IsHeadcount { get; set; }
    public List<OrgNode> Children { get; set; }
    public Employee Employee { get; set; }
    public int SubtreeSize { get; set; }
}

Org Chart Operations

Rendering Considerations

• Large orgs (1000+ nodes): Render only the visible viewport. Load children lazily on expand. Use virtual scrolling for the list view.
• Multiple views: Tree view (default), reporting lines, cost center view, location view.
• Export: PNG, PDF, and interactive HTML exports for board presentations.
• Historical org charts: Store org structure snapshots to show "what the org looked like on Jan 1, 2024."

5. Onboarding Workflows

Onboarding transforms a signed offer letter into a fully provisioned, productive employee. It spans pre-boarding (before day one), the first week, first 30 days, and first 90 days.

Workflow Engine Design

C#
public class OnboardingWorkflow
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public Guid EmployeeId { get; set; }
    public string TemplateId { get; set; }
    public OnboardingStatus Status { get; set; }
    public DateTime StartDate { get; set; }
    public List<OnboardingPhase> Phases { get; set; }
}

public class OnboardingPhase
{
    public string Name { get; set; }
    public int Order { get; set; }
    public int DaysBeforeStart { get; set; }
    public List<OnboardingTask> Tasks { get; set; }
}

public class OnboardingTask
{
    public string Title { get; set; }
    public string TaskType { get; set; }
    public string AssigneeType { get; set; }
    public bool IsRequired { get; set; }
    public bool IsCompleted { get; set; }
    public DateTime? DueDate { get; set; }
    public string DocumentTemplateId { get; set; }
    public List<string> Dependencies { get; set; }
}

Document Collection Checklist

Pre-Building Automation

C#
public class OnboardingOrchestrator
{
    private readonly IEventBus _eventBus;
    private readonly IProvisioningService _provisioning;

    public async Task HandleOfferAccepted(OfferAcceptedEvent e)
    {
        var workflow = await CreateWorkflow(e.OfferId, e.EmployeeId);

        await Task.WhenAll(
            _provisioning.CreateCompanyEmail(e.EmployeeEmail),
            _provisioning.ProvisionLaptop(e.EmployeeId, e.OfficeLocation),
            _provisioning.AddToSlackWorkspace(e.EmployeeEmail),
            _provisioning.CreateGitLabAccount(e.EmployeeEmail),
            _provisioning.ScheduleOrientation(e.StartDate, e.OfficeLocation),
            _provisioning.AssignOnboardingBuddy(e.EmployeeId, e.DepartmentId)
        );

        await _eventBus.Publish(new OnboardingStartedEvent
        {
            EmployeeId = e.EmployeeId,
            StartDate = e.StartDate,
            ManagerId = e.ManagerId
        });
    }
}

6. Time-Off Management

Time-off management is deceptively complex. A typical US company offers 5–10 leave types, each with different accrual rules, carryover limits, eligibility requirements, and legal obligations.

Leave Types & Policies

Accrual Engine

C#
public class AccrualCalculator
{
    public AccrualResult Calculate(EmployeeLeaveBalance balance, PayPeriod period)
    {
        var policy = balance.LeavePolicy;
        decimal earned = policy.AccrualMethod switch
        {
            AccrualMethod.PerPayPeriod =>
                policy.AnnualAllowance / policy.PayPeriodsPerYear,
            AccrualMethod.Hourly =>
                period.HoursWorked * policy.AccrualRatePerHour,
            AccrualMethod.FrontLoaded =>
                balance.YearsOfService >= policy.YearsForFrontLoad
                    ? policy.AnnualAllowance
                    : policy.AnnualAllowance / policy.PayPeriodsPerYear,
            _ => policy.AnnualAllowance / 12m
        };

        earned *= GetSeniorityMultiplier(balance.Employee.YearsOfService, policy);

        decimal newBalance = balance.Available + earned;
        if (newBalance > policy.MaxBalance)
        {
            decimal excess = newBalance - policy.MaxBalance;
            newBalance = policy.MaxBalance;
            if (policy.CarryoverEnabled)
            {
                newBalance += Math.Min(excess, policy.MaxCarryover);
            }
        }

        return new AccrualResult
        {
            Earned = earned,
            NewBalance = newBalance,
            CapApplied = newBalance == policy.MaxBalance
        };
    }
}

Approval Workflow

Blackout Dates & Conflicts

• Blackout periods: Configurable per department (e.g., no PTO during Q4 close for finance).
• Overlap limits: Maximum team members on leave simultaneously (e.g., no more than 20% on the same day).
• Holiday calendar: Company-wide holidays, configurable by country/state.
• Half-day support: Allow partial-day requests (half-day, quarter-day, hourly).

7. Timesheet & Time Tracking

Time tracking serves two purposes: (1) compliance with FLSA for non-exempt employees who must be paid overtime, and (2) project-based cost allocation.

Core Data Model

C#
public class TimeEntry
{
    public Guid Id { get; set; }
    public Guid EmployeeId { get; set; }
    public DateTime Date { get; set; }
    public TimeOnly ClockIn { get; set; }
    public TimeOnly? ClockOut { get; set; }
    public decimal RegularHours { get; set; }
    public decimal OvertimeHours { get; set; }
    public decimal DoubleTimeHours { get; set; }
    public string ProjectCode { get; set; }
    public EntryStatus Status { get; set; }
    public bool IsEdited { get; set; }
    public List<TimeEntryAudit> EditHistory { get; set; }
}

public class TimesheetPeriod
{
    public DateOnly PeriodStart { get; set; }
    public DateOnly PeriodEnd { get; set; }
    public decimal TotalRegularHours { get; set; }
    public decimal TotalOvertimeHours { get; set; }
    public decimal TotalDoubleTimeHours { get; set; }
    public TimesheetStatus Status { get; set; }
    public List<TimeEntry> Entries { get; set; }
}

Overtime Calculation

C#
public class OvertimeCalculator
{
    public OvertimeResult Calculate(Employee employee, List<TimeEntry> weekEntries)
    {
        return employee.WorkState switch
        {
            "CA" => CalculateCaliforniaOvertime(weekEntries),
            "AK" => CalculateAlaskaOvertime(weekEntries),
            _ => CalculateFederalOvertime(weekEntries.Sum(e => e.RegularHours))
        };
    }

    private OvertimeResult CalculateFederalOvertime(decimal totalHours)
    {
        return new OvertimeResult
        {
            RegularHours = Math.Min(totalHours, 40),
            OvertimeHours = Math.Max(0, totalHours - 40),
            DoubleTimeHours = 0
        };
    }

    private OvertimeResult CalculateCaliforniaOvertime(List<TimeEntry> entries)
    {
        decimal dailyOvertime = 0, dailyDoubleTime = 0;
        foreach (var entry in entries)
        {
            decimal dayTotal = entry.RegularHours + entry.OvertimeHours;
            if (dayTotal > 12) dailyDoubleTime += dayTotal - 12;
            if (dayTotal > 8) dailyOvertime += dayTotal - 8;
        }
        decimal weekTotal = entries.Sum(e => e.RegularHours + e.OvertimeHours);
        decimal weeklyOvertime = Math.Max(0, weekTotal - 40);
        decimal totalOT = Math.Max(dailyOvertime + dailyDoubleTime, weeklyOvertime);
        return new OvertimeResult
        {
            RegularHours = Math.Min(weekTotal, 40),
            OvertimeHours = totalOT - dailyDoubleTime,
            DoubleTimeHours = dailyDoubleTime
        };
    }
}

Geofencing & Kiosk Mode

• Geofencing: Mobile app restricts clock-in to within a configurable radius of the worksite.
• Kiosk mode: Shared tablet at worksite. Employees clock in/out with PIN or biometric.
• Break compliance: Auto-prompt for meal/rest breaks per state law (e.g., California: 30-min meal break before 5th hour).
• GPS tagging: Optional GPS coordinates stored with each clock event for remote/mobile workers.

8. Payroll Processing

Payroll is the most critical and regulated module. Employees must be paid accurately and on time. Errors create legal liability, tax penalties, and trust erosion.

Payroll Run Pipeline

Gross-to-Net Calculation

C#
public class PayrollCalculator
{
    public Paystub CalculatePaystub(Employee employee, PayPeriod period,
        List<TimeEntry> timeEntries, List<EarningLine> additionalEarnings,
        List<DeductionLine> deductions)
    {
        var paystub = new Paystub();

        paystub.RegularPay = CalculateRegularPay(employee, timeEntries);
        paystub.OvertimePay = CalculateOvertimePay(employee, timeEntries);
        paystub.DoubleTimePay = CalculateDoubleTimePay(employee, timeEntries);
        paystub.BonusPay = additionalEarnings.Where(e => e.Type == "Bonus").Sum(e => e.Amount);
        paystub.CommissionPay = additionalEarnings.Where(e => e.Type == "Commission").Sum(e => e.Amount);
        paystub.GrossPay = paystub.RegularPay + paystub.OvertimePay + paystub.DoubleTimePay
            + paystub.BonusPay + paystub.CommissionPay;

        paystub.PreTaxDeductionsTotal = employee.Benefits.HealthInsurancePreTax
            + employee.Benefits.DentalVisionPreTax
            + employee.Benefits.HSAContribution
            + employee.Benefits.FSAContribution
            + employee.Benefits.Retirement401kPreTax;

        paystub.TaxableIncomeFederal = paystub.GrossPay - paystub.PreTaxDeductionsTotal;

        paystub.FederalIncomeTax = CalculateFederalWithholding(
            employee.W4Info, paystub.TaxableIncomeFederal, employee.PaidFrequency);
        paystub.StateIncomeTax = CalculateStateWithholding(
            employee.WorkState, paystub.TaxableIncomeFederal, employee.PaidFrequency);

        paystub.SocialSecurityTax = Math.Min(
            paystub.TaxableIncomeFederal * 0.062m, 168_600m * 0.062m / employee.PayPeriodsPerYear);
        paystub.MedicareTax = paystub.TaxableIncomeFederal * 0.0145m;
        if (paystub.TaxableIncomeFederal > 200_000m)
            paystub.MedicareTax += (paystub.TaxableIncomeFederal - 200_000m) * 0.009m;

        paystub.NetPay = paystub.GrossPay - paystub.PreTaxDeductionsTotal
            - paystub.PostTaxDeductionsTotal - paystub.TotalTaxes;

        paystub.TotalEmployerCost = paystub.GrossPay
            + paystub.SocialSecurityTax
            + paystub.MedicareTax
            + CalculateFUTA(paystub, employee)
            + CalculateSUTA(employee.WorkState, paystub);

        return paystub;
    }
}

Direct Deposit & ACH

Tax Filing Automation

• Federal 941: Quarterly Form 941 filing via IRS e-file.
• State quarterly returns: Automated filing for all 50 states + DC.
• W-2 generation: Annual W-2 creation, SSA e-filing, and employee portal access by January 31.
• 1099-NEC: Contractor payment tracking and 1099 generation for payments over $600.
• New hire reporting: Automated reporting to state directories within 20 days of hire.

9. Benefits Administration

Benefits administration manages the enrollment lifecycle for health insurance, retirement plans, and other employee benefits.

Benefits Data Model

C#
public class BenefitsPlan
{
    public Guid Id { get; set; }
    public string PlanName { get; set; }
    public string PlanType { get; set; }
    public string Carrier { get; set; }
    public decimal EmployeePremium { get; set; }
    public decimal EmployerPremium { get; set; }
    public decimal Deductible { get; set; }
    public List<BenefitTier> Tiers { get; set; }
    public bool IsPreTax { get; set; }
}

public class BenefitEnrollment
{
    public Guid EmployeeId { get; set; }
    public Guid PlanId { get; set; }
    public EnrollmentStatus Status { get; set; }
    public string EnrollmentType { get; set; }
    public DateTime EffectiveDate { get; set; }
    public string Tier { get; set; }
    public List<Beneficiary> Beneficiaries { get; set; }
    public Guid? LifeEventId { get; set; }
}

Life Events & Qualifying Events

COBRA Administration

• Trigger: Termination, reduction in hours, divorce, dependent aging out.
• Timeline: Employer notifies COBRA admin within 30 days. Notice to employee within 14 days. Employee has 60 days to elect.
• Duration: 18 months (standard), 36 months (disability), 29 months (qualifying disability).
• Premium: 102% of total plan cost. Employee pays directly.

10. Performance Management

Performance management encompasses goal setting (OKRs), continuous feedback, formal reviews (360-degree), calibration sessions, and performance improvement plans.

Performance Cycle Template

C#
public class PerformanceCycle
{
    public string Name { get; set; }
    public CycleType Type { get; set; }
    public DateTime GoalSettingStart { get; set; }
    public DateTime GoalSettingEnd { get; set; }
    public DateTime SelfReviewStart { get; set; }
    public DateTime SelfReviewEnd { get; set; }
    public DateTime ManagerReviewStart { get; set; }
    public DateTime ManagerReviewEnd { get; set; }
    public DateTime PeerReviewStart { get; set; }
    public DateTime CalibrationStart { get; set; }
    public int PeerReviewersPerEmployee { get; set; }
    public List<RatingScale> RatingScale { get; set; }
}

public class PerformanceReview
{
    public Guid EmployeeId { get; set; }
    public string SelfAssessment { get; set; }
    public decimal SelfRating { get; set; }
    public string ManagerAssessment { get; set; }
    public decimal ManagerRating { get; set; }
    public decimal ManagerCalibratedRating { get; set; }
    public List<PeerReview> PeerReviews { get; set; }
    public string FinalRating { get; set; }
    public bool CalibrationAdjusted { get; set; }
}

OKR Framework

360 Review Workflow

Performance Improvement Plans

• Duration: 30, 60, or 90 days with defined milestones.
• Documentation: All PIP documents stored in personnel file with restricted access.
• Check-ins: Scheduled check-in reminders at configurable intervals.
• Outcomes: Successful completion, extension, or termination — each triggers different downstream workflows.

11. Compensation Management

Compensation management encompasses salary structures, equity grants, bonuses, and total rewards.

Salary Band Structure

C#
public class SalaryBand
{
    public string JobFamily { get; set; }
    public string Level { get; set; }
    public string Geography { get; set; }
    public decimal MinSalary { get; set; }
    public decimal Midpoint { get; set; }
    public decimal MaxSalary { get; set; }
    public string Currency { get; set; }
    public int BandVersion { get; set; }
    public DateTime EffectiveDate { get; set; }
}

// Compa-Ratio: Employee Salary / Band Midpoint
// Below 0.8 = Underpaid, 0.8-1.0 = Developing, 1.0 = At Market, 1.0-1.2 = Above Market

Compensation Review Cycle

Equity Management

Pay Equity Analysis

• Compensation ratio analysis: Compare pay across gender, race, and other protected categories.
• Regression analysis: Statistical analysis controlling for legitimate factors.
• Banding compliance: Flag employees paid above or below band for review.
• Pay transparency: States like CO, CA, NY require salary ranges in job postings.

12. Recruiting Pipeline

The recruiting module (ATS) manages the funnel from job requisition to offer acceptance, integrating seamlessly with Core HR.

Pipeline Stages

Data Model

C#
public class JobRequisition
{
    public string Title { get; set; }
    public Guid DepartmentId { get; set; }
    public Guid HiringManagerId { get; set; }
    public Guid RecruiterId { get; set; }
    public int Headcount { get; set; }
    public string SalaryRangeId { get; set; }
    public RequisitionStatus Status { get; set; }
}

public class Candidate
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
    public string Source { get; set; }
    public Guid? ReferredByEmployeeId { get; set; }
    public PipelineStage CurrentStage { get; set; }
    public List<Interview> Interviews { get; set; }
    public List<Scorecard> Scorecards { get; set; }
    public string ResumeUrl { get; set; }
    public bool IsDiversityCandidate { get; set; }
}

public class Interview
{
    public string InterviewType { get; set; }
    public List<Interviewer> Interviewers { get; set; }
    public DateTime ScheduledAt { get; set; }
    public InterviewStatus Status { get; set; }
    public Scorecard Scorecard { get; set; }
}

ATS Integration Features

• Job board syndication: Post to LinkedIn, Indeed, Glassdoor via XML feed / API.
• Resume parsing: Extract structured data from uploaded resumes using NLP.
• Interview scheduling: Calendar sync with automated availability collection and timezone handling.
• Referral tracking: Employee referral portal with bonus tracking.
• Diversity metrics: Pipeline diversity reporting. Anonymized screening mode to reduce bias.
• EEOC compliance: Voluntary self-identification data stored separately from hiring decisions.

13. Learning Management

The LMS handles training assignments, compliance training, course catalogs, and learning paths. Compliance training is particularly critical.

Training Types

LMS Data Model

C#
public class TrainingAssignment
{
    public Guid EmployeeId { get; set; }
    public Guid CourseId { get; set; }
    public AssignmentSource Source { get; set; }
    public DateTime AssignedDate { get; set; }
    public DateTime DueDate { get; set; }
    public DateTime? CompletedDate { get; set; }
    public AssignmentStatus Status { get; set; }
    public decimal Progress { get; set; }
    public decimal? Score { get; set; }
    public bool Passed { get; set; }
    public DateTime? CertificateExpiration { get; set; }
}

public class Course
{
    public string Title { get; set; }
    public string ContentType { get; set; }
    public int DurationMinutes { get; set; }
    public bool IsCompliance { get; set; }
    public bool Recurring { get; set; }
    public int RecurrenceDays { get; set; }
    public decimal PassingScore { get; set; }
}

SCORM & xAPI Integration

• SCORM 1.2 / 2004: Embed SCORM content in an iframe. Track completion, score, and time.
• xAPI (Experience API): Send detailed learning statements to a Learning Record Store.
• Overdue escalation: Automated reminders at 7 days, 3 days, and 1 day before due. Manager escalation when overdue.

14. Employee Self-Service Portal

The self-service portal empowers employees to manage their own HR data without submitting tickets.

Portal Features Matrix

Mobile-First Design

• Clock in/out: One-tap with GPS verification. Widget for quick access.
• Time-off requests: Calendar view with team availability overlay.
• Push notifications: Approvals pending, pay day reminders, training due dates.
• Biometric auth: Fingerprint and Face ID for mobile app access.
• Offline mode: Cache pay stubs and policy documents for offline viewing.

15. Manager Dashboard

The manager dashboard provides a unified view of everything a manager needs to lead their team.

Dashboard Widgets

C#
public class ManagerDashboard
{
    public int TeamSize { get; set; }
    public int OpenPositions { get; set; }
    public List<PendingAction> PendingActions { get; set; }
    public TeamOverview Overview { get; set; }
    public List<UpcomingEvent> UpcomingEvents { get; set; }
    public PerformanceSnapshot PerformanceSnapshot { get; set; }
    public List<FlightRisk> FlightRisks { get; set; }
    public CompSnapshot CompSnapshot { get; set; }
}

public class PendingAction
{
    public string Type { get; set; }
    public string Title { get; set; }
    public int Count { get; set; }
    public string Url { get; set; }
    public DateTime? DueDate { get; set; }
}

Manager-Specific Workflows

• Bulk approvals: Approve multiple requests in a single action.
• Team calendar: Overlay of PTO, holidays, and events. Drag to create.
• 1:1 meeting support: Agenda builder with talking points from performance and goals.
• Compensation planning: View compa-ratio, performance ratings, and proposed merit increases.
• Org chart editing: Drag-and-drop team restructuring (requires HR approval).

16. Analytics & Reporting

HR analytics transforms raw people data into actionable intelligence.

Key Metrics

DEI Metrics

Report Types

C#
public class ReportEngine
{
    public static readonly string[] StandardReports = new[]
    {
        "Headcount Summary (daily snapshot)",
        "Turnover Report (weekly)",
        "New Hires Report (weekly)",
        "Payroll Summary (per pay period)",
        "Benefits Enrollment Status",
        "Training Compliance Dashboard (monthly)",
        "Diversity Report (quarterly)",
        "Compensation Band Analysis (quarterly)",
        "Headcount Forecast (monthly)",
        "Exit Interview Summary (monthly)"
    };
}

Data Warehouse Architecture

• ETL pipeline: CDC from PostgreSQL → Kafka → Spark dbt transformations → Snowflake/BigQuery.
• BI tools: Embedded Metabase or Superset for self-service analytics.
• Export: CSV, Excel, PDF for all reports. Scheduled email delivery.
• Anonymization: Small team suppression to prevent individual identification.

17. Document Management

HR generates enormous volumes of documents requiring version control, e-signatures, retention policies, and secure access.

Document Categories

E-Signature Workflow

C#
public class DocumentSignatureRequest
{
    public Guid DocumentId { get; set; }
    public List<Signer> Signers { get; set; }
    public string SigningOrder { get; set; }
    public DateTime ExpirationDate { get; set; }
    public string CallbackUrl { get; set; }
}

public class Signer
{
    public string Name { get; set; }
    public string Email { get; set; }
    public string Role { get; set; }
    public SigningStatus Status { get; set; }
    public DateTime? SignedAt { get; set; }
    public string SignatureData { get; set; }
    public string IPAddress { get; set; }
}

18. Expense Management

Expense management handles submission, receipt capture, approval workflows, and reimbursement processing.

Expense Workflow

Policy Engine

C#
public class ExpensePolicy
{
    public Dictionary<string, decimal> CategoryLimits { get; set; }
    public decimal ReceiptRequiredThreshold { get; set; } = 25;

    public ExpenseValidationResult Validate(ExpenseLineItem item)
    {
        var violations = new List<PolicyViolation>();
        if (item.Amount > GetCategoryLimit(item.Category))
            violations.Add(new PolicyViolation("EXCEEDS_LIMIT"));
        if (item.Amount >= ReceiptRequiredThreshold && item.ReceiptUrl == null)
            violations.Add(new PolicyViolation("MISSING_RECEIPT"));
        if (item.Date > DateTime.UtcNow.AddDays(60))
            violations.Add(new PolicyViolation("LATE_SUBMISSION"));
        return new ExpenseValidationResult { IsValid = !violations.Any(v => v.Severity == "Hard") };
    }
}

Receipt Processing

• OCR extraction: Camera → OCR (Google Vision / Azure Form Recognizer) → extract merchant, date, amount.
• Per diem support: GSA per diem rates by location.
• Mileage tracking: Google Maps API for route-based calculation. IRS rate (67 cents/mile).
• Currency conversion: Real-time exchange rates with historical lookup.
• Duplicate detection: ML-based detection of duplicate receipts.

19. Org-Wide Announcements

The announcement system enables leadership to communicate company-wide, department-specific, or targeted messages.

Announcement Features

C#
public class Announcement
{
    public string Title { get; set; }
    public string Content { get; set; }
    public string Priority { get; set; }
    public TargetAudience Audience { get; set; }
    public DateTime? ScheduledAt { get; set; }
    public DateTime? ExpiresAt { get; set; }
    public bool RequiresAcknowledgment { get; set; }
    public List<string> DistributionChannels { get; set; }
}

20. Monitoring & Observability

HR platforms carry unique monitoring requirements. Payroll failures are P0 incidents. Data access anomalies may indicate insider threats.

Monitoring Stack

Critical Alerts

Audit Logging

C#
public class AuditLogEntry
{
    public string EntityType { get; set; }
    public Guid EntityId { get; set; }
    public string Action { get; set; }
    public string UserId { get; set; }
    public string IpAddress { get; set; }
    public Dictionary<string, object> OldValues { get; set; }
    public Dictionary<string, object> NewValues { get; set; }
    public DateTime Timestamp { get; set; }
    public bool IsSensitiveData { get; set; }
}

21. Security & Access Control

HR platforms are treasure troves for attackers: SSNs, salary data, bank account details, health information, and home addresses.

Authentication & SSO

C#
public class AuthenticationConfig
{
    public SsoConfig SSO { get; set; }
    public MfaPolicy Mfa { get; set; }
    public SessionConfig Sessions { get; set; }
    public PasswordPolicy Passwords { get; set; }
}

public class RoleBasedAccessControl
{
    public static readonly Dictionary<string, List<string>> RolePermissions = new()
    {
        ["Employee"] = new()
        {
            "profile:read:own", "profile:update:own:limited",
            "timeoff:request", "timeoff:read:own",
            "paystub:read:own", "timesheet:read:own:submit",
            "documents:read:own", "training:read:own:complete"
        },
        ["Manager"] = new()
        {
            "timeoff:approve:direct_reports",
            "timesheet:approve:direct_reports",
            "performance:review:direct_reports",
            "team:read:direct_reports"
        },
        ["HRAdmin"] = new()
        {
            "employee:read:all", "employee:create", "employee:update",
            "payroll:read:all", "payroll:process",
            "benefits:admin", "reports:read:all", "audit:read"
        },
        ["PayrollAdmin"] = new()
        {
            "payroll:read:all", "payroll:process", "payroll:approve",
            "tax:admin", "banking:admin"
        },
        ["SuperAdmin"] = new() { "*:*:*" }
    };
}

Data Encryption

Security Controls

• Data masking: SSN as ***-**-1234. Salary visible only to HR admin and employee.
• IP allowlisting: Optional IP whitelist for HR admin access.
• Session recording: Record HR admin sessions for sensitive operations.
• Penetration testing: Quarterly third-party pen tests. Bug bounty program.
• SOC 2 Type II: Annual audit with continuous monitoring.

22. Compliance & Regulatory

HR compliance is a multi-jurisdictional minefield. The platform must enforce rules from federal, state, local, and international regulations simultaneously.

Key Regulations

Compliance Automation

C#
public class ComplianceEngine
{
    public async Task<ComplianceCheckResult> RunComplianceChecks(Guid tenantId)
    {
        var results = new List<ComplianceCheck>();
        results.Add(await CheckFlsaCompliance(tenantId));
        results.Add(await CheckI9Compliance(tenantId));
        results.Add(await CheckOshaCompliance(tenantId));
        results.Add(await CheckAcaCompliance(tenantId));
        results.Add(await CheckPayEquity(tenantId));
        results.Add(await CheckLeaveAccruals(tenantId));
        results.Add(await CheckStateCompliance(tenantId));

        return new ComplianceCheckResult
        {
            Checks = results,
            OverallStatus = results.All(r => r.Status == ComplianceStatus.Compliant)
                ? ComplianceStatus.Compliant
                : ComplianceStatus.ActionRequired,
            CriticalFindings = results.Where(r => r.Severity == "Critical").ToList()
        };
    }
}

GDPR Compliance for HR

• Lawful basis: Employment contract (Art. 6(1)(b)) for most HR processing.
• Data minimization: Collect only what's necessary.
• Right to access: Employees can request all their data within 30 days.
• Right to erasure: Limited for HR data due to legal retention requirements.
• DPIA: Required for high-risk processing like performance monitoring.
• Cross-border transfers: Standard Contractual Clauses for EU→US transfers.

23. Database Design

Multi-Tenant Schema Strategy

SQL
CREATE SCHEMA tenant_acme;
CREATE SCHEMA tenant_globex;

ALTER TABLE employees ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON employees
    USING (tenant_id = current_setting('app.current_tenant')::uuid);

SET app.current_tenant = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

Core Schema

SQL
CREATE TABLE employees (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL,
    employee_number VARCHAR(20) NOT NULL,
    first_name VARCHAR(100) NOT NULL,
    last_name VARCHAR(100) NOT NULL,
    email VARCHAR(255) NOT NULL UNIQUE,
    status VARCHAR(20) NOT NULL DEFAULT 'Active',
    department_id UUID REFERENCES departments(id),
    manager_id UUID REFERENCES employees(id),
    hire_date DATE NOT NULL,
    termination_date DATE,
    employment_type VARCHAR(20) NOT NULL,
    org_path TEXT,
    org_depth INT DEFAULT 0,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE payroll_runs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL,
    pay_period_id UUID NOT NULL,
    status VARCHAR(20) NOT NULL,
    total_gross DECIMAL(12,2),
    total_net DECIMAL(12,2),
    idempotency_key VARCHAR(100) UNIQUE NOT NULL
);

CREATE TABLE paystubs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL,
    payroll_run_id UUID REFERENCES payroll_runs(id),
    employee_id UUID REFERENCES employees(id),
    gross_pay DECIMAL(12,2) NOT NULL,
    net_pay DECIMAL(12,2) NOT NULL,
    federal_tax DECIMAL(12,2),
    state_tax DECIMAL(12,2),
    social_security DECIMAL(12,2),
    medicare DECIMAL(12,2)
);

CREATE TABLE audit_log (
    id BIGSERIAL PRIMARY KEY,
    tenant_id UUID NOT NULL,
    entity_type VARCHAR(50) NOT NULL,
    entity_id UUID NOT NULL,
    action VARCHAR(20) NOT NULL,
    user_id UUID NOT NULL,
    old_values JSONB,
    new_values JSONB,
    is_sensitive BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE RULE no_update_audit AS ON UPDATE TO audit_log DO INSTEAD NOTHING;
CREATE RULE no_delete_audit AS ON DELETE TO audit_log DO INSTEAD NOTHING;

Indexing Strategy

24. API Design

REST API Overview

Text
Base URL: https://api.hrplatform.com/v1
Authentication: Bearer JWT (SSO IdP)
Tenant isolation: X-Tenant-Id header
Pagination: Cursor-based
Rate limits: 1000 req/min per tenant

GET    /employees                     List employees
GET    /employees/:id                 Get employee
POST   /employees                     Create employee
PATCH  /employees/:id                 Update employee
GET    /employees/:id/org-path        Get reporting chain
GET    /employees/search?q=           Full-text search

GET    /time-off/balances/:empId      Get leave balances
POST   /time-off/requests             Submit request
PATCH  /time-off/requests/:id/approve Approve
GET    /time-off/calendar             Team calendar

POST   /payroll/runs                  Initiate payroll
GET    /payroll/runs/:id              Get status
POST   /payroll/runs/:id/approve      Approve
POST   /payroll/runs/:id/submit-ach   Submit to bank

GET    /benefits/plans                List plans
POST   /benefits/enrollments          Enroll
POST   /benefits/life-events          Report life event

GET    /performance/cycles/:id/reviews/:empId  Get review
POST   /performance/cycles/:id/calibrate       Calibrate

GET    /analytics/headcount           Dashboard data
GET    /analytics/turnover            Metrics
GET    /analytics/diversity           DEI data

GraphQL Schema

GraphQL
type Employee {
    id: ID!
    fullName: String!
    email: String!
    department: Department!
    position: Position!
    manager: Employee
    directReports: [Employee!]!
    hireDate: Date!
    status: EmployeeStatus!
    leaveBalances: [LeaveBalance!]!
    currentReview: PerformanceReview
}

type Query {
    employee(id: ID!): Employee
    employees(filter: EmployeeFilter, pagination: PaginationInput): EmployeeConnection!
    teamCalendar(departmentId: ID!, startDate: Date!, endDate: Date!): [TimeOffEntry!]!
    orgChart(rootEmployeeId: ID, maxDepth: Int): OrgTreeNode!
}

input EmployeeFilter {
    departmentId: ID
    locationId: ID
    status: EmployeeStatus
    search: String
}

Webhook Events

25. Cost Estimation

Infrastructure Costs (10,000 Employee SaaS)

Third-Party Service Costs

Team Cost Estimate

26. Testing Strategy

HR platforms require exceptionally rigorous testing because errors directly impact employee paychecks, tax filings, and legal compliance.

Testing Pyramid

Payroll Test Scenarios

C#
public class PayrollCalculatorTests
{
    [Theory]
    [InlineData("CA", 45, 5, 0)]   // California daily OT
    [InlineData("NY", 45, 5, 0)]   // New York weekly only
    [InlineData("TX", 50, 10, 0)]  // Texas weekly only
    public void CalculateOvertime_MultiState(string state, decimal hours, decimal expectedOT, decimal expectedDT)
    {
        var employee = CreateEmployee(workState: state);
        var entries = CreateWeekEntries(totalHours: hours);
        var result = _calculator.CalculateOvertime(employee, entries);
        Assert.Equal(expectedOT, result.OvertimeHours);
    }

    [Fact]
    public void Paystub_NetPay_NeverNegative()
    {
        var employee = CreateEmployee(salary: 30_000m);
        var paystub = _payrollCalculator.CalculatePaystub(employee);
        Assert.True(paystub.NetPay >= 0, "Net pay should never be negative");
    }

    [Fact]
    public void PayrollRun_Idempotent_SameResultOnRetry()
    {
        var run = CreatePayrollRun();
        var result1 = _payrollService.ExecutePayroll(run.Id);
        var result2 = _payrollService.ExecutePayroll(run.Id);
        Assert.Equal(result1.TotalNet, result2.TotalNet);
    }
}

Test Categories

27. Interview Q&A

A: The payroll system uses a pipeline architecture with idempotent stages. Each employee's pay calculation is independent and parallelized. The pipeline: (1) collect time data, (2) calculate earnings, (3) calculate deductions, (4) calculate taxes via a state-specific rule engine, (5) generate paystub, (6) aggregate for ACH file. Each stage is a Kafka consumer processing employees in batches of 100. The state-specific tax engine loads rules from a configuration store, using a strategy pattern where each state implements ITaxCalculator. New states are added by implementing the interface. The entire run is wrapped in a saga with compensation for rollback. Idempotency is enforced through a unique constraint on (RunId, PayPeriodId).

A: We use the saga pattern with compensation. Termination: (1) Core HR updates status in a transaction, (2) publishes EmployeeTerminatedEvent via the outbox pattern, (3) Payroll service finalizes current pay run and calculates PTO payout, (4) Benefits service initiates COBRA, (5) Document service archives personnel file, (6) Access service revokes all system access. If any step fails, the saga compensates — e.g., if benefits COBRA fails, we retry rather than rolling back the termination. The termination itself is the only step that must be committed; downstream services must be eventually consistent.

A: Three layers: (1) Schema-per-tenant for strong logical isolation — each tenant gets its own PostgreSQL schema, (2) Row-Level Security as defense-in-depth — even if application code has a bug, the database layer enforces tenant boundaries, (3) Application-level tenant context set per-request from the JWT token and propagated through all service calls via HTTP headers and Kafka message headers. We test isolation with dedicated integration tests that attempt cross-tenant data access.

A: We build a migration toolkit: (1) BambooHR API connector pulls all employee data, time-off history, and documents, (2) Data transformation layer maps BambooHR fields to our schema, handling field mismatches and enrichment, (3) Validation engine runs compliance checks on migrated data, (4) Dry-run mode lets the customer preview everything before committing, (5) Delta sync during the transition period keeps both systems in sync until go-live. Typical migration for 1,000 employees takes 2-4 weeks including validation and UAT.

A: Payroll calculations use UTC internally and only convert to local time for display. Pay periods are defined by calendar dates (not hours), so DST transitions don't affect period boundaries. Time entries store local date + local clock-in/out times, and the overtime calculator converts to total duration in decimal hours regardless of DST. We have explicit test cases for the "spring forward" and "fall back" weekends to ensure no double-counting or gaps.

A: The notification service is a standalone microservice consuming from Kafka. Events are categorized by priority: P0 (payroll failure — page via PagerDuty), P1 (approval pending — push notification + email), P2 (training reminder — email + in-app). Each tenant configures their notification preferences (which channels, quiet hours, digest frequency). The service maintains a notification queue per user with deduplication (no more than one approval reminder per hour). Templates are stored as Handlebars templates with tenant-specific branding. Delivery is retried with exponential backoff, and failed deliveries are logged for manual follow-up.

A: We model benefits eligibility as a rule engine with composable predicates. Each benefits plan has an eligibility configuration specifying which employment types, departments, locations, and tenure thresholds qualify. For state-specific rules (like California's mandated paid family leave or New York's disability insurance), we maintain a regulatory ruleset that overlays federal defaults. The rules engine evaluates eligibility at enrollment time and re-evaluates on life events. When a regulation changes, we update the ruleset configuration — not application code — allowing compliance updates without redeployment. The system also tracks which employees are affected by a rule change and generates proactive notifications.

A: A phased migration approach over 8-12 weeks. Phase 1 (Weeks 1-2): Extract data from the source system via API or flat file export. Map field schemas, identify data quality issues, and generate a migration report. Phase 2 (Weeks 3-4): Transform and cleanse data — normalize department structures, reconcile salary bands, align leave policies. Run data validation rules to flag anomalies. Phase 3 (Weeks 5-6): Load into staging environment with full tenant isolation. Customer runs parallel operations on both systems for one pay period. Phase 4 (Week 7): Validate payroll reconciliation — every employee's pay stub must match between old and new systems. Phase 5 (Week 8): Go-live cutover with real-time delta sync for any remaining transitions. Post-migration support for 30 days including a dedicated Slack channel with the engineering team.

A: Multiple layers of defense: (1) Separation of duties — the person who initiates a payroll run cannot approve it; two-person authorization required, (2) Anomaly detection — automated alerts when any employee's pay changes by more than 15% without a documented compensation event, (3) Ghost employee detection — cross-reference active employee count with badge access and network login data, (4) Payroll run comparison — compare each run against the previous run and flag any unexplained changes, (5) Bank account change monitoring — flag and require re-verification when an employee's bank details change within 48 hours of a payroll run, (6) Audit logging — every payroll action is logged with the acting user's identity, IP address, and timestamp. Monthly reconciliation reports are generated automatically and sent to the CFO.

A: Feature flags and tiered service plans. The core data model and services are the same for all tenants. Differences are handled through: (1) Feature flags — smaller tenants get simplified views (no org chart drag-and-drop, no calibration workflow), (2) Tenant configuration — accrual rules, approval chains, and notification preferences are configurable per-tenant rather than hard-coded, (3) Performance tiering — small tenants share a database pool; enterprise tenants get dedicated read replicas, (4) Onboarding templates — startups use a simple 5-step onboarding; enterprises use the full multi-phase workflow with custom tasks. The key principle is that the codebase is always the same; only configuration and resource allocation differ. This avoids the "two products" trap that plagues many SaaS companies.

A: During normal operations, pay stubs are generated as part of the batch payroll run — this is the reliable, auditable path. However, we also support real-time on-demand generation for two scenarios: (1) Employee self-service "what-if" calculator — shows estimated next paycheck based on current elections and hours, useful during benefits open enrollment, (2) Off-cycle payment requests — a manager can request an off-cycle payment (e.g., commission payout) that generates a pay stub immediately. Both paths use the same PayrollCalculator class, ensuring consistency. The on-demand path writes to a shadow table marked as "preview" and doesn't trigger bank submissions. Only the batch payroll run produces official, filed pay stubs.

A: For an initial US-focused platform expanding internationally, we use a hub-and-spoke model. The core platform handles US payroll natively. For other countries, we integrate with local payroll providers via API (e.g., Papaya Global, Remote.com, or local providers like Xero for UK). The integration layer normalizes data between our internal model and the local provider's format. Each country gets a "payroll adapter" that handles local tax calculations, statutory deductions, and filing requirements. Employee data flows from our Core HR service to the local payroll provider; pay results flow back for reporting and analytics. This lets us support 30+ countries without building local payroll expertise in-house.

28. Glossary & Key Terminology

HR technology is a domain dense with acronyms and specialized terminology. This glossary covers the most important terms encountered when designing and building an HR platform, organized by domain.

Employment & HR General

Payroll & Compensation

Benefits & Insurance

Performance & Development

Compliance & Data Privacy

Technology & Architecture

29. Conclusion

Building an HR and People Management Platform is one of the most complex SaaS endeavors. It requires deep domain expertise across payroll, benefits, compliance, and employment law — areas where bugs don't just cause downtime, they cause employees to receive incorrect paychecks, companies to face regulatory penalties, and organizations to lose the trust of their workforce.

The key architectural takeaways are:

1. Start with the employee as the central entity. Every module connects back to the employee record. Get this data model right and the rest follows.
2. Design for compliance from day one. Retroactive compliance is exponentially harder than building it in. Audit logging, retention policies, and data isolation are non-negotiable foundations.
3. Payroll must be treated as a financial system. Idempotency, reconciliation, audit trails, and failure recovery are not optional features — they are requirements.
4. Event-driven architecture for lifecycle cascades. A single employee action (termination, transfer, promotion) touches 10+ services. Async events with the outbox pattern ensure consistency without tight coupling.
5. Multi-tenancy with strong isolation. Schema-per-tenant plus row-level security provides defense-in-depth. Never rely on application code alone for tenant boundaries.
6. Invest in testing infrastructure. Payroll calculation tests, compliance rule tests, and migration validation tests are worth their weight in gold. A single miscalculation can cascade to thousands of employees.

The HR tech market continues to grow as companies recognize that people operations are strategic, not administrative. The platforms that win will be those that combine deep compliance expertise with modern developer experience, beautiful employee-facing design, and the reliability that payroll and benefits demand.