#Admin verification and ops

Module id: MOD-ADMIN
Doc profile: system

Platform admin console for TradeForce: role-gated /admin host, company and contractor verification lists, skill-rate editors on company detail, open/active shift inspection and edits, and invoice/payment-schedule recording. Target stack is React + Vite in app/ with Supabase Auth JWT + RLS/RPC under app/supabase/. Bubble page admin and its client workflows are the evidence for behavior; every persistent write must become server-authoritative (LOG-CLIENT-WRITES / MON-CLIENT-WRITES).

#Purpose

Platform admins need one console to verify companies and contractors, set skill rates, inspect and correct shifts, and mark time-entry payments as paid with notes. This module owns the /admin body inside the cabinet workspace, the tab query contract (adminnav / admintab), list/detail regions, approve and rate Save mutations, shift edit / stop-hiring, and admin payment confirm (including PostMark notify on edge). It does not own Header/SideBar chrome (MOD-SHELL), public auth (MOD-AUTH), contractor payment read UI (MOD-PAYMENTS), or Stripe Connect / KYC (MON-MARKETPLACE).

#Scope boundaries

#Actors

#Admin composition

Admin is one cabinet page whose body regions switch on the tab query. Shell admin menu enters Shifts via admintab openshifts and Companies / Contractors / Payments via adminnav. Sub-tabs and detail tabs reuse the same param. Empty tab on load is filled with adminnav Shift (Bubble writes the option display). G-Shifts itself is visible only when tab matches openshifts or activeshifts — so the empty-tab default alone does not show the shifts list until Open/Active (or shell Shifts) is chosen.

Bubble evidence for composition and gates is listed under Traceability / IR evidence.

#Primary journeys

Journeys are reconstructed from admin page workflows (PageLoaded → ChangePage, ButtonClicked → Search/ChangeThing/NewThing/ScheduleAPIEvent/connector). Where a chain ends in an edge notify, the wire literals are named; PostMark template HTML itself lives outside the export.

#J1 — Open admin and land on a gated host

1. An admin opens /admin (with or without tab); the page mounts inside the cabinet workspace with the admin body outlet.
2. If the session is missing, the app redirects to /; if the signed-in role is company, it redirects to the company shifts host; if contractor, to the contractor shifts host.
3. When the user is an admin and tab is empty, the app navigates to the same admin host with tab set to the Shift admin-nav default (Bubble option display).
4. Non-admins never see company, contractor, shift, or payment admin regions.

#J2 — Browse and open companies for verification

1. Admin opens /admin?tab=companies and sees Verified Companies / Not verified Companies sub-tabs.
2. Verified lists company profiles that completed onboarding and have at least one skill rate column set; Not verified lists the inverse rate filter among the same role/onboarding set.
3. Admin opens Details on a row and lands on /admin?tab=detailedcompany with that company as detail context.
4. Empty lists show “No result found”; query failures show a plain-language error in the companies region.

#J3 — Verify a contractor with skill set

1. Admin opens /admin?tab=contractors, switches Verified / Not verified (preserve wire value spelling veriedcontractors for verified), and opens a contractor into /admin?tab=detailedcontractor.
2. Verified lists contractor profiles that are active, onboarded, and approved true; Not verified lists the same role/active/onboarding set with approved false. On a not-yet-approved contractor, Admin chooses Approve, which opens the skill-set popup and loads the contractor into it.
3. Admin confirms; the app persists approved true and the selected skill set via an admin-only server write, then closes the popup.
4. Cancel closes the popup without approving; non-admin JWTs cannot set another user’s approved flag.

#J4 — Set company and contractor skill rates

1. From detailed company, Admin sees Company rate and Contractor rate sections with exactly four pay-practice rows (Concrete Carpenter, Concrete Finisher, Concrete Laborer, Concrete Walls).
2. Admin edits staging inputs and optional custom rate for an exact day (shift, existing rate, new rate).
3. Admin chooses Save; the app creates a custom_rates row when that path is used, updates the company profile rate columns, and appends the custom rate to the company’s list — all in one admin-authorized transaction.
4. Save failure shows a plain-language error; success resets inputs as the source does.

#J5 — Inspect and edit open or active shifts

1. Admin opens /admin?tab=openshifts or /admin?tab=activeshifts, optionally filters by company, and opens a shift into /admin?tab=detailedshift.
2. Admin edits evidenced shift fields and chooses Edit; the app creates an in-app notification to the company that the shift was changed, persists via admin RPC, and when the shift date is still in the future cancels/reschedules the tracking job that Bubble named shift.
3. Discard resets the editor and goes back without saving.
4. Stop hiring confirms stop_hiring and sets shift type upcoming (clearing schedule tracking when present), and updates the related contractor’s dependability for a company-canceled-shift positive; cancel closes the popup only.

#J6 — Record an admin payment on an invoice row

1. Admin opens /admin?tab=payments and switches Previous payments / Upcoming payment schedule / All invoices.
2. Admin opens a row into the payment details popup and enters amount and notes.
3. On confirm with amount present, the app sets admin paid amount, notes, and status paid on the time-tracking entry via admin RPC, then may notify via edge PostMark (user-invitation-3, empty template model) using server secrets only.
4. Confirm with empty amount runs only when the payment-tabs report list has at least one row; it follows the list-update + in-app notification (“Your payment is on the way!”) path; Cancel closes without writing.

