# XTask-Web Application Documentation
## Overview
XTask-Web is a Django-based workforce management platform inspired by Deputy. It provides tools for managing businesses, locations, employees, scheduling, attendance, payroll, leave, compliance, and more. The system is organized into multiple Django apps under the `apps/` directory.
### Tenant / Location Model
The project follows a Deputy-style hierarchy:
- `Organization` represents a business/company account.
- `BusinessLocation` represents an operational site, branch, store, or workplace for that business.
- Operational records are location-scoped through `business_location`.
- The business for any operational record is available through `record.business_location.business`.
This means attendance, schedules, availability, payroll, leave, documents, compliance, benefits, roles, tasks, timesheets, training, and performance records belong to a `BusinessLocation`, not directly to an `Organization`.
---
## Swagger / OpenAPI (drf-spectacular)
The backend exposes an OpenAPI schema and interactive documentation for all DRF endpoints registered under `core/urls.py`.
- OpenAPI JSON schema: `GET /api/schema/`
- Swagger UI: `GET /api/docs/`
- ReDoc UI: `GET /api/redoc/`
> Note: Swagger requires `drf-spectacular` to be installed in the active environment.
---
## Table of Contents
1. [Authentication](#authentication)
2. [Users](#users)
3. [Organization](#organization)
4. [Business Locations](#business-locations)
5. [Roles & Permissions](#roles--permissions)
6. [Attendance](#attendance)
7. [Scheduling](#scheduling)
8. [Timesheets](#timesheets)
9. [Leave](#leave)
10. [Payroll](#payroll)
11. [Benefits](#benefits)
12. [Performance](#performance)
13. [Training](#training)
14. [Notifications](#notifications)
15. [Reports](#reports)
16. [Dashboard](#dashboard)
17. [Files](#files)
18. [Documents](#documents)
19. [Compliance](#compliance)
20. [Availability](#availability)
21. [Integrations](#integrations)
22. [Settings](#settings)
23. [Activity Logs](#activity-logs)
24. [Audit Logs](#audit-logs)
---
## Authentication
**Path:** `apps/authentication/`
**Purpose:** Handles user registration, login, logout, and JWT token management.
### Models
- No dedicated models (uses Django's built-in User model from `apps.users`)
### API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/auth/register/` | POST | Register a new user |
| `/auth/login/` | POST | Login and receive JWT tokens |
| `/auth/logout/` | POST | Logout and blacklist refresh token |
| `/auth/refresh/` | POST | Refresh access token |
### Serializers
- `RegisterSerializer` - Handles user registration with password confirmation
- `LoginSerializer` - Validates email and password for login
### Usage in Deputy
- Equivalent to Deputy's authentication system
- JWT-based auth replaces session-based auth for API-first architecture
---
## Users
**Path:** `apps/users/`
**Purpose:** User management with role-based access control and profile management.
### Models
- `User` - Custom user model with email as username, profile fields, ABN, TFN, emergency contacts, bank details, and status tracking
### API Endpoints
- Full CRUD via UserViewSet (`/users/`)
### Serializers
- `UserSerializer` - Main user serializer with FK expansion support
- `UserProfileSerializer` - Profile-specific fields
### Services
- `UserService` - `get_user_with_data()`, `get_branch_with_data()`, `get_department_with_data()`
### Usage in Deputy
- Core employee management
- Stores personal info, contact details, bank info for payroll
- Status tracking (active, inactive, terminated)
---
## Organization
**Path:** `apps/organization/`
**Purpose:** Business/company account management, plus location-scoped departments and teams.
### Models
- `Organization` - Business/company account with default address, industry, size, timezone, and manager
- `Department` - Business-location units with hierarchical structure (parent/child)
- `Team` - Cross-functional groups within departments
- `TeamMember` - Many-to-many relationship between users and teams
### API Endpoints
| Endpoint | Description |
|----------|-------------|
| `/organizations/` | CRUD for organizations |
| `/organizations/departments/` | CRUD for departments |
| `/organizations/teams/` | CRUD for teams |
| `/organizations/team-members/` | CRUD for team memberships |
### Serializers
- `OrganizationSerializer` - With `get_organization` expansion
- `DepartmentSerializer` - With `get_department` expansion
- `TeamSerializer` - With `get_team` expansion
- `TeamMemberSerializer` - Team membership with user/team expansion
### Services
- `OrganizationService` - `get_organization_with_data()`, `get_branch_with_data()`, `get_department_with_data()`
### Usage in Deputy
- Organization structure management
- Business account ownership
- Department/team structure within locations
- Department/team-based reporting
---
## Business Locations
**Path:** `apps/business_locations/`
**Purpose:** Physical or operational locations for a business. Each location has its own timezone, address, opening hours, and active status.
### Models
- `BusinessLocation` - Site/store/branch linked to an `Organization` through `business`
### API Endpoints
| Endpoint | Description |
|----------|-------------|
| `/business-locations/locations/` | CRUD for business locations |
| `/business-locations/locations/?business_id=<uuid>` | Filter locations by business |
### Serializers
- `BusinessLocationSerializer` - Exposes `business_id`, optional `business` expansion, address, geo, timezone, and hours
### Services
- `BusinessLocationService` - `get_business_location_with_data()`
- `get_user_business_locations()` - Locations available to the current user
- `get_user_default_business_location()` - Default location for create/clock-in flows
- `user_can_access_business_location()` - Permission helper for location-scoped data
### Usage in Deputy
- Location/store/site management
- Per-location timezone support for clock-in/out and shift dates
- Scope boundary for most workforce operations
---
## Roles & Permissions
**Path:** `apps/roles_permissions/`
**Purpose:** Role-based access control (RBAC) with custom permissions.
### Models
- `Role` - Named roles with ManyToMany permissions
- `Permission` - Individual permissions with codenames
- `UserRole` - Assignment of roles to users within business locations
### API Endpoints
- Full CRUD via ViewSets for roles, permissions, and user roles
### Serializers
- `PermissionSerializer` - Permission fields
- `RoleSerializer` - With permissions and `permission_ids` write support
- `UserRoleSerializer` - With user/role/business_location expansion
### Services
- `RoleService` - `get_role_with_data()`
- `PermissionService` - `get_permission_with_data()`
- `UserRoleService` - `get_user_role_with_data()`
### Usage in Deputy
- Manager vs Employee roles
- Custom permission sets for different job functions
- Location-scoped role assignments
---
## Attendance
**Path:** `apps/attendance/`
**Purpose:** Time tracking, attendance records, GPS clock-in/out, and approval workflows.
### Models
- `Attendance` - Daily attendance with clock in/out, GPS coordinates, status
- `BreakRecord` - Break tracking during shifts
- `TimeCorrection` - Manual time correction requests with approval
- `AttendanceApproval` - Multi-level approval workflow
### API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/attendance/` | CRUD | Attendance records |
| `/attendance/clock-in/` | POST | Clock in with location |
| `/attendance/clock-out/` | POST | Clock out with location |
| `/attendance/today/` | GET | Get today's attendance |
### Serializers
- `AttendanceSerializer` - With user/business_location expansion
- `ClockInSerializer` / `ClockOutSerializer` - Action serializers
### Services
- `AttendanceService` - `get_attendance_with_data()`
### Usage in Deputy
- GPS-based clock in/out by business location
- Attendance status tracking (present, absent, late, remote)
- Time correction approvals
- Break tracking
---
## Scheduling
**Path:** `apps/scheduling/`
**Purpose:** Shift scheduling, assignments, and recurring shift patterns.
### Models
- `ShiftTemplate` - Reusable shift templates
- `Shift` - Scheduled shifts with start/end times, locations
- `ShiftAssignment` - Employee assignments to shifts
- `ShiftSwapRequest` - Employee-initiated shift swaps with approval
- `RecurringShift` - Recurring shift patterns
### API Endpoints
| Endpoint | Description |
|----------|-------------|
| `/scheduling/` | CRUD for shifts |
| `/scheduling/templates/` | Shift templates |
| `/scheduling/assignments/` | Shift assignments |
| `/scheduling/swap-requests/` | Swap requests |
| `/scheduling/recurring/` | Recurring shifts |
### Serializers
- `ShiftSerializer` - With business_location/user expansion
- `ShiftTemplateSerializer`
- `ShiftAssignmentSerializer`
- `ShiftSwapRequestSerializer`
- `RecurringShiftSerializer`
### Services
- `SchedulingService` - `get_schedule_with_data()`
### Usage in Deputy
- Weekly/monthly roster creation
- Shift swap requests between employees
- Recurring shift patterns for regular staff
- Location-based scheduling
---
## Timesheets
**Path:** `apps/timesheets/`
**Purpose:** Timesheet submission, approval, and status tracking.
### Models
- `Timesheet` - Weekly timesheet with total hours, status, and approval workflow
### API Endpoints
| Endpoint | Description |
|----------|-------------|
| `/timesheets/` | CRUD for timesheets |
### Serializers
- `TimesheetSerializer` - With user/business_location expansion
### Services
- `TimesheetService` - `get_timesheet_with_data()`
### Usage in Deputy
- Weekly timesheet submission
- Manager approval workflow
- Integration with payroll calculations
---
## Leave
**Path:** `apps/leave/`
**Purpose:** Leave management with balances, policies, and approval workflows.
### Models
- `LeaveType` - Configurable leave types (annual, sick, etc.)
- `LeaveBalance` - Per-employee, per-year balance tracking
- `Leave` - Leave requests with approval workflow
- `LeaveAdjustment` - Manual balance adjustments
- `LeavePolicy` - Business-location-specific leave policies
- `PublicHoliday` - Public holiday calendar
### API Endpoints
| Endpoint | Description |
|----------|-------------|
| `/leaves/` | CRUD for leave requests |
| `/leaves/types/` | Leave types |
| `/leaves/<id>/approve/` | Approve leave |
| `/leaves/<id>/reject/` | Reject leave |
### Serializers
- `LeaveTypeSerializer` - With business_location expansion
- `LeaveSerializer` - With user/leave_type/approved_by expansion
### Services
- `LeaveTypeService` - `get_leave_type_with_data()`
- `LeaveService` - `get_leave_with_data()`
### Usage in Deputy
- Leave requests and approvals
- Balance tracking (allocated, used, pending, remaining)
- Public holiday management
- Leave policy configuration
---
## Payroll
**Path:** `apps/payroll/`
**Purpose:** Australian payroll management with tax and superannuation handling.
### Models
- `SuperannuationFund` - Third-party super funds with USI
- `PayRate` - Employee pay rates with super contribution details
- `PayrollDeduction` - Deduction types (tax, super, child support)
- `Payroll` - Pay run calculations with hours, overtime, allowances
- `PayAdjustment` - One-off adjustments (bonus, back pay)
- `Payslip` - Generated payslip records
### API Endpoints
| Endpoint | Description |
|----------|-------------|
| `/payroll/` | CRUD for payroll records |
| `/payroll/pay-rates/` | Pay rate configuration |
| `/payroll/<id>/calculate/` | Calculate payroll |
### Serializers
- `PayRateSerializer` - With business_location/user/super_fund expansion
- `PayrollSerializer` - With business_location/user expansion
### Services
- `PayRateService` - `get_pay_rate_with_data()`
- `PayrollService` - `get_payroll_with_data()`
- `PayAdjustmentService` - `get_pay_adjustment_with_data()`
- `PayslipService` - `get_payslip_with_data()`
### Usage in Deputy
- Australian payroll compliance
- Superannuation tracking
- Tax withholding calculations
- Payslip generation
---
## Benefits
**Path:** `apps/benefits/`
**Purpose:** Employee benefits, plans, and enrollment management.
### Models
- `BenefitType` - Categories (health, retirement, insurance)
- `BenefitPlan` - Business-location-specific plans with costs
- `EmployeeBenefit` - Employee enrollments
- `BenefitDeduction` - Payroll deduction tracking for benefits
### Serializers
- `BenefitTypeSerializer`
- `BenefitPlanSerializer` - With business_location/benefit_type expansion
- `EmployeeBenefitSerializer` - With employee/plan expansion
- `BenefitDeductionSerializer` - With employee_benefit/payroll expansion
### Services
- `BenefitTypeService` - `get_benefit_type_with_data()`
- `BenefitPlanService` - `get_benefit_plan_with_data()`
- `EmployeeBenefitService` - `get_employee_benefit_with_data()`
- `BenefitDeductionService` - `get_benefit_deduction_with_data()`
### Usage in Deputy
- Benefit enrollment tracking
- Employee/employer contribution calculations
- Integration with payroll deductions
---
## Performance
**Path:** `apps/performance/`
**Purpose:** Performance reviews, goal setting, and 360-degree feedback.
### Models
- `PerformanceReview` - Scheduled reviews with ratings and comments
- `EmployeeGoal` - Individual goals with progress tracking
- `ReviewFeedback` - 360-degree feedback from peers
### Serializers
- `PerformanceReviewSerializer` - With business_location/employee/reviewer expansion
- `EmployeeGoalSerializer` - With employee expansion
- `ReviewFeedbackSerializer` - With review/from_user expansion
### Services
- `PerformanceReviewService` - `get_performance_review_with_data()`
- `EmployeeGoalService` - `get_employee_goal_with_data()`
- `ReviewFeedbackService` - `get_review_feedback_with_data()`
### Usage in Deputy
- Annual/quarterly performance reviews
- Goal setting and tracking
- Peer feedback collection
---
## Training
**Path:** `apps/training/`
**Purpose:** Training programs, modules, completions, and certificates.
### Models
- `TrainingProgram` - Business-location training programs
- `TrainingModule` - Individual modules within programs
- `EmployeeTraining` - Enrollment tracking
- `TrainingCompletion` - Module completion records
- `TrainingCertificate` - Generated certificates
### Serializers
- `TrainingProgramSerializer` - With business_location expansion
- `TrainingModuleSerializer` - With program expansion
- `EmployeeTrainingSerializer` - With employee/program expansion
- `TrainingCompletionSerializer` - With enrollment/module expansion
- `TrainingCertificateSerializer` - With enrollment expansion
### Services
- `TrainingProgramService` - `get_training_program_with_data()`
- `TrainingModuleService` - `get_training_module_with_data()`
- `EmployeeTrainingService` - `get_employee_training_with_data()`
- `TrainingCompletionService` - `get_training_completion_with_data()`
- `TrainingCertificateService` - `get_training_certificate_with_data()`
### Usage in Deputy
- Mandatory training tracking
- Certification expiry management
- Training completion reporting
---
## Notifications
**Path:** `apps/notifications/`
**Purpose:** In-app notification system for users.
### Models
- `Notification` - User notifications with read status and links
### API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/notifications/` | CRUD | User notifications |
| `/notifications/<id>/mark-read/` | POST | Mark as read |
| `/notifications/mark-all-read/` | POST | Mark all as read |
| `/notifications/unread-count/` | GET | Get unread count |
### Serializers
- `NotificationSerializer` - With user expansion
### Services
- `NotificationService` - `get_notification_with_data()`
### Usage in Deputy
- Shift reminders
- Leave approval notifications
- Timesheet submission reminders
- System alerts
---
## Reports
**Path:** `apps/reports/`
**Purpose:** Report generation and scheduling.
### Models
- `Report` - Generated reports with filters and scheduling
### API Endpoints
- Full CRUD via ReportViewSet
### Serializers
- `ReportSerializer` - With generated_by expansion
### Services
- `ReportService` - `get_report_with_data()`
- `generate_attendance_report()` - Attendance reporting placeholder
- `generate_payroll_report()` - Payroll reporting placeholder
### Usage in Deputy
- Attendance reports
- Payroll summaries
- Leave balance reports
- Scheduled report generation
---
## Dashboard
**Path:** `apps/dashboard/`
**Purpose:** Aggregated statistics and summary views.
### API Endpoints
| Endpoint | Description |
|----------|-------------|
| `/dashboard/summary/` | Overall system summary |
| `/dashboard/stats/` | Key performance metrics |
### Serializers
- `DashboardSummarySerializer` - Total users, organizations, attendance, pending items
- `DashboardStatsSerializer` - Attendance rate, leave utilization, pending approvals
### Usage in Deputy
- Manager dashboard overview
- Key metrics at a glance
- Pending action items
---
## Files
**Path:** `apps/files/`
**Purpose:** File upload and management.
### Models
- `FileUpload` - Uploaded files with metadata (size, type, privacy)
### API Endpoints
| Endpoint | Description |
|----------|-------------|
| `/files/` | CRUD for file uploads |
| `/files/upload/` | Upload endpoint |
### Serializers
- `FileUploadSerializer` - With uploaded_by expansion
### Services
- `FileService` - `get_file_with_data()`, `get_category_with_data()`
### Usage in Deputy
- Document storage
- Profile photos
- Attachment uploads for leave/documents
---
## Documents
**Path:** `apps/documents/`
**Purpose:** Employee documents, contracts, and document management.
### Models
- `DocumentTemplate` - Reusable templates (employment, NDA, handbook)
- `EmployeeDocument` - Individual employee documents with status
- `DocumentSignature` - Electronic signature tracking
### Serializers
- `DocumentTemplateSerializer` - With business_location expansion
- `EmployeeDocumentSerializer` - With employee/template expansion
- `DocumentSignatureSerializer` - With document/signed_by expansion
### Services
- `DocumentTemplateService` - `get_document_template_with_data()`
- `EmployeeDocumentService` - `get_employee_document_with_data()`
- `DocumentSignatureService` - `get_document_signature_with_data()`
### Usage in Deputy
- Employment contract management
- Electronic signatures
- Document expiry tracking
- Template-based document generation
---
## Compliance
**Path:** `apps/compliance/`
**Purpose:** Compliance rules, violations, and audit management.
### Models
- `ComplianceRule` - Business-location rules (rest periods, max hours, awards)
- `ComplianceViolation` - Violation tracking with severity
- `TermsAndConditions` - Versioned T&Cs
- `TermsAcknowledgment` - Employee acknowledgment tracking
- `PrivacyConsent` - Privacy policy consent tracking
### Serializers
- `ComplianceRuleSerializer` - With business_location expansion
- `ComplianceViolationSerializer` - With business_location/rule/employee expansion
- `TermsAndConditionsSerializer` - With business_location expansion
- `TermsAcknowledgmentSerializer` - With employee/terms expansion
- `PrivacyConsentSerializer` - With business_location/employee expansion
### Services
- `ComplianceRuleService` - `get_compliance_rule_with_data()`
- `ComplianceViolationService` - `get_compliance_violation_with_data()`
- `TermsAndConditionsService` - `get_terms_and_conditions_with_data()`
- `TermsAcknowledgmentService` - `get_terms_acknowledgment_with_data()`
- `PrivacyConsentService` - `get_privacy_consent_with_data()`
### Usage in Deputy
- Award compliance tracking
- Rest period enforcement
- Terms and conditions acceptance
- Privacy consent management
---
## Availability
**Path:** `apps/availability/`
**Purpose:** Employee availability and scheduling preferences.
### Models
- `EmployeeAvailability` - Recurring weekly availability patterns
- `AvailabilityException` - One-off unavailability (sick, vacation)
- `AvailabilityRequest` - Employee-requested changes with approval
### Serializers
- `EmployeeAvailabilitySerializer` - With user/business_location expansion
- `AvailabilityExceptionSerializer` - With user expansion
- `AvailabilityRequestSerializer` - With user/reviewed_by expansion
### Services
- `EmployeeAvailabilityService` - `get_employee_availability_with_data()`
- `AvailabilityExceptionService` - `get_availability_exception_with_data()`
- `AvailabilityRequestService` - `get_availability_request_with_data()`
### Usage in Deputy
- Availability-based scheduling
- Time-off preferences
- Scheduling conflict prevention
---
## Integrations
**Path:** `apps/integrations/`
**Purpose:** Third-party integrations and webhook management.
### Models
- `Webhook` - Configurable webhooks with event filtering
- `Integration` - Third-party service connections
### API Endpoints
| Endpoint | Description |
|----------|-------------|
| `/integrations/webhooks/` | Webhook management |
| `/integrations/integrations/` | Third-party integrations |
### Serializers
- `WebhookSerializer` - With created_by expansion
- `IntegrationSerializer` - With created_by expansion
### Services
- `WebhookService` - `get_webhook_with_data()`
- `IntegrationService` - `get_integration_with_data()`
### Usage in Deputy
- Payroll system integrations
- Accounting software connections
- Custom webhook notifications
---
## Settings
**Path:** `apps/settings_app/`
**Purpose:** Application configuration and settings management.
### Models
- `Setting` - Key-value configuration storage
### Serializers
- `SettingSerializer`
### Services
- `SettingService` - `get_setting_with_data()`
- `get_setting(key, default)` - Retrieve setting value
- `set_setting(key, value)` - Update setting value
- `delete_setting(key)` - Remove setting
### Usage in Deputy
- Business/location-specific configuration
- Feature toggles
- Custom business rules
---
## Activity Logs
**Path:** `apps/activity_logs/`
**Purpose:** User activity tracking for auditing.
### Models
- `ActivityLog` - User actions with entity tracking and metadata
### API Endpoints
| Endpoint | Description |
|----------|-------------|
| `/activity-logs/` | Read-only activity logs |
### Serializers
- `ActivityLogSerializer` - With user expansion
### Services
- `ActivityLogService` - `get_log_with_data()`
### Usage in Deputy
- User action history
- Entity change tracking
- Security auditing
---
## Audit Logs
**Path:** `apps/audit_logs/`
**Purpose:** Database-level audit trail.
### Models
- `AuditLog` - CREATE/UPDATE/DELETE tracking with old/new values
### API Endpoints
| Endpoint | Description |
|----------|-------------|
| `/audit-logs/` | Read-only audit logs |
### Serializers
- `AuditLogSerializer` - With user expansion
### Services
- `AuditLogService` - `get_log_with_data()`
### Usage in Deputy
- Compliance auditing
- Data change history
- Forensic investigation
---
## Unified FK Expansion Pattern
All serializers support conditional ForeignKey data expansion via serializer context flags.
### Usage
```python
# Default response - FK fields return None for nested data
serializer = LeaveSerializer(leave)
# With expansion - nested data included
serializer = LeaveSerializer(
leave,
context={
'get_user_data': True,
'get_business_location_data': True,
'get_leave_type_data': True,
'get_approved_by_data': True,
}
)
```
### Pattern
- `<field>_id` - Exposes raw ForeignKey UUID (read-only)
- `<field>` - SerializerMethodField that checks `self.context.get('get_<field>_data', False)`
- Service classes provide `get_<model>_with_data()` static methods
- Imports are done inside methods to avoid circular dependencies
---
## Deputy Equivalents Summary
| XTask App | Deputy Feature |
|-----------|---------------|
| Authentication | Login/SSO |
| Users | People/Employees |
| Organization | Business/company accounts |
| Business Locations | Locations/Areas |
| Roles & Permissions | Access Levels |
| Attendance | Time & Attendance |
| Scheduling | Rostering/Scheduling |
| Timesheets | Timesheets |
| Leave | Leave Management |
| Payroll | Payroll (AU) |
| Benefits | Benefits (limited) |
| Performance | Performance Management |
| Training | Training (limited) |
| Notifications | News Feed/Notifications |
| Reports | Reports |
| Dashboard | Home/Dashboard |
| Files | Document Library |
| Documents | Contracts/Onboarding |
| Compliance | Compliance/Awards |
| Availability | Availability |
| Integrations | Integrations |
| Settings | Business Settings |
| Activity Logs | Activity Feed |
| Audit Logs | Audit Trail |