Case Study: Candy Tree English School — HR & Payroll Management System

Project Code: candy
Category: Human Resources Management System (HRMS) / Payroll Automation
Status: Active Development (Port 8010)
Industry: Private Education / English Language Schools

1. Project Name

Candy Tree HRMS — A fully integrated human resources management system purpose-built for a private English language school in Taiwan, covering payroll, attendance, leave management, and course scheduling.

2. Core Technology Stack

Custom Apps Built:
cores (base models & mixins) · hr (employee records) · attendance (clock-in/out) · leave (leave application & approval) · payroll (salary calculation engine) · course (lesson scheduling, teacher assignments) · tax_insurance (labour & health insurance, income tax withholding) · staff · hr_reports (monthly reporting) · front (employee self-service portal) · share · utils

Reusable Core Mixins:
UserUpdateModel · ActiveModel (soft delete) · StateTrackingModel · CodeNO (auto-numbering) · FileProcessingMixin · ModelChangeHistoryMixin

3. The Challenge (The Problem)

A private English school with mixed staffing — full-time administrative staff and part-time teachers with varied hourly contracts — faces a payroll complexity that generic off-the-shelf software cannot cleanly handle:

1. Heterogeneous pay structures: Full-time monthly salaries, part-time per-lesson pay rates, supplementary allowances (meal/transport), and class-based bonuses all need to coexist in one calculation engine.
2. Manual payroll risk: Without automation, monthly payroll calculation requires HR staff to cross-reference attendance records, teaching schedules, leave records, and statutory deduction tables — a process prone to human error and consuming 2–3 days per payroll cycle.
3. Regulatory compliance burden: Taiwan's Labour Standards Act mandates specific rules for overtime pay tiers, paid sick leave, and annual leave accrual. Non-compliance exposes the employer to fines and litigation.
4. Scattered records: Attendance punch data, leave approvals, and course scheduling lived in separate tools (spreadsheets, paper forms, LINE messages) with no single source of truth.

4. The Solution (The Implementation)

Feature 1: Unified Payroll Calculation Engine

The payroll app calculates each employee's net pay from first principles every month: base salary + allowances + overtime pay (computed from attendance app data) − labour insurance (employee share) − health insurance − income tax pre-withholding. The calculation is driven by the tax_insurance app, which maintains the statutory fee rate tables and ensures they can be updated annually without code changes. Every calculation line item is stored with a created_by audit stamp and is immutable once HR confirms the payroll run.

Feature 2: Leave Management with Real-Time Balance Tracking

The leave app implements a multi-step approval workflow: employee submits request → immediate manager/HR receives notification → approval/rejection with mandatory reason → balance auto-deducted. The system enforces minimum staffing levels per department, alerting the approver when a requested leave date would leave the team below the contractual headcount minimum.

Feature 3: Course-Linked Teacher Attendance

Unlike generic HR systems, the course app links each teacher's scheduled lessons to their attendance record. A teacher who has lessons scheduled on a given day but no clock-in triggers an immediate flag. This integration eliminates the scenario where absent teachers are paid for classes that did not run.

Feature 4: Employee Self-Service Portal

The front app provides a mobile-first portal where employees can view their own payslip (PDF download), check remaining leave balances, submit leave requests, and see their teaching schedule — without calling HR. Every payslip line item has a tooltip explaining the calculation basis, pre-empting the most common payroll queries.

Feature 5: Batch Reporting & PDF Generation

The hr_reports app generates monthly statutory reports — attendance summaries, payroll totals, labour/health insurance contribution schedules — as both Excel (for internal bookkeeping) and PDF (for government submission). Batch generation of all employee payslips (with each employee's unique figures) is a single button operation via xhtml2pdf.

5. Business Impact (The Result)

• Payroll cycle time reduction: Monthly payroll processing (previously 2–3 days of manual spreadsheet work) is reduced to a same-day confirmation workflow. HR verifies flagged anomalies rather than performing all calculations manually.
• Eliminated compliance risk: Overtime tiers, annual leave accrual, and statutory deduction rates are enforced by code rather than by memory — removing the most common source of Labour Standards Act violations in SMEs.
• Eliminated teacher payroll disputes: Course-attendance integration ensures teachers are paid for classes actually delivered; the audit trail resolves any disputes with timestamps and manager sign-off records.
• Staff satisfaction: Employees with 24/7 self-service access to payslips and leave balances report fewer queries to HR and greater transparency confidence.
• [Needs Manual Input]: Number of employees, monthly payroll volume, specific hours saved per pay cycle.

6. AI / Innovation Factor

• AI-Assisted UX Specification: The full employee self-service portal and all backend custom page flows (payroll confirmation, attendance dashboard, leave approval, monthly reports) have pre-implementation UX Spec documents — including user journey maps, use cases, interaction specs, and acceptance criteria — produced with Claude AI assistance.
• Automated Anomaly Flagging: The payroll confirmation page automatically highlights employees whose overtime pay or net salary deviates >20% from the previous month, directing HR attention to exceptions rather than requiring line-by-line review.
• Scalable Mixin Architecture: The cores app provides a library of reusable abstract base classes (StateTrackingModel, ModelChangeHistoryMixin) that enforce audit logging and workflow governance across every module, building compliance tracking into the data model rather than treating it as an afterthought.
• [Needs Manual Input]: Any planned AI-driven scheduling optimisation or predictive headcount reporting.

Document generated: 2026-05-03 | Maintained by Tom Lai / You Er Ta Mu She Ji