#Time tracking and approvals

Module id: MOD-TIME-TRACKING
Doc profile: capability

Contractors record live hours and breaks, submit reports for company review, and companies approve filled time for payment send. Backend workers ensure tracking rows exist and mark approval notices when the shift window is due — replacing Bubble’s recursive send_tracking_approve with a queue/cursor job (LOG-RECURSIVE). End job popup is owned by MOD-COMPANY-SHIFTS; this module hosts it for report Submit only.

#Purpose

Give contractors a signed-in place to start and stop shift timers, edit logged duration, and submit completed entries; give companies a time-tracking tab to filter and approve those entries; and run server-side ensure/approve-notice jobs so rows and approval_notice_sent stay consistent without client service-role writes (MON-CLIENT-WRITES-ALL). Observable outcomes are time_entries rows (from Bubble time_tracking1) under RLS, with create/stop/update/approve going through JWT RPCs or service-role edge workers. Live Start time may set company_requested true or false from the begin-shift “Company request” checkbox; backend ensure-row create always leaves that flag false.

#Scope boundaries

Module-map primary_journeys still say company “approve or reject” and that the fifteen-minute delay “resumes” tracking approve/create. Export chase supersedes both: company tab is Approve → Approved only, and the delay job only adjusts list visibility + clears its marker (J4 / J5). Refresh the map on the next map pass; do not reintroduce reject or delay→approve coupling from the stale map wording.

#Actors

#Capability composition

Contractor time-tracking is one cabinet route with two modes (live vs reports). Company approval lives as a tab body inside the company shifts host. Backend ensure/approve-notice and fifteen-minute delay are edge/cron surfaces, not SPA pages. Shared End job popup is imported from company-shifts.

Bubble evidence for pages, APIs, and tab body is under Traceability / IR evidence.

#Primary journeys

Journeys are reconstructed from contractor page workflows, company dashboard time-tracking workflows, and API events create_list_tracking / send_tracking_approve / 15_minuts_delay. Where End job popup internals or company shift publish enqueue belong to another module, steps are marked out of scope.

#J1 — Contractor live-tracks a shift

1. A signed-in contractor opens /contractor/time-tracking (default or tab=time_tracking).
2. Signed-out visitors are redirected to /; the page stamps the contractor time-tracking root under the cabinet workspace.
3. Mode shows “Tracking your time” (vs “Time tracking reports”); live mode shows “Start tracking your time”, today’s date, and “Begin shift”.
4. Begin shift opens “New time entry for YYYY/MM/DD” with shift picker and Checkbox Company request; Cancel hides; Start time creates an in-progress time_entries row via RPC (self contractor, chosen shift, started_at now) with company_requested true when Company request is checked and false when it is not — do not treat backend ensure-row’s always-false create as this path.
5. Stop ends the timer via RPC with logged hours/minutes/seconds; break (“If you had a break:”) applies only when elapsed ≥ 15 minutes — otherwise the less-than-15-minutes message blocks break selection.
6. Editing start/end calls update RPC and recomputes logged fields; optional ?shift= focuses that shift or shows a clear empty/error state.
7. RPC failures show inline/page errors without inventing client-only persistence.

#J2 — Contractor reviews reports and submits

1. Contractor selects “Time tracking reports” and sees the reports list (Date, Job title, Company, Location, Start T, End T, Break T, Logged T, Notes, Approve, and Upcoming payment when bound) or “No result found”.
2. Approve column is read-only on this surface (waiting vs company-approved labels).
3. Check opens the notes popup for the row’s contractor notes.
4. Submit opens the shared End job popup host for the selected entry — implement reuses MOD-COMPANY-SHIFTS End job popup; does not fork it.
5. After a successful shared confirm, the list refreshes; Cancel/hide returns without orphan overlays.
6. Postmark “New time-tracking report” and End job popup write paths remain owned by the shared reusable (out of this module’s implement tree).

#J3 — Backend ensures tracking rows and approval notices

1. An enqueue for contractor + shift runs the create-list-tracking equivalent: if no time_entries row exists for that pair, insert one with company_requested false and approval_notice_sent false; if a row already exists, skip create (idempotent). This always-false create is only the ensure path — not the contractor live Start time branch in J1.
2. After create (or when the row exists), enqueue send-tracking-approve work and persist an opaque schedule_send_approve_job_id when a follow-up is scheduled.
3. When the approval window is due — shift date plus hours required, plus one day, is less than now — the worker sets approval_notice_sent true.
4. When the window is not due, the worker re-queues with backoff/cursor and must not HTTP-schedule itself (LOG-RECURSIVE).
5. Upstream company shift publish that enqueues this consumer stays MOD-COMPANY-SHIFTS; this module owns the consumer redesign only.

#J4 — Company reviews and approves time entries

1. A company user opens /company/shifts?tab=time_tracking and sees filters “Select period”, “Select engagement”, “Approval status” plus “Zero hours” / “Filled hours”.
2. The list shows Date, Job title, Worker, Location, Logged time, Approval, Contractors’ note — or “Nothing was found. Try again later!”.
3. Row shows “Approve” when not company-approved and “Approved” when true; Approve opens confirm “Please, confirm your action” / “You are going to send this shift for payment.” with Save / Discard.
4. Save calls set_company_approval setting company_approved and sent_for_payment true; Discard writes nothing.
5. “Multipal approval” (source spelling) bulk-applies the same flags via one server round-trip.
6. Contractors’ note popup Save persists company notes and sets sent_for_payment true (same paid flag as Approve Save); Close dismisses.
7. There is no separate reject control on this surface — only Approve → Approved.

