Payroll
Payroll Management for Instructor Networks
Salary Engine · Period Locking · Dispute System · Worker Portal
Internal Z-AGENCY payroll system for managing compensation of a distributed instructor network. Automated salary calculation, period management, dispute resolution, and worker self-service portal.
Why We Built This
The Problem
Z-AGENCY manages a network of instructors across multiple programs and locations. Calculating compensation is complex -- base salary, role surcharges, distance bonuses, transport costs, day-before premiums. Monthly payroll was a manual spreadsheet exercise prone to errors, disputes, and missed deadlines.
The Solution
We built a dedicated payroll system that automates the entire compensation pipeline. Events are logged with instructor assignments, the calculation engine applies all rate rules automatically, and monthly periods go through a structured review-lock cycle. Instructors access their own portal to view salary breakdowns and file disputes.
What Is Payroll?
A complete payroll management system with multi-factor compensation calculation (base + role + distance + transport surcharges), monthly salary period management with a 10-step atomic lock process, an instructor self-service portal, dispute management with threaded messaging, Excel export, and comprehensive audit logging. Integrates with Tabidoo for real-time instructor data synchronization.
Compensation Engine
Multi-factor salary calculation: base rate, role surcharges, distance, transport, and day-before premiums.
Period Management
10-step atomic lock process with snapshots, transfer propagation, and rate version locking.
Dispute System
Instructor-initiated disputes with threaded messaging, attachments, and admin resolution workflow.
Worker Portal
Self-service salary viewing, event breakdown details, and dispute filing for instructors.
Feature Showcase
Key capabilities of Payroll.
Compensation Calculation
Multi-factor rate engine handling base salary, role surcharges (senior, manager, prep manager), distance bonuses, transport compensation (company car or per-km reimbursement), and day-before premiums. Pure function architecture for consistency.
- Role-based rate calculation with surcharges
- Transport: company car (short/long) + own car (per-km)
- Manual adjustments via special amounts
- Multiple rate versions with date ranges
Salary Period Management
Monthly salary periods with draft/review/locked states. A 10-step atomic lock process ensures data integrity: validation, snapshot creation, transfer propagation, rate version locking, and worker email notification.
- Draft, review, and locked period states
- Immutable salary snapshots per instructor
- Transfer-to-next carry-forward system
- Unlock and reset-to-draft for corrections
Disputes & Communication
Instructors can challenge event assignments or calculations through a structured dispute system with threaded messaging, file attachments, and status tracking from open to resolved.
- Instructor-initiated dispute filing
- Threaded messages with attachments
- Admin review and resolution workflow
- Real-time notifications for activity
Reporting & Export
Excel export for payroll distribution, Google Drive integration for archival, historical salary snapshots with full event and rate breakdowns, and comprehensive audit logging.
- XLSX export for salary distribution
- Google Drive backup and sharing
- Full audit trail with before/after data
- Historical snapshots for compliance
Project Scope & Architecture
The building blocks of Payroll.
Admin Dashboard
Next.js App Router with role-based navigation for superadmins and salespersons.
Worker Portal
Read-only salary viewing, event breakdowns, and dispute filing for instructors.
Backend
Supabase (PostgreSQL) with 16 normalized tables and Row-Level Security.
Integrations
Tabidoo API for instructor sync, n8n for automation, Google Drive for exports.
Tech Stack
The technologies powering Payroll.
In Numbers
Real metrics from this project -- no inflated counts.
3
User roles (superadmin, salesperson, worker)
16
Database tables
10-step
Atomic lock process
35+
API endpoints
This is an internal Z-AGENCY application and is not publicly accessible.
Interested in something similar?
We are always open to exploring new ideas. Whether it is a similar platform or something entirely different -- let's have a conversation.