Leave Module Lifecycle

​
Overview

The Leave Management module handles the end-to-end lifecycle of employee leave requests, from submission to approval and balance tracking. It integrates with the Better Auth identity system to enforce organization-level permissions and roles.

​
Core Features

  • Leave Requests: Create, view, and track leave requests (Annual, Sick, Emergency, etc.).
  • Leave Balance Tracking: Real-time balance calculations and usage tracking.
  • Approval Workflow: Multi-tier approval system based on organization roles and management relationships.
  • Team Impact Analysis: Visual indicators for team coverage when reviewing requests.
  • Audit Logging: Traceability for all status changes and approvals.

​
🔄 Approval Workflow

The approval workflow is the core of the leave module, ensuring requests are reviewed by authorized personnel.

​
Workflow States

  1. PENDING: Request submitted and awaiting review.
  2. APPROVED: Request granted; leave balance is automatically deducted.
  3. REJECTED: Request denied; reason provided to the employee.

​
Authorization Rules

Authorization is handled via the PermissionService, which queries Better Auth’s members table for roles and permissions.
RolePermissionsApproval Capabilities
Ownerleave:approve, leave:*Can approve any request in the organization.
Adminleave:approve, leave:*Can approve any request in the organization.
Staffleave:requestCannot approve requests (unless they are a manager).
Memberleave:requestCannot approve requests.

​
Approval Logic (CanApproveLeaveFor)

To approve or reject a request, the following conditions must be met:
  1. Org Membership: Both the approver and the requestor must be active members of the same organization.
  2. Permission Check: The approver must possess the leave:approve permission string.
  3. Role Hierarchy:
    • Owners and Admins can approve requests for any member of the organization.
    • Non-Admin Approvers (if granted leave:approve) can only approve requests for employees where they are explicitly set as the manager_id.

​
Balance Deduction

Leave balance deduction happens atomically upon approval. If the deduction fails (e.g., due to insufficient remaining days during concurrent approvals), the request status is rolled back to PENDING.

​
📊 Team Impact & Coverage

When an approver reviews a request, the system provides a Team Impact assessment:
  • Overlapping Leaves: Number of other team members (same department) on leave during the requested dates.
  • Coverage Percentage: Percentage of active team members remaining.
  • Low Coverage Alert: Triggered if coverage falls below 70%.

​
🛡 Security & Audit

  • Read-Only Identity: User roles are fetched directly from Better Auth tables to ensure consistency with the Bun backend.
  • Transactional Safety: Balance updates use database transactions to prevent double-spending of leave days.
  • Audit Logs: Every approval action records the approver_id, timestamp, and comment.
  • internal/modules/leave/application/usecase/approval_service.go — Approval logic implementation
  • internal/modules/organizations/application/usecase/permission_service.go — Authorization engine
  • docs/backend/go/guides/permission-service-integration.md — Integration guide