This is an internal working record, not an everyday instruction. It was written while the system was being rebuilt, for whoever maintains it. If you are here to do today's work, use the everyday documents instead: Procedures · Processes · Runbooks · The working day, step by step

CTC Process Sequence Diagram Catalog

• Status: CURRENT SOURCE / PROCESS / MIGRATION DIAGRAM CATALOG
• Source-inspection baseline: 4fc2f5a893765fbb95e0a2bdcb971322b0ec9fc0
• Process owner: P6-007
• Related:
• PROCESS_CONTRACT_STANDARD.md
• CROSS_PROCESS_HANDOFF_AND_IDENTITY_MATRIX.md

1. Purpose

This catalog makes current-source request, transaction, handoff, provider and recovery boundaries visible and connects them to the target one-writer migration model.

The diagrams are not a substitute for the owning process contract. They are a compact operating and reconstruction aid. When a diagram, an atomic process contract and current source disagree, the owning process and source must be reconciled and the discrepancy recorded.

2. Diagram Legend

Marker	Meaning
SR	Reconstructed from the named current PHP/JavaScript/API/helper paths.
DOC	Documented operating or target rule that still requires process-owner or applicable execution evidence.
TARGET	Proposed React/Next.js/TypeScript/worker responsibility; not implemented.
UNKNOWN	Exact policy, role, transaction or provider result is unresolved.

General reading rules:

solid request/response arrow
= current synchronous request or planned command boundary

dashed arrow
= post-commit/provider/notification/reconciliation effect

DB commit
!= provider success
!= next process completion
!= user acceptance

3. CTC Daily Operating Sequence

Evidence: SR + DOC. This is a composite view. Each child retains its own state and completion authority.

sequenceDiagram
    autonumber
    actor Office as Office / Dispatch
    participant Intake as Appointment Intake
    participant Planning as Inbound Planning
    participant Assign as Assignment Board
    actor Loader as Forklift Operator
    participant Review as Final Loading Review
    participant Inventory as Bale Inventory / Ledger
    participant Yard as Yard Dispatch
    actor Driver as Truck Operator
    participant Billing as Billing / Reports

    Office->>Intake: Review request and create/reschedule/cancel work
    Intake-->>Office: Scheduled work readback
    Office->>Planning: Plan dock, equipment, work type and assignment context
    Planning->>Assign: Expose Ready / Current / Next work
    Office->>Assign: Assign Loader and queue order
    Assign-->>Loader: Telegram or Loader-page visibility
    Loader->>Planning: Start and complete physical work
    Planning-->>Office: Completed Reload / Transload / Unload

    alt Eligible Reload or Transload
        Office->>Review: Reconcile quantity, weight and active ledger relation
        alt Source or Leftover action required
            Review->>Inventory: Apply Source or create Leftover
            Inventory-->>Review: Exact lot / ledger readback
        end
        Review-->>Office: Confirmed review readback
    else Unload or non-review path
        Planning-->>Inventory: Inventory / warehouse handoff when applicable
    end

    opt Yard work required
        Office->>Yard: Create / schedule / reconcile physical move
        Yard-->>Office: Queue and Yard Map readback
    end

    opt Driver delivery required
        Office->>Driver: Assign delivery
        Driver-->>Office: Delivery / evidence / parking / Yard readback
    end

    Office->>Billing: Reconcile local billing, files, email and provider effects
    Billing-->>Office: Independent completion checkpoints

    Note over Office,Billing: No composite status proves every child completed.

4. Office Planning And Loader Assignment

Evidence: SR. Important current behavior: assignment can commit before Telegram succeeds; the board and Loader page share underlying work but are not one role path.

