03 — Business Processes

End-to-end walkthroughs of every workflow in the system. Each section follows the same shape:

1. What it is — one-paragraph summary in plain English.
2. Who's involved — the roles that drive each step.
3. State diagram — the formal lifecycle.
4. Step-by-step — each step with the actor, action, system effect, and notifications.
5. Cross-actor sequence — when more than one person hands off.
6. Edge cases & variations — branches the happy path doesn't show.
7. Notifications emitted — full list of events, recipients, and merge fields.

Index

1. Asset lifecycle
2. Audit process
3. Asset transfer process
4. Check-out / check-in process
5. Maintenance process
6. Notification flow (cross-cutting)

Asset lifecycle

What it is

The asset's full journey through the system, from the moment it's registered to the moment it's disposed. Most steps don't require a workflow gate — they happen as side effects of other processes (a transfer's Complete writes the new location, an audit's Approve writes a corrected location, a check-out flips the status to OnLoan).

Who's involved

• Super Admin registers new assets (via UI, by import, or via API).
• Field users (Auditors, Transfer participants, Custodians) drive the asset's history without ever clicking "Edit".
• Reviewers confirm corrections by approving audit lines.

State diagram

stateDiagram-v2
  [*] --> Active : Asset created (default status)
  Active --> Reserved : status change
  Reserved --> Active : status change
  Active --> OnLoan : Check-out created
  OnLoan --> Active : Check-in
  Active --> InMaintenance : Work Order Started
  InMaintenance --> Active : Work Order Completed
  Active --> Missing : Audit "NotFound" approved
  Missing --> Active : Found in next audit + approved
  Active --> OutOfService : status change
  OutOfService --> Active : status change
  OutOfService --> Disposed : Final state
  Active --> Disposed : Final state
  Disposed --> [*] : Terminal — no further changes

Step-by-step

History tables — every change leaves a trail

flowchart LR
  A[Asset record] --> AS[AssetStatusHistory<br/>OldStatus → NewStatus<br/>+ Source + SourceRefId]
  A --> AL[AssetLocationHistory<br/>OldLocation → NewLocation]
  A --> AO[AssetOrganizationHistory<br/>OldOrganization → NewOrganization]
  A --> AC[AssetCustodyHistory<br/>OldCustodian → NewCustodian]

When viewing /assets/:id → History tab, the user sees a single unified timeline merging all four tables, sorted newest first. Each row shows:

• When it happened
• Who triggered it (user that caused the change)
• What kind of change (status / location / org / custody)
• The before → after values
• The source — Manual (someone clicked Edit), Audit, Transfer, CheckOut, CheckIn, Maintenance, BulkImport, or System
• The source reference id — clickable to open the originating audit, transfer, work order, etc.

Edge cases

• Re-classifying an asset is not supported — the asset's Code is partly derived from its classification. To "re-classify", delete the asset (soft delete) and re-import under the correct classification. This is intentional and called out in the AuditOutcome enum docstring.
• Reactivating a disposed asset is technically allowed (an admin can change the status back to Active), but every such change is recorded in the audit log and shows up as a Manual source change in the asset's status history.
• Soft delete — when an admin deletes an asset, the row stays but is hidden everywhere by the global query filter. Reports don't see it. The code remains reserved (a freed code is never reissued).

Audit process

What it is

A planned physical inventory check. An Audit Planner designs the scope (which assets to audit), assigns it to an auditor (desktop or mobile), the auditor records what they found in the field, a reviewer approves or rejects each line, and approved corrections write back to the asset records.

Who's involved

State diagram (Plan)

stateDiagram-v2
  [*] --> Draft : Plan created
  Draft --> Scheduled : First assignment created
  Scheduled --> InProgress : First result submitted
  InProgress --> Completed : Last assignment fully reviewed
  Draft --> Cancelled
  Scheduled --> Cancelled
  InProgress --> Cancelled
  Completed --> [*]

State diagram (Assignment)

stateDiagram-v2
  [*] --> Assigned : Audit Planner assigns
  Assigned --> Downloaded : Mobile downloads template
  Downloaded --> InProgress : First scan / save draft
  InProgress --> Submitted : Auditor clicks Submit
  Submitted --> InReview : Reviewer opens it
  InReview --> Completed : All lines reviewed
  Assigned --> Cancelled
  Downloaded --> Cancelled
  InProgress --> Cancelled

Step-by-step

