Leave Types Catalog
Relevant source files
The following files were used as context for generating this wiki page:
- packages/api/Modules/LeaveTypes/LeaveTypeService.cs
- packages/web/src/features/leave-types/leave-types.server.ts
- packages/api/Modules/LeaveTypes/LeaveType.cs
- packages/api/Modules/LeaveTypes/LeaveTypeEndpoints.cs
- packages/api/Modules/LeaveTypes/LeaveTypeContracts.cs
- packages/api/Modules/LeaveTypes/LeaveTypesModule.cs
- packages/web/src/api/schema.ts
Introduction
The Leave Types Catalog is a core module within the TSZ system responsible for defining and managing different categories of time off (e.g., Holiday, Sickness, ADV). It serves as the template for user-specific leave allowances, establishing default values such as the number of days allowed and whether the leave is "Limited" or "Unlimited."
This system ensures that leave policies are consistent across the organization while providing the flexibility to archive obsolete types without losing historical data. It integrates directly with the User module to auto-populate leave allowances for new employees based on currently active leave types.
Sources: packages/api/Modules/LeaveTypes/LeaveTypeService.cs, packages/api.tests/Users/UserLeaveAllowanceServiceTests.cs:51-60
Data Architecture
Leave Type Model
The system uses a centralized LeaveType entity to store configuration data. Key attributes include the name, default days, and an AllowanceMode which dictates how the balance is calculated for users.
The diagram shows the structure of a Leave Type entity and its relationship with the Allowance Mode enumeration.
Sources: packages/api/Modules/LeaveTypes/LeaveType.cs:5-13, packages/web/src/api/schema.ts:696-697
Entity Fields
| Field | Type | Description |
|---|---|---|
Id | Guid | Unique identifier for the leave type. |
Name | String | Unique name of the leave type (case-insensitive). |
DefaultDays | Decimal | The standard number of days awarded to users (Max 1 decimal place). |
DefaultMode | Enum | Determines if the leave is Limited (capped) or Unlimited. |
IsArchived | Boolean | Flag to hide the leave type from active selection lists. |
Sources: packages/api/Modules/LeaveTypes/LeaveTypeContracts.cs:20-31, packages/api/Migrations/AppDb/20260517143608_AddLeaveTypes.Designer.cs:175-195
Backend Logic and API
Leave Type Service
The LeaveTypeService encapsulates the business logic for managing leave types, including validation for duplicate names and handling pagination for the administrative interface.
The flow represents the creation logic within the service layer.
Sources: packages/api/Modules/LeaveTypes/LeaveTypeService.cs:38-57
API Endpoints
All leave type operations are grouped under the /api/leave-types prefix.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/leave-types | Returns a paged list of leave types. Supports search and sort. |
| GET | /api/leave-types/{id} | Retrieves details for a specific leave type. |
| POST | /api/leave-types | Creates a new leave type. Returns 409 if name exists. |
| PUT | /api/leave-types/{id} | Updates an existing leave type. |
| PATCH | /api/leave-types/{id}/archive | Sets IsArchived to true. |
| PATCH | /api/leave-types/{id}/unarchive | Sets IsArchived to false. |
Sources: packages/api/Modules/LeaveTypes/LeaveTypeEndpoints.cs:12-96, packages/web/src/features/leave-types/leave-types.server.ts:16-43
Frontend Implementation
State Management and Functions
The web application uses TanStack Start server functions to bridge the UI with the API. These functions handle input validation via Zod schemas and error mapping (e.g., converting 409 status codes to user-friendly error messages).
This diagram illustrates the data flow from the UI to the backend API via server functions.
Sources: packages/web/src/features/leave-types/leave-types.functions.ts:13-26, packages/web/src/routes/_authed/admin/leave-types/index.tsx:28-35
User Interface Components
- LeaveTypeList: An administrative table that supports sorting by name or default days, searching by name, and toggling the visibility of archived items.
- LeaveTypeForm: A shared form for creating and editing types, utilizing
@tanstack/react-formfor validation. It enforces specific constraints such as a maximum of 365 days and a single decimal place for day increments.
Sources: packages/web/src/routes/_authed/admin/leave-types/index.tsx:68-150, packages/web/src/routes/_authed/admin/leave-types/-components/form.tsx:32-90
Integration with User Allowances
When a new user is created, the system iterates through all non-archived leave types in the catalog and generates a UserLeaveAllowance for each. This ensures every employee starts with the organization's standard leave set.
The diagram shows how the Leave Types Catalog acts as a template for user allowances.
Sources: packages/api.tests/Users/UserLeaveAllowanceServiceTests.cs:51-70
Conclusion
The Leave Types Catalog provides a structured foundation for time-off management in the TSZ application. By separating the definition of leave categories from individual user balances, it allows administrators to maintain global policies that are automatically applied to the workforce while providing necessary tools for lifecycle management like archiving and auditing.