sequenceDiagram
    autonumber
    actor Office
    participant Board as Assignment Board UI
    participant API as TMS Transload API
    participant App as Transload Assignment Helper
    database DB as MySQL
    participant TG as Telegram Provider
    actor Loader

    Office->>Board: Drag/select Ready work for Loader
    Board->>API: POST loader-assignment
    API->>App: Validate tenant, planner, work and loader token
    App->>DB: Update planner Loader and queue fields
    DB-->>App: Assignment committed
    App-->>API: Assignment result

    opt Auto Telegram requested
        API-->>TG: Send first/next assignment message
        alt Telegram succeeds
            TG-->>API: Provider success
            API-->>Board: Assignment + sent result
        else Telegram fails or result is uncertain
            TG-->>API: Failure / timeout / unknown
            API-->>Board: Assignment remains committed; notification needs recovery
        end
    end

    Board-->>Office: Refresh exact planner / board state
    API-->>Loader: Work appears on Loader page when role/query scope allows

    Note over Office,Loader: Do not reassign merely to resend Telegram.

Required readback

TRANSLOAD_ID
+ PLANNER_ID
+ assigned Loader ID(s)
+ queue order
+ planner job status
+ Telegram result/checkpoint when used

5. Loader Start And Complete

Evidence: SR. Both Assignment Board and Loader page can currently initiate Start/Complete paths. Target policy must select the normal actor path before migration.

sequenceDiagram
    autonumber
    actor Loader
    participant UI as Loader Page or Board Override
    participant API as TMS Transload API
    participant Handler as WMS/TMS Current Handler
    database DB as MySQL
    participant Staff as Staff-Time Ledger
    participant Post as Post-Commit Effects

    Loader->>UI: Open assigned Current work
    UI->>API: Start Transloading / Unloading
    API->>Handler: Resolve authenticated/assigned Loader actor
    Handler->>DB: Begin transaction
    Handler->>DB: Update T_TRANSLOAD runtime state
    Handler->>DB: Update T_LOADING_PLANNER to STARTED
    Handler->>Staff: Append JOB_START
    Staff-->>Handler: Event result
    Handler->>DB: Commit
    Handler-->>API: Start result
    API-->>UI: Refresh Opened work

    Loader->>UI: Enter completion data and submit
    UI->>API: Complete Transloading / Unloading
    API->>Handler: Validate current completion fields
    Handler->>DB: Begin transaction
    Handler->>DB: Write terminal work / equipment / planner effects
    Handler->>Staff: Attempt JOB_END
    Handler->>DB: Commit
    Handler-->>API: Completion result
    API-->>Post: Telegram / operation event / other post-commit effect
    API-->>UI: Completion response
    UI-->>Loader: Refresh Completed and downstream handoff

    Note over Staff,Post: Missing staff event or provider failure does not necessarily roll back physical work completion.

Unknown-result recovery

sequenceDiagram
    autonumber
    actor Loader
    participant UI
    participant API
    database DB
    actor Office

    Loader->>UI: Submit Start or Complete
    UI->>API: Request
    API--xUI: Timeout / connection loss
    Loader-->>Office: Report TRANSLOAD_ID, PLANNER_ID and action time
    Office->>API: Reread board, work detail and timeline
    API->>DB: Read T_TRANSLOAD, planner and staff events
    DB-->>API: Current committed state
    API-->>Office: Exact state

    alt Requested state is already committed
        Office-->>Loader: Continue from committed next step
    else Requested state is not committed
        Office-->>Loader: Retry only the missing action
    else Sources disagree
        Office-->>Loader: Stop; carry named partial exception
    end

6. Loader Clock Out And Scheduled Assignment Release

Evidence: SR. Current local staff-time event and scheduled-assignment release share one DB transaction. QuickBooks Time is a later effect.