#Navigation contracts

#Vertical slices (decompose)

#Side-effect contracts

#Role gate matrix (PageLoaded)

#Style and fidelity

Admin uses cabinet_workspace (section → container → workspace head from SHELL + surface-card body). Stamp data-bubble-id on the admin page root and G-admin outlet. Preserve list/table layout (not marketing cards), sub-tab labels including leading spaces on “ Not verified …”, empty copy “No result found” / “No data”, and detail labels (Dependability score, Company Name Rates, payment popup fields). 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.

#Failure modes

#Needs human clarification

None. After catalog + inventory + sanitized-export chase for PageLoaded gates, adminnav/admintab values, company/contractor Search filters (including not-verified approve1_boolean equals false), Approve/Save/Edit/Stop-hiring/Payment workflows, ScheduleAPIEvent shift, and PostMark body literals (From, TemplateAlias user-invitation-3, empty TemplateModel), admin console behavior is encoded in the export. PostMark template HTML content remains outside the export (same wire alias as MOD-PAYMENTS cycle mail) but is not required to implement the call site. Server-authority migration is a stack obligation, not an open product question.

#Traceability

#IR evidence

#Module evidence roots

• bTHun0 — admin page (/pages/bTHuo0), G-admin body, all admin list/detail workflows.

Supporting segments: ir/slices/bTHuo0____root.json, ir/slices/bTHuo0__elements____remaining_children.json, ir/slices/bTHuo0__elements__bTHvp0__elements____remaining_children.json, ir/slices/bTHuo0__workflows____part_A.json, user types company, custom_rate, rates, option sets adminnav, admintab.

#Path-key ↔ inventory id aliases

#Tab and option contracts (chased)

adminnav db_values: shift, companies, contractors, payments, detailedcompany, detailedcontractor, detailedshift (shift_type marked deleted).
admintab db_values: veriedcontractors (typo preserved), notverifiedcontractors, verified_companies, notverifiedcompanies, openshifts, activeshifts, all_invoices, upcoming_payment_schedule, previous_payments.
pay_practices: concrete_carpenter, concrete_finisher, concrete_laborer, concrete_walls (four rows).

Empty-tab fill (bTKmw) writes OptionValue display for adminnav/shift. G-Shifts visibility (element_condition:bTIKT0:0) is admintab openshifts or activeshifts only. Companies / Contractors / Payments groups key off adminnav companies / contractors / payments.

#List filters (chased)

• RG-Companies (bTHwr0): Search user with role company + onboarding; verified path further requires any of company_rates_number / company_concrete_finisher_number / company_concrete_laborer_number / company_concrete_walls_number non-empty (filtered constraints).
• RG-Contractors (bTIBv0): role contractor + active__boolean true + onboarding_boolean true; verified Search adds approve1_boolean equals true; not-verified Search (element_condition:bTIBv0:1, admintab notverifiedcontractors) uses the same role/active/onboarding constraints with approve1_boolean equals false (target profiles.approved = false).
• RG-payments (bTKIX0): time_tracking1 with tab-state constraints on approve_company / send_paid / status paid as element conditions encode.

#Mutations (chased)

• Approve (bTJLF): skill_set_list_custom_skill_set set_list from popup custom.skill_; approve1_boolean true.
• Save rates (bTKaR/bTKaT): NewThing custom.custom_rate (shift, existed_rate, new_rate); ChangeThing company rate columns + add to custom_rate1_list.
• Edit shift (bTMcD chain): NewThing custom.notification to company (bTMeM, text “Your shift "…" was changed”); ChangeThing shift fields; CancelScheduledAPIEvent; ScheduleAPIEvent bTMBT (shift) when the shift date is still after now.
• Stop hiring (bTMZI): ChangeThing stop_hiring / shift type; ChangeListOfThings user dependability (bTMZT, dependability_scoup_number + positives company_canceled_shift).
• Payment confirm with amount (bTMpP): admin_paid___number, admin_notes_text, status_option_status_paid = paid; then connector bTNNo.
• Payment confirm empty amount (bTMqB Only-when: ElementParent amount is_empty and GetElement bTKIM0 custom.report_ count ≥ 1): list update (bTMqR) + NewThing notification text “Your payment is on the way!” (bTNLe) + connector bTNNp.
• Both connectors: body From amanda.gasman@tradeforce.dev, To contractor email, TemplateAlias user-invitation-3, TemplateModel {}.

#Privacy & authorization

Target: only profiles.role = admin may read verification lists and mutate other users’ approved/rates, shifts stop/edit, custom_rates inserts, and time-entry admin paid fields. SPA uses user JWT + RLS/RPC; PostMark secrets only on edge. Bubble privacy_role:* rows for these types are answered structurally in decompose → DATA-MODEL RLS, not separate journey items.

#Naming map (idiomatic highlights)

Note: inventory user_type rates is an evidence segment; do not invent a live rates table from deleted fields — skill rates live on profiles + custom_rates as chased above. User_type company remains a segment label; admin company lists Search user with role company.