sequenceDiagram
  participant P as Audit Planner
  participant SYS as System
  participant A as Auditor / Mobile Auditor
  participant R as Audit Reviewer
  participant ASSET as Asset record

  P->>SYS: 1. Create Plan with scope rules
  SYS->>SYS: Resolve asset count (preview)
  P->>SYS: 2. Create Assignment for plan + assign user
  SYS->>SYS: Snapshot expected state per asset
  SYS->>A: Notification "audit.assigned"

  A->>SYS: 3. Open assignment, scan/type each asset
  SYS->>SYS: Auto-save draft every 1s of inactivity
  A->>SYS: 4. Submit (with idempotency key)
  SYS->>SYS: Result + lines persisted; assignment → Submitted
  SYS->>R: Notification "audit.result.review-required"

  R->>SYS: 5. Open result, review each line
  R->>SYS: 6. Approve / Reject / Modify line
  alt All lines decided
    SYS->>ASSET: Write back observed values<br/>(status, location, org)
    SYS->>SYS: Assignment → Completed; Plan rolls up
    SYS->>A: Notification "audit.result.approved"
  end

Detailed action table

Audit outcomes — what each one means

Classification mismatch is intentionally not an outcome — see §Asset lifecycle edge cases above.

Cross-actor sequence — mobile audit with photo

sequenceDiagram
  autonumber
  participant M as Mobile Auditor
  participant API as System
  participant FS as File storage

  M->>API: GET /mobile/assignment/:id
  API->>M: Expected assets + location chain
  M->>API: GET /draft (resume previous session)
  API->>M: Saved scan state JSON

  loop Walk the floor
    M->>M: Scan QR (camera)
    M->>M: Beep + vibrate (per outcome)
    M->>API: Auto-save draft (debounced 1s)
    API->>API: Persist DraftPayload
  end

  M->>API: POST photo (multipart)
  API->>FS: Store file
  API->>M: documentId
  Note over M: Pin documentId on the row

  M->>API: POST /audit-results (with clientSubmissionId)
  API->>API: Validate idempotency
  API->>API: Create result + lines + photo links
  API->>API: Clear DraftPayload
  API->>M: Result summary

Edge cases & variations

• No connectivity — Mobile shell shows "draft saved" with a stale timestamp. Auditor keeps scanning; the next save retries automatically.
• Excel offline path — Mobile screen offers "Download template / Fill offline / Upload back". The Excel file pre-fills with expected assets; auditor edits cells; system parses and submits via the same idempotent pipeline.
• Reviewer wants to reject the entire submission — there's no single button. The reviewer rejects each line, after which the assignment still flips to Completed (the act of deciding completes it; rejection means "no write-back"). The auditor can be re-assigned by the planner for a redo.
• Auditor disagrees with a rejection — out-of-band conversation; nothing in the system enforces a re-submission flow. The reviewer can change their decision (a new AuditReviewAction row is added; latest wins).
• Plan with multiple assignments — multiple auditors covering disjoint sub-scopes. Plan rolls up to Completed only when all assignments are Completed. (The system enforces only-one-active-assignment-per-plan, but multiple cancelled + one active + plus more later is fine.)

Notifications emitted

Asset transfer process

What it is

A formal request to move one or more assets from one organization or location to another. Goes through approval before the assets are actually marked "in transit", then a separate "receive" step at the destination confirms arrival, then "complete" writes the new location/organization back to each asset.

Who's involved

• Transfer Requester initiates the move (Draft → Submit).
• Transfer Approver decides go/no-go (Approve → InTransit, or Reject).
• Transfer Receiver marks lines received and completes the transfer (writes asset records).

State diagram

stateDiagram-v2
  [*] --> Draft : Created
  Draft --> Submitted : Submit
  Submitted --> Approved : Approve
  Approved --> InTransit : (auto, same handler)
  InTransit --> Completed : Complete (after all lines received)
  Submitted --> Rejected : Reject (with reason)
  Draft --> Cancelled : Cancel
  Submitted --> Cancelled : Cancel
  Completed --> [*]
  Rejected --> [*]
  Cancelled --> [*]

Approved → InTransit is automatic — the Approve handler bumps both states in one save. Users see the transfer flip directly from Submitted to InTransit; the Approved state is barely visible in the UI.

Step-by-step

