Gig Domain Overview

What the Gig Domain Does

The Gig domain manages the end-to-end lifecycle of ad-hoc, short-term job fulfilment — from an employer posting a manpower need, to a talent completing the work and receiving payment.

A typical scenario: a McDonald's outlet needs 3 Service Crew workers for an 8-hour shift next Tuesday. The Gig domain handles posting that shift, matching it with suitable gig workers, tracking who shows up, recording their working hours, and ensuring they get paid.

What makes Gig different from Careers?

	Gig	Careers
Duration	Single shift (typically 4–10 hours)	Ongoing employment
Frequency	Recurring — same job, new shifts weekly	One-time posting per opening
Selection	Fast — ranked by algorithm, can auto-select	Manual — employer reviews applications
Attendance	Tracked per shift via QR clock-in/out	Not tracked by platform
Payment	Per shift, calculated from hours worked	Not handled by platform
Credits	Consumes gig credits from Billing	Consumes placement credits from Billing

---

Fundamental Concepts

Job vs Shift

A Job is a long-lived definition of a manpower need. It describes the role, location, pay rate, description, and requirements. Jobs are not one-time postings — employers keep them active and add new Shifts over time.

Example: "Service Crew at McDonald's Orchard, $12/hr" is a Job that persists for months. The employer adds new Shifts to it whenever they need workers.

A Shift is a specific time window within a Job that needs workers. Each Shift has a start time, end time, and a headcount (how many workers are needed). Shifts own the fulfilment lifecycle — they are what gets posted, applied to, staffed, and completed.

Example: "Tuesday April 8, 9am–6pm, 3 workers needed" is a Shift under the McDonald's Service Crew Job.

important

The Shift is the primary lifecycle entity in the Gig domain, not the Job. Jobs are containers; Shifts are what gets fulfilled. All status tracking, application, assignment, attendance, and payment happen at the Shift level.

Application — The Recruiting Phase

An Application represents a talent's intent to work a specific shift — the talent shows they want to work that shift by applying, and the employer shows they want that talent to fulfil the manpower need by accepting.

The Application answers: "Who wants to work this shift, and do both parties agree?"

An Application goes through a double handshake:

1. Talent applies — expresses interest in the Shift
2. Employer accepts — selects this talent from the ranked applicant pool
3. Talent confirms — acknowledges the selection and commits to showing up

Only when both parties have agreed does the system create an Assignment.

Assignment — The Operations Phase

An Assignment represents a confirmed work order — a specific talent committed to work a specific shift. This is the operational record that tracks attendance and working hours.

The Assignment answers: "Who is working, when did they start/stop, and how much do we pay them?"

The Three Definitions of Time

Every Assignment tracks time at two levels, with a third derived from the Shift:

Time	What it records	Who sets it	Mutable?
Scheduled Time	When the shift is supposed to happen	Derived from Gig::Shift.starts_at / ends_at	No (it's on the Shift)
Actual Time	When the worker physically clocked in/out	System (QR scan timestamp)	Never — this is the immutable audit record
Billable Time	The hours the employer agrees to pay for	Employer (defaults to actual, can override)	Yes, until the verification deadline

Example: A shift runs 9am–6pm (scheduled). The worker scans QR at 9:02am and 6:01pm (actual). The employer confirms 9:00am–6:00pm with a 60-minute paid break (billable). The worker is paid for 8 hours.

This separation is critical for:

• Audit trails — actual times are never lost, even when billable times are adjusted
• Dispute resolution — "the QR says 9:02am but I started working at 9:00am" is handled by the employer adjusting billable time
• The forgotten QR code scenario — employer generates QR late, worker started earlier. Actual time says 9:30am (when QR was scanned), but employer adjusts billable time to 9:00am

Settlement Window

After a worker clocks out, the employer has until 9:00am the next day to adjust billable times. During this window:

• The employer can modify billable_clock_in, billable_clock_out, and billable_break_minutes
• Each change is recorded in an adjustment log for audit
• After the deadline, billable times are locked and Payment is generated

Payment — Wage Disbursement

A Payment tracks the wage owed to a talent for a completed Assignment and its disbursement status. It is created after billable times are locked (the Assignment is "verified").

Payment represents the Jod → Talent money flow. The Employer → Jod money flow (gig credit consumption) is handled by the Billing domain.

Headcount — Derived Staffing State

Each Shift specifies a headcount — how many workers are needed. The staffing level is derived by counting confirmed Assignments against the headcount, not stored as a status.

Filled / Headcount	What the employer sees
0 / 3	"3 positions open"
1 / 3	"1 confirmed, 2 positions open"
3 / 3	"Fully staffed"

The Shift stays open regardless of how many positions are filled. It stops accepting new applications when the headcount is met or the application cutoff time passes.

---

Domain Models

Model	Purpose	Lifecycle
Gig::Job	Long-lived manpower need (outlet, role, description)	active → archived
Gig::Shift	Specific time window needing workers	draft → pending_approval → open → active → pending_verification → completed (+ cancelled, expired)
Gig::Application	Talent's intent + mutual selection process	pending → accepted → confirmed (+ rejected, withdrawn, expired, cancelled)
Gig::Assignment	Confirmed work order with attendance tracking	confirmed → clocked_in → clocked_out → verified (+ cancelled, no_show)
Gig::AssignmentAdjustment	Append-only audit log of billable time changes	Immutable (event record)
Gig::Payment	Wage disbursement tracking	pending → processing → paid
Gig::QrCode	Clock-in/out QR codes with expiry	Generated per shift, expires after configured duration

---

The Gig Business Process

Phase 1: Posting

1. Employer creates a Gig::Job (or reuses an existing one) defining the role, location, pay rate, and requirements
2. Employer adds a Gig::Shift (to a Gig::Job) specifying start time, end time, and headcount
3. If the employer's company requires approval, the Shift enters pending_approval until an approver publishes it
4. Once approved (or immediately if no approval required), the Shift becomes open and is visible to talent on the marketplace

Phase 2: Matching and Selection

5. Talent browse open Shifts (via Listings::Job) and apply — creating a Gig::Application in pending status
6. System ranks all applicants for the Shift using a scoring algorithm based on: show-up reliability, cancellation history, category experience, and employer ratings
7. Employer reviews ranked applicants and accepts one or more — each Application that the employer accepts moves to accepted
8. Auto-selection (if enabled for the outlet/location): If the employer hasn't selected anyone by the cutoff time, the system auto-selects the top-ranked applicant(s) up to headcount. Some clients prefer to disable auto-selection — this is a per-location configuration.
9. Selected talent receives a notification and must confirm — Application moves to confirmed
10. Upon confirmation, the system creates a Gig::Assignment linking the talent to the shift

Phase 3: Attendance

11. When the shift start time arrives, the Shift transitions to active
12. Employer generates a clock-in Gig::QrCode for the Shift
13. Talent scans the QR code to clock in — Assignment moves to clocked_in, actual_clock_in is recorded
14. Talent works the shift
15. Employer generates a clock-out QR code and fills in the initial time confirmation form
16. Talent scans the QR code to clock out — Assignment moves to clocked_out, actual_clock_out recorded, billable_* fields set from the employer's form

Phase 4: Verification and Payment

17. The settlement window opens — employer can adjust billable times until 9:00am the next day
18. Each adjustment creates an immutable Gig::AssignmentAdjustment record capturing old values, new values, reason, and who made the change
19. At the deadline (or earlier if employer explicitly locks), billable times are finalised — Assignment moves to verified
20. System creates a Gig::Payment calculated from verified billable hours × hourly rate
21. System triggers Billing domain to consume gig credits from the employer's entitlement lots (FIFO allocation across lots)
22. Payment tracks disbursement status: pending → processing (included in bank instruction file) → paid (confirmed)

Phase 5: Completion

23. When all Assignments for a Shift reach a terminal state (verified, cancelled, or no_show), the Shift transitions to completed
24. The Job remains active — employer continues adding new Shifts as needed

---

Key Business Rules

Talent Cancellation Policy

A talent can cancel at different points in the flow, with increasing consequences as the shift approaches. Cancellation reasons are mandatory for post-selection cancellations (via Taxonomy::GigStatusReason).

Before selection (Application in pending): Talent can withdraw at any time. No penalty, no document required. Application moves to withdrawn.

After selection (Application in accepted or confirmed, or Assignment exists):

Window	Requirements	Penalty	Shift impact
>48 hours before shift	Cancellation reason required	No penalty	Assignment cancelled, shift headcount reopens for new applicants
3–48 hours before shift	Cancellation reason required	Enters progressive suspension discipline	Assignment cancelled, shift headcount reopens
0–3 hours before shift	Cancellation reason + supporting document required (urgent cancellation)	Enters progressive suspension discipline	Assignment cancelled, shift headcount reopens if >30min before start
After shift starts	Cancellation blocked	Treated as no-show (see Suspension Policy)	—

Cancellation is blocked when: the talent has already clocked in, or the shift has already started (treated as no-show).

No explicit reposting mechanism. When an Assignment is cancelled, the shift's filled count decreases. If the shift is still open (before the application cutoff time), it naturally accepts new applicants — there is no need to create a new shift.

Employer Cancellation Policy

When an employer cancels a confirmed Assignment (talent has already confirmed), gig credits are deducted proportional to how late the cancellation is. This discourages disruptive last-minute cancellations that waste talent's time and availability.

Window	Credit deduction
>48 hours before shift	No deduction
24–48 hours	Progressive deduction (low)
12–24 hours	Progressive deduction (moderate)
3–12 hours	Progressive deduction (high)
0–3 hours	Progressive deduction (very high)
After shift starts	Full shift value consumed

Specific deduction percentages per window are a configuration decision. Cancellation reasons are mandatory (via Taxonomy::GigStatusReason) to enable future policy refinement based on data.

note

When an employer cancels a clocked_in Assignment (talent has already started working), the payment for hours already worked is an open question — see Gig::Payment model spec.

Suspension Policy

Suspension is a progressive discipline system for talent who no-show or cancel late (within 48 hours of shift start).

Triggers:

• Talent cancels a confirmed Assignment within 48 hours of shift start
• Talent does not clock in for an assigned shift (no-show, detected by system)

Progressive tiers:

Tier	Offense	Penalty	Appeal window
Warning	1st	Warning notification only. No suspension. Incident recorded.	N/A
Short suspension	2nd	7-day suspension	24 hours pre-suspension
Medium suspension	3rd	30-day suspension	24 hours pre-suspension
Long suspension	4th+	90-day suspension	24 hours pre-suspension

Appeal mechanism:

When a suspension is triggered (2nd offense and above), the system creates a pending suspension state. The talent has 24 hours to submit an appeal with a supporting document (e.g., MC) via the app.

During the 24-hour appeal window:

• Talent cannot apply to new shifts
• Existing confirmed Assignments are preserved (employers are not disrupted)
• Talent can still work their confirmed shifts

After the appeal window:

• If appeal submitted: Ops reviews (typical turnaround: same business day). If approved, penalty is cleared and full access is restored. If rejected, suspension takes effect.
• If no appeal: Suspension takes effect automatically.

When suspension takes effect:

• Talent cannot apply to new shifts
• Assignments within the suspension period are cancelled
• Assignments scheduled after the suspension ends are preserved
• Talent can still log in and view profile/history (read-only)
• Suspension lifts automatically when the period expires

Auto-Selection Timing

Auto-selection is a per-location configuration — some clients prefer manual selection only. When enabled, if the employer has not selected any applicants by the auto-select deadline:

• AM shifts (starting 00:00–11:59): auto-select runs at 9:00am the previous day
• PM shifts (starting 12:00–23:59): auto-select runs at 5:00pm the previous day

The system selects the top-ranked applicant(s) up to the shift's headcount.

No-Show Handling

If a talent does not clock in within a configured window after the shift starts:

• Assignment is marked no_show
• Talent enters the progressive suspension discipline (see Suspension Policy above)
• No Payment is generated for this Assignment

Shift Expiration

If a shift reaches its cutoff time with no applicants or no selections:

• Shift transitions to expired
• All remaining pending Applications are closed

Time Overlap Prevention

When a talent is confirmed for a shift, the system checks for time conflicts with other shifts the talent has applied to. Conflicting Applications are automatically rejected to prevent double-booking.

---

Cross-Domain Interactions

Domain	Interaction
Billing	When an Assignment is verified, the Gig domain triggers credit consumption from the employer's gig entitlement lots. The consumed amount equals the billable wage. Reservation may happen at shift posting time to prevent overspend.
Org	Gig::Job belongs to Org::Company. Employer actions are performed by Org::UserProfile. Role definitions come from Org::JobRoleVersion.
Talent	Gig::Application and Gig::Assignment reference Talent::Profile. Ranking algorithm uses talent's historical gig performance.
Listings	Gig::Job with its open shifts are synced to Listings::Job for the public marketplace. Talent discovers shifts through Listings search.
Taxonomy	Taxonomy::GigStatusReason provides the canonical list of cancellation and rejection reasons.
External Integrations	Shifts can originate from external workforce management systems (e.g., UKG). The integration layer maps external shifts to Gig::Shift records and syncs selection/attendance data back. Designed to support multiple integration providers.

---

Glossary

Term	Definition
Job	Long-lived definition of a manpower need — the role, location, pay rate, and description. Not a one-time posting.
Shift	A specific time window within a Job that needs workers. The primary lifecycle entity in the Gig domain.
Application	A talent's expression of interest in working a shift, combined with the mutual selection process.
Assignment	A confirmed work order — a talent committed to work a specific shift. The operational record for attendance.
Headcount	Number of workers needed for a shift. Staffing level is derived by counting Assignments against headcount.
Actual Time	The immutable, system-recorded timestamp when a QR code was scanned. Used for audit.
Billable Time	The employer-confirmed working hours used to calculate payment. Defaults to actual time, can be adjusted during the settlement window.
Settlement Window	The period after clock-out (until 9:00am next day) during which the employer can adjust billable times.
Verification	The act of locking billable times — either by the deadline passing or the employer explicitly confirming. Triggers Payment creation.
Double Handshake	The mutual agreement process: employer accepts an applicant, then the talent confirms. Both must agree before an Assignment is created.
Auto-Selection	System automatically selects the top-ranked applicant(s) if the employer hasn't made a selection by the cutoff time.
Ranking	Scoring algorithm that ranks applicants based on: show-up reliability (30%), cancellation history (25%), category experience (25%), and employer ratings (20%).
No-Show	When a confirmed talent fails to clock in for their assigned shift. Enters progressive suspension discipline.
Pending Suspension	A temporary state after a suspension is triggered, giving the talent 24 hours to appeal with a supporting document before the suspension takes effect.
Appeal	A talent's submission of a supporting document (e.g., MC) to contest a pending suspension. Reviewed by ops.

---

Open Questions

1. Approval hierarchy: The pending_approval flow for shifts requires defining who can approve shift postings. This depends on Org::UserProfile role/permission design which is not yet defined.
2. Billing reservation timing: Should gig credits be reserved when the Shift is posted (to prevent overspend), or when the Assignment is created (to avoid locking credits for unfilled positions)? See Billing domain documentation for reservation mechanics.
3. QR code scope: Should QR codes be generated per-shift (all workers scan the same code) or per-assignment (each worker gets their own)? Legacy supports both — per-shift with reuse within expiry window.
4. Auto-selection with headcount > 1: When auto-selecting multiple workers, should the system select all at once or stagger selections to give each talent time to confirm?
5. Shift active trigger: Recommended as time-based (shift transitions to active at starts_at), but could also be event-based (first clock-in). Time-based enables no-show detection before anyone clocks in.
6. Employer cancellation of clocked-in Assignment: When an employer cancels a clocked_in Assignment, the talent has already worked some hours. How should payment be handled? See Gig::Payment model spec.
7. Employer credit deduction percentages: The principle of time-windowed progressive deduction is established. Specific percentages per window (e.g., 25%, 50%, 75%, 100%) are a configuration decision to be determined.
8. No-show vs late cancel severity: Currently treated the same in the progressive discipline. Future consideration: should no-shows skip the warning tier and start at short suspension?
9. Loyalty program integration: A future loyalty program (points per hour worked, redeemable for vouchers) may interact with the suspension policy. Design as an extension point — appeal document submission should support future integration with loyalty tracking.