sequenceDiagram
    autonumber
    actor Loader
    participant UI as Inbound Loader Time Clock
    participant API as Staff-Time API
    participant Staff as Staff-Time Service
    participant Assign as Assignment Release Helper
    database DB as MySQL
    participant QBT as QuickBooks Time

    Loader->>UI: Select Clock Out
    UI->>API: POST CLOCK_OUT
    API->>DB: Begin transaction
    API->>Staff: Create local CLOCK_OUT event
    Staff->>DB: Insert T_STAFF_TIME_EVENT
    API->>Assign: Release this Loader from SCHEDULED assignments
    Assign->>DB: Clear Loader/Telegram/queue fields on eligible planner rows
    DB-->>API: Local event + release result
    API->>DB: Commit
    API-->>QBT: Sync external timesheet after local commit
    API-->>UI: Return event and released assignment count
    UI-->>Loader: Refresh clock and work queue

    Note over Loader,QBT: Local Clock Out may succeed even when QuickBooks Time fails.

Policy still requiring approval

Can Clock Out proceed with an active job?
Can Clock Out proceed with an open Break?
Must the UI preview assignments that will be released?
Who owns re-assignment after release?
How is QuickBooks Time divergence displayed and reconciled?

7. Break Queue, Telegram And Expiry

Evidence: SR. Current Break rows reuse T_LOADING_PLANNER with SPECIAL_INSTRUCTION='QUEUE_BREAK'. Some read/list/timeline/cron paths can close expired Breaks; this is a migration concern.

sequenceDiagram
    autonumber
    actor Manager
    participant Board as Assignment Board
    participant BreakAPI as Break Queue API
    database DB as MySQL
    participant TG as Telegram
    actor Loader
    participant LoaderUI as Loader Page
    participant Staff as Staff-Time Ledger
    participant Expiry as Current Expiry Caller
    participant QBT as QuickBooks Time

    Manager->>Board: Add Break / Lunch for Loader
    Board->>BreakAPI: Create Break queue row
    BreakAPI->>DB: Insert compatibility planner row as SCHEDULED
    DB-->>BreakAPI: Break queue ID
    Manager->>BreakAPI: Send Break Telegram
    BreakAPI-->>TG: Provider send
    alt Telegram succeeds
        TG-->>BreakAPI: Sent
        BreakAPI->>DB: Set LAST_SENT_TIME
        DB-->>LoaderUI: Break becomes startable/visible
    else Telegram fails
        TG-->>BreakAPI: Failure / unknown
        BreakAPI-->>Manager: Local Break remains queued; notification unresolved
    end

    Loader->>LoaderUI: Start Break
    LoaderUI->>BreakAPI: POST break-queue/{id}/start
    BreakAPI->>DB: Conditional SCHEDULED -> STARTED
    BreakAPI->>Staff: Append BREAK_IN
    Staff-->>BreakAPI: Event result
    BreakAPI-->>QBT: Post-commit external sync

    Expiry->>DB: Find expired STARTED Breaks
    Expiry->>Staff: Append/repair BREAK_OUT
    Expiry->>DB: Mark Break finished
    Expiry-->>TG: Optionally notify next queued work

    Note over Expiry,QBT: TARGET should move expiry mutation to one deterministic worker/command, not ordinary reads.

8. Final Loading Review — Normal Confirm

Evidence: SR. Review state is separate from operational completion and inventory ledger authority.

sequenceDiagram
    autonumber
    actor Office
    participant UI as Final Loading Review UI
    participant API as WMS Review API
    participant Review as Review Policy Helper
    database DB as MySQL
    participant Ledger as Inventory Ledger Read

    Office->>UI: Select LA date and Pending Review
    UI->>API: GET bale-reviews
    API->>DB: Read completed Reload/Transload + planner state
    API->>Ledger: Read active non-reversed ledger relations
    Ledger-->>API: Source / Leftover / L2L evidence
    API->>Review: Derive DATA/SOURCE/LEFTOVER/WEIGHT/READY state
    Review-->>UI: Queue row, action and metrics

    Office->>UI: Confirm Final Loading
    UI->>API: POST bale-reviews/confirm
    API->>Review: Reread work, planner, metrics and ledger
    Review->>DB: Conditional PENDING -> CONFIRMED update
    DB-->>Review: One row changed
    Review-->>API: Confirmed review row
    API-->>UI: Success
    UI->>API: GET exact queue/detail state
    API->>DB: Reread review actor/time/status/reason
    DB-->>UI: CONFIRMED readback

    Note over Office,DB: Queue disappearance alone is not completion proof.