sequenceDiagram
  autonumber
  participant REQ as Transfer Requester
  participant APP as Transfer Approver
  participant REC as Transfer Receiver
  participant SYS as System
  participant ASSETS as Asset records

  REQ->>SYS: Create transfer (Draft) with from/to + reason + lines
  REQ->>SYS: Submit → status = Submitted
  SYS->>APP: Notify "transfer.pending"

  alt Approver approves
    APP->>SYS: Approve → status = InTransit
    SYS->>REQ: Notify "transfer.approved"
    SYS->>REC: Notify "transfer.approved"

    loop Lines arrive at destination
      REC->>SYS: ReceiveLine (Ok / Damaged / Missing + notes)
    end

    REC->>SYS: Complete → status = Completed
    SYS->>ASSETS: Write new location + organization<br/>Write history rows (Source=Transfer)
    SYS->>REQ: Notify "transfer.completed"
  else Approver rejects
    APP->>SYS: Reject (with reason)
    SYS->>REQ: Notify "transfer.rejected"
  else Requester cancels
    REQ->>SYS: Cancel
  end

Detailed action table

Receive line statuses

Edge cases & variations

• Approver wants edits — the system has no "request changes" state. Rejecting with a reason is the closest path; the requester re-creates a corrected transfer.
• Partial receive — Receiver can mark some lines now, others tomorrow. Complete is gated on every line having a ReceivedAt. The transfer stays in InTransit until then.
• Cancel after approval — not directly supported. The path is to Complete with all lines as Missing, then file a corrective transfer to put them back. (asset-transfer.cancel only applies to Draft / Submitted.)
• Re-submit after rejection — no explicit re-open. The requester creates a new transfer (the rejected one stays as a permanent record).

Notifications emitted

Check-out / check-in process

What it is

Issuing an asset to a person ("check-out") and getting it back ("check-in"). Independent from transfers — a check-out doesn't change the asset's home location, just records who currently holds it.

Who's involved

• Checkout Issuer creates check-outs.
• Checkout Returner accepts returns.
• Asset Custodian (the recipient) holds the asset and reads their own list.

State diagram

stateDiagram-v2
  [*] --> Active : Issuer creates check-out
  Active --> Returned : Returner checks in
  Active --> Overdue : ExpectedReturnAt < now (computed)
  Active --> Cancelled : Issuer cancels
  Active --> Lost : Issuer marks lost
  Returned --> [*]
  Cancelled --> [*]
  Lost --> [*]

Overdue is computed, not persisted. The check-out list filters or flags rows where Status = Active and ExpectedReturnAt < now. There's no scheduled job that rewrites the status.

Step-by-step

Edge cases & variations

• Already overdue when returned — the system doesn't penalize; the check-out becomes Returned. Reports show that days-overdue history.
• Lost asset — the issuer can mark Status = Lost (manual transition; not automatic). Asset's status typically gets manually set to Missing after.
• Cancel an active check-out — Issuer cancels; status reverts (same restore logic as a check-in but without condition + notes).

Notifications emitted

None by default. Adding one (e.g., "your asset is overdue") would mean adding a new template key + a scheduled job to publish it. Not in scope today.

Maintenance process

What it is

Three-layer model: Plans (recurring schedules), Requests (user-filed reports), Work Orders (the actual job).

Who's involved

Reminder: Maintenance has no seeded workflow role. The default install puts every maintenance permission on Super Admin only. See 02 §Maintenance for proposed custom roles.

State diagrams

Maintenance Plan (recurring)

stateDiagram-v2
  [*] --> Active
  Active --> Active : Generate work orders<br/>(NextDueDate must be ≤ now)
  Active --> Inactive : Disable
  Inactive --> Active : Re-enable

Maintenance Request

stateDiagram-v2
  [*] --> Open : Custodian files
  Open --> UnderReview : Reviewer opens it
  UnderReview --> PromotedToWorkOrder : Reviewer promotes
  UnderReview --> Rejected : Reviewer rejects (with reason)
  Open --> Cancelled : Reporter cancels (if granted)
  PromotedToWorkOrder --> [*]
  Rejected --> [*]
  Cancelled --> [*]

Work Order

stateDiagram-v2
  [*] --> Open : Created without assignee
  [*] --> Assigned : Created with vendor (DefaultVendor on plan)
  Open --> Assigned : Assign user/vendor
  Assigned --> InProgress : Start
  InProgress --> Completed : Complete (with cost + notes)
  InProgress --> OnHold : Pause
  OnHold --> InProgress : Resume
  Open --> Cancelled
  Assigned --> Cancelled
  OnHold --> Cancelled
  Completed --> [*]
  Cancelled --> [*]

Plan-driven flow