#J5 — Fifteen-minute delay clears list visibility marker

1. A company (or system) caller schedules the fifteen-minute delay job for a target user.
2. When the job runs as service role, it adds the user to the show-contractor-list visibility set and clears the schedule-15-min-delay marker.
3. A second run with the marker already clear is a successful no-op.
4. The job does not run create-list-tracking or send-tracking-approve — those stay on J3.

#Vertical slices (decompose)

Decompose TT-LIVE-TRACK still echoes an AC that Start time always passes company_requested=false; implement must follow the checkbox branch documented in J1 / IR evidence, not that oversimplification.

#Key UI states

#Style and fidelity

Cabinet workspace outlet for contractor route and company tab body. Transcribe visible copy and stamp data-bubble-id on migrated roots: contractor page, mode toggle, live/report regions, begin-shift popup (including Company request checkbox), reports RG, company time-tracking group and RG, approve and notes popups. Preserve source spelling “Multipal approval”. Shared tokens come from the app-level stylesheet that SHELL-LAYOUT (MOD-SHELL) delivers out of IR styles (ir/slices/styles____part_all.json — 49 styles, 8 color tokens, 1 font token); this cycle's module map has no separate design-system module, so do not defer a token to one. Do not restyle reports into a card grid — keep table/list hierarchy.

#Failure modes

#Traceability

#IR evidence

#Module evidence roots

• bTJFi0 — contractor_time-tracking page (/pages/bTJIF0); live timer, reports, PageLoaded auth, Submit host for EndJobPopup
• bTLsx — API event create_list_tracking (/api/bTLsy); NewThing when count of matching time_tracking1 for contractor+shift is 0; then schedule send_tracking_approve and store schedule id
• bTMBg — API event send_tracking_approve (/api/bTMBh); when window due set send_boolean true; else ScheduleAPIEvent self (bTMCQ) — target must become queue/cursor (LOG-RECURSIVE)
• bTKPV — API event 15_minuts_delay (/api/bTKPZ); add user to show_contractor_list_user, clear schedule_15_min_delay_text

Supporting segments: ir/slices/bTJIF0____root.json, ir/slices/edef_bTHky____root.json, bTHkx (deferred EndJobPopup), time_tracking1, approve_type, break, external_ns:bTNMZ.

#Path-key ↔ inventory id aliases

#Start time / company_requested (chased)

Workflow bTLYK (ButtonClicked Start time on begin-shift popup) has two NewThing actions on custom.time_tracking1:

• bTLar — when Checkbox Company request bTJJZ0 has data (get_data): sets company_request_boolean true (plus contractor = CurrentUser, shift from picker bTJJR0, start_date = now).
• bTLat — when bTJJZ0 has no data (get_not_data): same contractor/shift/start fields with company_request_boolean false.

Do not conflate with create_list_tracking action bTNLv1, which always initializes company_request_boolean false on ensure-row create.

#Approval window (chased)

On send_tracking_approve action bTMCE, send_boolean is set true when:

track.shift.date_date + hours_required_number (plus_hours) + 1 day (plus_days) less_than Current Date/Time.

If that ChangeThing does not apply (PreviousStep empty), action bTMCQ schedules bTMBg again — rewrite as re-queue, not HTTP self-schedule.

#create_list_tracking (chased)

• Runs when contractor parameter is not empty.
• bTNLv1 NewThing time_tracking1 when Search count for same contractor + shift equals 0; initial values: contractor, shift, company_request_boolean false, send_boolean false.
• bTMCF ScheduleAPIEvent → bTMBg when previous NewThing is not empty.
• bTMCP stores schedule id into schedule_send_approve_text on the new/previous thing.

#Company approve and notes (chased)

• Single: bTMSH sets approve_company_boolean and send_paid_boolean true.
• Bulk: bTMTZ ChangeListOfThings same two flags.
• Contractors’ note Save bTLhL writes notes_company_text and sets send_paid_boolean true (same paid flag as Approve Save).
• No reject / not_approved write path on the company time-tracking tab (bTLhn deleted).

#Fifteen-minute delay (chased)

• bTKPa / bTKVs1: add user to show-contractor-list visibility and clear delay marker.
• No create-list-tracking or send-tracking-approve side effects on this API — stale module-map wording that the delay “resumes” approve/create is wrong.

#Privacy roles (time_tracking1)

• contractor_ — view/search when CurrentUser is the contractor on the row.
• company_ — view/search via shift ownership chain.
• admin_ — view/search for admin role.
• everyone — no view/search.

Target: RLS + SECURITY DEFINER RPCs; Bubble ignore_privacy_rules on APIs must not become SPA bypasses.

#Option sets

#Residuals (decompose)

• time_tracking option set — display only, no values → dead.
• bTLhn / feedback_text — deleted → dead.
• bTHkx EndJobPopup — deferred to MOD-COMPANY-SHIFTS.
• bTMBT shift notify enqueue — answered structurally; consumer is TT-APPROVE-QUEUE.

#Decompose refs

tooling/cursor-impl-cycle/output/decompose/MOD-TIME-TRACKING.json — items TT-SCHEMA through TT-DELAY-JOB.