9. Final Loading Review — Source Or Leftover Resolution

Evidence: SR + DOC. Final Review references adjustment evidence but does not own lot/ledger mutation.

sequenceDiagram
    autonumber
    actor Office
    participant ReviewUI as Final Review UI
    participant ReviewAPI as Review API
    participant AdjustAPI as Bale Adjustment API
    participant Adjust as Adjustment Owner
    database DB as MySQL

    ReviewUI->>ReviewAPI: Load review state
    ReviewAPI-->>ReviewUI: SOURCE_REQUIRED or LEFTOVER_REQUIRED

    alt Extra Source required
        Office->>ReviewUI: Select approved planned Source and actual quantity
        ReviewUI->>AdjustAPI: Apply EXTRA_SOURCE
        AdjustAPI->>DB: Begin transaction
        AdjustAPI->>Adjust: Revalidate source eligibility and balance
        Adjust->>DB: Decrease source Lot + append Ledger event
        AdjustAPI->>DB: Commit
    else Leftover required
        Office->>ReviewUI: Confirm Loader-recorded actual location
        ReviewUI->>AdjustAPI: Create LEFTOVER
        AdjustAPI->>DB: Begin transaction
        Adjust->>DB: Create Leftover Lot + placement + Ledger evidence
        AdjustAPI->>DB: Commit
    end

    ReviewUI->>ReviewAPI: Reread review state
    ReviewAPI->>DB: Read current metrics and active ledger evidence
    DB-->>ReviewAPI: Reconciled state
    ReviewAPI-->>ReviewUI: READY_TO_CONFIRM or remaining exception
    Office->>ReviewUI: Confirm only when READY

    Note over ReviewAPI,AdjustAPI: Reopen changes review mutability; Void/Reversal changes inventory evidence. They are not the same command.

10. Final Loading Review — Unknown Confirm Result And Reopen

Evidence: SR + DOC.

sequenceDiagram
    autonumber
    actor Office
    participant UI
    participant API
    database DB

    Office->>UI: Submit Confirm
    UI->>API: POST confirm
    API--xUI: Timeout / response lost
    UI->>API: GET exact review row and queue scope
    API->>DB: Read status, actor, confirmed_at, reason
    DB-->>API: Current review row

    alt Status is CONFIRMED
        API-->>UI: Treat original Confirm as committed
        UI-->>Office: Do not repeat Confirm
    else Status is PENDING and readiness is READY
        API-->>UI: Original Confirm not committed
        UI-->>Office: Retry once with refreshed state
    else Status is PENDING but readiness changed
        API-->>UI: Show current blocking action
        UI-->>Office: Resolve new state before any Confirm
    end

    opt Later correction required
        Office->>UI: Reopen confirmed review
        UI->>API: POST reopen
        API->>DB: Set review to PENDING under current guard
        DB-->>API: Pending review readback
        API-->>UI: Reopened
        Note over Office,DB: Current source metadata-retention semantics require explicit policy review.
    end

11. Yard Dispatch — Non-Pull Move

Evidence: SR.

sequenceDiagram
    autonumber
    actor Office
    participant Dispatch as Yard Dispatch UI
    participant API as YMS Yard API
    database DB as MySQL
    actor YardDriver as Yard Truck Driver
    participant Map as Yard Map

    Office->>Dispatch: Create/edit queue item and destination
    Dispatch->>API: Create or update queue
    API->>DB: Commit QUEUED/SCHEDULED instruction
    DB-->>Dispatch: Queue readback

    YardDriver->>API: Claim scheduled queue item
    API->>DB: Conditional claim update
    DB-->>YardDriver: Claimed by current actor
    YardDriver->>YardDriver: Move physical item
    YardDriver->>API: Complete with actual destination
    API->>DB: Begin transaction
    API->>DB: Validate source, target, occupancy and claim
    API->>DB: Update Yard location + queue COMPLETED + mirrors
    API->>DB: Commit
    API-->>YardDriver: Completion response

    Office->>Dispatch: Refresh Completed queue
    Office->>Map: Refresh actual occupancy
    Note over Office,Map: Completed queue and Yard Map must agree with physical state.