sequenceDiagram
  autonumber
  participant MP as Maintenance Planner
  participant SYS as System
  participant T as Technician
  participant ASSET as Asset records

  MP->>SYS: Create Plan (multi-asset, frequency, default vendor)
  Note over SYS: NextDueDate = today
  loop Every cycle
    MP->>SYS: Click "Generate work orders"
    Note over SYS: Refused if NextDueDate > now
    SYS->>SYS: Create one WorkOrder per plan-asset<br/>(Origin=Plan, OriginRefId=planId)
    SYS->>SYS: LastPerformedDate=now<br/>NextDueDate += frequency
    SYS->>T: Notification "work-order.assigned"<br/>(if assigned)
    T->>SYS: Start WO → asset Status=InMaintenance
    T->>SYS: Complete WO with cost + notes
    SYS->>ASSET: Restore asset status to PreviousStatusId
  end

Request-driven flow

sequenceDiagram
  autonumber
  participant U as Reporter
  participant R as Maintenance Reviewer
  participant T as Technician
  participant SYS as System

  U->>SYS: Create Request (asset, severity, summary, description)
  Note over SYS: Status = Open
  R->>SYS: Open & investigate
  Note over SYS: Status = UnderReview

  alt Promote to Work Order
    R->>SYS: Promote (with WO type, priority, schedule, assignee)
    SYS->>SYS: Create WorkOrder; link request<br/>Status = PromotedToWorkOrder
    SYS->>T: Notification "work-order.assigned"
  else Reject
    R->>SYS: Reject (with reason)
  end

Detailed action tables

Plan handling

Request handling

Work order execution

Edge cases & variations

• Plan generates while a previous batch is still open — the system allows it. Frequency-based plans don't gate on prior completion. If a quarterly plan generates, technicians are halfway done with the previous batch, and another quarter rolls around — both batches are open at once. (Add a custom check if you don't want this.)
• Multi-asset plan with one missing asset — the generate command emits work orders for every plan-asset row that still resolves. If a plan-asset row points at a soft-deleted asset, that work order is skipped silently.
• Cost rollup — the system stores LaborCost and PartsCost separately, plus a denormalized TotalCost set at complete time. Currency is per-WO, not normalized.

Notifications emitted

There's no notification on Maintenance Request submission or rejection out of the box. Add custom templates if you want them.

Notification flow (cross-cutting)

What it is

How an event becomes an in-app notification + an optional email.

Who's involved

Template structure

Each template has up to two rows:

Both subjects and bodies are bilingual: *Primary (configurable language) + *Secondary. The recipient's PreferredLanguage decides which one renders.

Merge fields

Every template can reference {{ field.path }} placeholders. Fields the system auto-injects for every notification:

The publishing handler can also push entity-specific fields (e.g., transfer.code, transfer.reason, approver.name) — see each process section above for the full list per template key.

Delivery flow

sequenceDiagram
  participant H as Domain handler
  participant NS as Notification service
  participant DB as Database
  participant W as Delivery worker
  participant SMTP as SMTP server
  participant U as Recipient

  H->>NS: PublishAsync(templateKey, recipients, mergeFields)
  NS->>DB: Look up template by key
  NS->>NS: Render subject + body (per recipient language)
  loop Each recipient
    NS->>DB: Insert Notification (in-app, plain text)
    alt Email channel enabled & recipient has email
      NS->>DB: Insert NotificationDelivery (Status=Queued)
    end
  end

  Note over W: Polls every 15s
  W->>DB: Select NotificationDelivery WHERE Status=Queued AND NextAttemptAt<=now
  loop Each delivery
    W->>SMTP: Send
    alt Success
      W->>DB: Status=Sent, ProviderMessageId
    else Failure
      W->>DB: Attempts++, NextAttemptAt = backoff
      Note over W: After MaxAttempts → Failed
    end
  end

  U->>U: Sees bell badge increment (next 60s poll)
  U->>U: Reads inbox or opens email

Recipient targeting

Three publish modes:

User preferences

Every recipient can opt out of a specific template on a specific channel. At /preferences, they see a grid: each row is a template key from the NotificationEventCatalog, columns for InApp and Email.

The default (no preference row) is enabled — opt-out, not opt-in.

Edge cases & variations

• Recipient has no email — Email delivery is skipped (logged, no error).
• Email channel disabled at the template level (IsActive = false) — no email queued.
• SMTP master switch (EmailProviderSettings.Enabled = false) — worker idles, queue accumulates. Re-enabling drains.
• Staging redirect (RedirectAllEnabled = true) — every email reroutes to RedirectAllToAddress, original recipient prefixed in the subject. Useful when most user accounts in staging have fake emails.
• Quill-in-template gotcha — the admin template editor wraps text in <p>...</p> and inserts  . The renderer normalizes both to plain space before substituting merge fields, otherwise placeholders like {{ transfer.code }} would never match. For InApp output, HTML is stripped after substitution; Email keeps the HTML.

Where to go next