TDS CoPilot — Agent Architecture
& Workflow Design

flowchart TD
  A["Client request lands in Outlook shared mailbox"] --> B{"Is this a shift or coverage request?"}
  B -->|No| Z["Route to human inbox and stop"]
  B -->|Yes| C["Intake Agent classifies request type"]
  C --> C1["Static guard on site"]
  C --> C2["Adhoc one off work"]
  C --> C3["Ongoing core hours"]
  C1 --> D["Extract fields"]
  C2 --> D
  C3 --> D
  D --> E["Customer, site, address, date, start, finish, headcount,
licence class, rate, PO reference, client contact"]
  E --> F{"Extraction confidence above threshold
and no required field missing?"}
  F -->|No| G[/"CHECKPOINT 1
Human confirms or corrects parsed request"/]
  F -->|Yes| H["Create Shift Request record with unique TDS reference"]
  G --> H
  H --> I["Acknowledge receipt to client on the same thread"]
  I --> J["Hand to Roster Agent"]

flowchart TD
  A["Validated Shift Request"] --> B["Identify which platform this client uses"]
  B --> C["Guardhouse / FieldService / Humanforce"]
  C --> D{"Customer record exists?"}
  D -->|No match| E[/"CHECKPOINT 2
Approve creation of new customer"/]
  D -->|Fuzzy match| F[/"CHECKPOINT 2b
Confirm this is the right customer"/]
  D -->|Exact match| G{"Site record exists under that customer?"}
  E --> G
  F --> G
  G -->|No| H[/"CHECKPOINT 3
Approve creation of new site"/]
  G -->|Yes| I["Create shift via platform API"]
  H --> I
  I --> J{"API call successful?"}
  J -->|No| K["Retry 3 times with backoff"]
  K --> L{"Still failing?"}
  L -->|Yes| M[/"Escalate to ops - platform outage"/]
  L -->|No| N["Write platform shift ID back to TDS record"]
  J -->|Yes| N
  N --> O["Hand to Allocation Agent"]

flowchart TD
  A["Shift live on platform"] --> B["Pull shift history for this site and this client"]
  B --> C["Rank candidates by site familiarity and reliability score"]
  C --> D["Hard filter - licence current, inductions valid,
no clash, right qualification class"]
  D --> E["Fatigue calculation - hours already rostered this fortnight plus this shift"]
  E --> F{"Total within the 36 to 48 hour threshold?"}
  F -->|No| G["Exclude guard and log overtime breach reason"]
  F -->|Yes| H["Add to TIER 1 - direct TDS guards"]
  G --> I{"Any Tier 1 candidates remaining?"}
  H --> I
  I -->|Yes| M["Build ranked offer list"]
  I -->|No| J["Escalate to TIER 2 - approved supplier guards"]
  J --> K{"Is supplier fill pre-approved for this client?"}
  K -->|Yes| M
  K -->|No| L[/"CHECKPOINT 4
Approve supplier fill and margin impact"/]
  L --> M
  M --> N["Hand ranked list to Engagement Agent"]

flowchart TD
  A["Ranked offer list"] --> B["Send offer - wave 1 to top candidates"]
  B --> C["WhatsApp message"]
  B --> D["Email"]
  B --> E["In app push - Humanforce, Guardhouse, FieldService"]
  C --> F{"Response inside the SLA window?"}
  D --> F
  E --> F
  F -->|Accepts| G["First accept wins - lock the shift immediately"]
  F -->|Declines| H["Mark declined and move down the list"]
  F -->|No response| I["Wave 2 - widen the pool and shorten the window"]
  H --> J{"Candidates remaining?"}
  I --> J
  J -->|Yes| B
  J -->|No| K[/"CHECKPOINT 5
Unfilled shift - ops decides: supplier, premium rate,
or advise client"/]
  G --> L["Withdraw all outstanding offers for this shift"]
  L --> M["Assign guard across every relevant platform"]
  M --> N["Confirm to guard - site, address, ETA, contact, special instructions"]
  N --> O["Hand to Client Comms Agent"]

flowchart TD
  A["Guard assigned"] --> B["Load client communication profile"]
  B --> C{"Profile defined for this client?"}
  C -->|No| D[/"CHECKPOINT 6
Confirm what this client wants disclosed
and who is copied"/]
  C -->|Yes| E["Assemble confirmation pack"]
  D --> E
  E --> F["Guard name and licence number"]
  E --> G["Shift date, start, finish, ETA"]
  E --> H["Site and TDS shift reference"]
  E --> I["Escalation contact"]
  F --> J["Reply on the ORIGINAL email thread - preserve subject and recipients"]
  G --> J
  H --> J
  I --> J
  J --> K["Log confirmation against the shift record"]
  K --> L["Trigger Commercials Agent"]

flowchart TD
  A["Shift confirmed to client"] --> B["Load client billing profile"]
  B --> C{"Billing profile on file?"}
  C -->|No| D[/"CHECKPOINT 7
Human defines: PO required, rate card, cycle,
consolidation, portal or email, approver"/]
  C -->|Yes| E{"PO required before the shift is worked?"}
  D --> E
  E -->|Yes| F["Raise PO and send to client per profile"]
  E -->|No| G["Flag shift as bill on completion"]
  F --> H["Store PO number on the shift record"]
  G --> H
  H --> I(["PARK - wait for timesheet approval"])
  I --> J["S8 returns an approved timesheet"]
  J --> K["Generate invoice from approved actual hours"]
  K --> L{"Variance against quoted value above tolerance?"}
  L -->|Yes| M[/"CHECKPOINT 8
Approve invoice before issue"/]
  L -->|No| N["Auto issue invoice per client cycle"]
  M --> N
  N --> O["Write to accounting platform and dashboard"]

flowchart TD
  A["Shift start approaching"] --> B["Pre shift reminder to guard - T minus 2 hours"]
  B --> C{"Clocked in inside the grace window?"}
  C -->|Yes| D["Mark on site and verify geolocation against site"]
  C -->|No| E["Auto contact guard - WhatsApp and app prompt"]
  E --> F{"Guard responds and is en route?"}
  F -->|Yes| G["Notify client of revised ETA"]
  F -->|No| H[/"CHECKPOINT 9
NO SHOW - ops authorises urgent backfill"/]
  H --> I["Re inject into S3 Allocation as urgent priority"]
  I --> J["Notify client of replacement guard"]
  D --> K["Monitor mid shift welfare checks and patrol scans"]
  G --> K
  K --> L{"Clock out recorded at shift end?"}
  L -->|Yes| M["Close attendance record with actual hours"]
  L -->|No| N["Flag missing clock out as exception"]
  M --> O["Hand to Timesheet Agent"]
  N --> O

flowchart TD
  A["Shift completed"] --> B["Compare rostered versus actual against attendance record"]
  B --> C{"Variance inside this client's tolerance?"}
  C -->|Yes| D["Auto approve on the client's platform"]
  C -->|No| E["Classify the exception"]
  E --> F["Missing clock in or clock out"]
  E --> G["Overtime or extended hours"]
  E --> H["Wrong site or wrong guard clocked on"]
  E --> I["Break, allowance or penalty rate mismatch"]
  F --> J[/"CHECKPOINT 10
Approver is shown the error, the evidence
and the options: fix, approve as is, reject"/]
  G --> J
  H --> J
  I --> J
  J --> K["Apply the human decision on the platform"]
  K --> L["Record decision and reason in the audit log"]
  D --> M["Release to Commercials Agent for invoicing"]
  L --> M
  M --> N["Feed exception pattern back to Insights Agent"]

flowchart TD
  A["Every agent writes to the shared event log"] --> B["Insights Agent aggregates"]
  B --> C["Shifts today - filled, unfilled, in progress, completed"]
  B --> D["Daily and month to date dollar value"]
  B --> E["Invoices pending, issued, overdue"]
  B --> F["Timesheets in error, grouped by client and by cause"]
  B --> G["Guard fatigue and overtime watchlist"]
  B --> H["Unfilled shift risk for the next 7 days"]
  B --> I["Autonomy score - percent completed without human touch"]
  C --> J["Live operations dashboard"]
  D --> J
  E --> J
  F --> J
  G --> J
  H --> J
  I --> J
  J --> K["Daily digest to leadership"]
  J --> L["Exception queue to ops"]