12. Pull Out Closing — Partial Result Boundary

Evidence: SR. Current browser sends BMS closing first and YMS queue completion second.

sequenceDiagram
    autonumber
    actor YardDriver as Yard Truck Driver
    participant ClosingUI as Yard Closing UI
    participant BMS as BMS Closing API
    participant YMS as YMS Yard Completion API
    database DB as MySQL
    actor Office

    YardDriver->>ClosingUI: Enter photos, tare/scale and closing data
    ClosingUI->>BMS: POST closing scale ticket
    BMS->>DB: Commit closing / scale evidence
    DB-->>BMS: Closing saved
    BMS-->>ClosingUI: Success
    ClosingUI->>YMS: Complete claimed PULL_OUT queue

    alt Yard completion succeeds
        YMS->>DB: Commit queue completion and Yard effects
        DB-->>YMS: Completed
        YMS-->>ClosingUI: Success
        ClosingUI-->>YardDriver: Return to Yard Instruction
    else Yard completion fails or result is uncertain
        YMS--xClosingUI: Error / timeout
        ClosingUI-->>YardDriver: Do not resubmit whole closing form blindly
        YardDriver-->>Office: Report queue ID and equipment/load
        Office->>BMS: Reread closing/scale evidence
        Office->>YMS: Reread queue and Yard location
        Note over Office,DB: Resume only the missing boundary after evidence review.
    end

13. Queue After Clear

Evidence: SR + DOC. A business child may be complete while physical placement remains pending.

sequenceDiagram
    autonumber
    actor Operator
    participant Origin as Delivery or Yard Origin Command
    participant YMS as Yard Queue Service
    database DB as MySQL
    actor ClearingDriver as Yard Driver
    participant Map as Yard Map

    Operator->>Origin: Finish toward occupied target
    Origin->>YMS: Create queue-after-clear with target and origin identity
    YMS->>DB: Commit waiting queue
    DB-->>Origin: Queue ID and pending Yard result
    Origin-->>Operator: Origin child may report complete/pending Yard

    ClearingDriver->>YMS: Complete blocking move
    YMS->>DB: Update blocker location
    YMS->>DB: Detect eligible waiting queue
    YMS->>DB: Auto-complete waiting placement when guards pass
    DB-->>YMS: Completed or still blocked
    YMS-->>Map: Updated physical projection

    Operator->>YMS: Reread waiting queue
    Operator->>Map: Reread target occupancy
    Note over Origin,Map: Origin completion does not prove waiting Yard placement completed.

14. Conditional Yard-To-Driver Handoff

Evidence: SR + DOC.

sequenceDiagram
    autonumber
    actor Office
    participant Yard as Yard Dispatch / Map
    actor YardDriver as Yard Truck Driver
    participant DriverUI as Driver Page
    participant Delivery as Delivery API
    database DB as MySQL
    actor TruckDriver as Truck Operator

    Office->>Yard: Correlate queue, equipment and current location
    Yard-->>DriverUI: Active Yard queue projects Driver Start blocker
    YardDriver->>Yard: Complete/correct required Yard work
    Yard->>DB: Commit queue/location result
    DB-->>Yard: Current Yard state

    Office->>Yard: Reread no active blocker
    TruckDriver->>DriverUI: Refresh assigned delivery
    TruckDriver->>Delivery: Start scheduled Return/Relocate
    Delivery->>DB: Validate assigned actor and remaining Yard blocker
    Delivery->>DB: Commit DISPATCHED when allowed
    DB-->>Delivery: Started delivery
    Delivery-->>DriverUI: Start result

    Office->>Yard: Verify no unexplained occupancy/queue
    Office->>Delivery: Verify delivery is DISPATCHED
    Note over Office,TruckDriver: Yard complete makes Driver Start eligible; it does not start or complete delivery.

15. Driver Finish And Parking Checkpoints

Evidence: SR.

sequenceDiagram
    autonumber
    actor Driver
    participant UI as Driver Page
    participant Files as File Service
    participant Delivery as Delivery API
    participant Yard as Yard API
    participant TG as Telegram
    database DB as MySQL
    actor Office

    Driver->>Files: Upload required photo/evidence
    Files->>DB: Commit file object/link
    DB-->>Driver: Evidence visible

    alt External destination
        Driver->>Delivery: Finish delivery
        Delivery->>DB: Commit DELIVERED and equipment/load effects
    else Tenant Yard direct placement
        Driver->>Yard: Move/confirm actual Yard location
        Yard->>DB: Commit Yard effect
        Driver->>Delivery: Finish delivery in separate request
        Delivery->>DB: Commit DELIVERED
    else Return-to-CTC parking
        Driver->>Delivery: Request parking
        Delivery-->>TG: Notify Office/Driver within current effect boundary
        Office->>Delivery: Assign location
        Delivery-->>TG: Send assignment notification
        Driver->>Yard: Confirm parked / actual spot
        Yard->>DB: Commit Yard placement
        Driver->>Delivery: Complete delivery in later request
        Delivery->>DB: Commit DELIVERED
    end

    Driver->>UI: Refresh delivery, evidence and parking state
    Office->>Yard: Refresh Yard queue/location when applicable
    Note over Files,Office: Photo, provider notification, parking, Yard placement and delivery completion are independent checkpoints.

16. Target One-Writer Migration Sequence

Evidence: TARGET. This diagram is a migration requirement, not current implementation.

sequenceDiagram
    autonumber
    actor User
    participant Legacy as Current PHP UI/API
    participant Next as Next.js UI / Route Handler
    participant App as TypeScript Application Command
    participant Repo as MySQL Repository
    participant Shadow as Read/Parity Recorder
    participant Worker as Effect Worker

    User->>Next: Open migrated read surface
    Next->>Repo: Read current authoritative MySQL state
    Repo-->>Next: Typed projection
    Next-->>Shadow: Compare with legacy read during shadow phase

    alt Legacy remains writer
        User->>Legacy: Execute write
        Legacy->>Repo: Commit current command
        Next->>Repo: Reread result
    else New command is one writer
        User->>Next: Execute command
        Next->>App: Validate actor, state and idempotency
        App->>Repo: Conditional transaction
        Repo-->>App: Committed result
        App-->>Worker: Persist/emit effect intent after commit
        Next-->>User: Exact readback
    end

    opt Rollback required
        Next-->>User: Disable new write entry
        User->>Legacy: Resume legacy writer after compatibility check
        Legacy->>Repo: Continue from current DB state; no replay of completed side effects
    end

    Note over Legacy,Worker: Never run two independent writers for the same command.

17. Diagram Maintenance Rules

Update this catalog when any of the following changes:

• normal actor or entry point;
• command/query route;
• transaction boundary;
• state authority or stable identity;
• provider/file/device effect timing;
• partial-success behavior;
• retry/readback/Reopen/Undo/Void/Reversal path;
• process composition;
• target one-writer or rollback plan.

For every update:

1. name the source revision inspected;
2. update the owning atomic process contract first or in the same change;
3. distinguish current source from proposed target behavior;
4. keep unresolved policy as UNKNOWN or an explicit decision item;
5. update the affected operational Runbook and Wiki projection;
6. update the reconstruction data/interface/component map when an authority boundary changes;
7. preserve a simplified user-facing diagram and adjacent text when the process is published to the Wiki.

---

Source: docs/processes/PROCESS_SEQUENCE_DIAGRAM_CATALOG.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.