Deliveries¶

Status: Specified — ready to build Build order: 9 of 10 — depends on Projects & Sites

Purpose¶

Deliveries is the materials intake log for a site. Each delivery is recorded at the point of receipt — what was delivered, by whom, in what condition, and against which order or reference. Photos of the delivery (including any damage) are attached at the time of receipt. The log gives the project a complete record of materials arriving on site and supports claims under NEC compensation events where delivery conditions are disputed.

Entities¶

Delivery¶

One record per delivery event at a site.

CREATE INDEX idx_deliveries_site_id
    ON deliveries(site_id, delivered_at DESC) WHERE deleted_at IS NULL;
CREATE INDEX idx_deliveries_project_id
    ON deliveries(project_id, delivered_at DESC) WHERE deleted_at IS NULL;
CREATE INDEX idx_deliveries_condition
    ON deliveries(site_id, condition) WHERE deleted_at IS NULL;

Condition values:

DeliveryPhoto¶

Photos attached to a delivery record.

CREATE INDEX idx_delivery_photo_delivery
    ON delivery_photos(delivery_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_delivery_photo_project
    ON delivery_photos(project_id, taken_at DESC) WHERE deleted_at IS NULL;

Business Rules¶

1. delivered_at is set by the user — it records when the delivery arrived on site, not when the record was created. It can be set to any time on the current day or a past date (not future).

2. condition_notes is required when condition is damaged or rejected. A delivery with condition = damaged without condition_notes → 422.

3. photo_count is denormalised on the Delivery record and kept in sync by the photo add/delete operations. It is not recomputed from child records on every list query.

4. There is no sign-off workflow for deliveries. The record is created and remains editable until soft-deleted. Audit trail via updated_by / updated_at is sufficient.

5. received_by defaults to the authenticated user creating the record. Project Managers can set received_by to another user (for retrospective entry). Site Managers can only set received_by to themselves.

6. Deliveries are not linked to the Documents or Plant modules in V1. The description field is free text. Cross-referencing with purchase orders or delivery notes is a V2 feature.

7. Up to 20 photos per delivery. The 21^st upload → 422.

8. Soft deleting a delivery soft-deletes all its photos in the same transaction.

API Endpoints¶

Deliveries¶

Photos¶

Project-level view¶

Request / Response Shapes¶

POST /sites/{siteId}/deliveries¶

// Request
{
  "reference": "DN-2026-1042",
  "delivered_at": "2026-05-28T10:30:00Z",
  "supplier": "Hanson UK",
  "description": "Ready-mix concrete C30/37 — 24 m³ for pad foundations P7–P12",
  "quantity": "24 m³",
  "condition": "acceptable",
  "condition_notes": null,
  "custom_fields": {}
}

// Response 201
{
  "id": "uuid-delivery",
  "site_id": "uuid-site",
  "project_id": "uuid-project",
  "reference": "DN-2026-1042",
  "delivered_at": "2026-05-28T10:30:00Z",
  "supplier": "Hanson UK",
  "description": "Ready-mix concrete C30/37 — 24 m³ for pad foundations P7–P12",
  "quantity": "24 m³",
  "condition": "acceptable",
  "condition_notes": null,
  "received_by": "uuid-user",
  "received_by_name": "James Fletcher",
  "photo_count": 0,
  "custom_fields": {},
  "created_at": "2026-05-28T10:35:00Z"
}

GET /sites/{siteId}/deliveries¶

Query params: condition (acceptable|damaged|rejected), from_date, to_date, supplier (partial match), q (description/reference search), sort (default -delivered_at), limit, cursor

// Response 200
{
  "data": [
    {
      "id": "uuid-delivery",
      "reference": "DN-2026-1042",
      "delivered_at": "2026-05-28T10:30:00Z",
      "supplier": "Hanson UK",
      "description": "Ready-mix concrete C30/37 — 24 m³ for pad foundations P7–P12",
      "quantity": "24 m³",
      "condition": "acceptable",
      "condition_notes": null,
      "received_by_name": "James Fletcher",
      "photo_count": 3,
      "created_at": "2026-05-28T10:35:00Z"
    }
  ],
  "pagination": { "total": 18, "cursor": null, "has_more": false }
}

Permission Matrix¶

Notifications Triggered¶

None. The Deliveries module does not fire any notifications.

Offline Sync Scope¶

Offline create flow: - Site Manager creates delivery record on device, writes to local SQLite - Photos captured offline are stored in device storage - On reconnect: delivery record and photos upload sequentially

Cross-Module Dependencies¶

Upstream¶

Downstream¶

None. Deliveries is a terminal module.

Tests Required¶

Deliveries¶

• Create delivery — valid payload → 201
• Create delivery — condition = damaged, no condition_notes → 422
• Create delivery — condition = rejected, no condition_notes → 422
• Create delivery — delivered_at in the future → 422
• List deliveries — filter by condition, from_date, to_date
• q search matches description and reference
• Update delivery — PATCH semantics
• Soft delete — excluded from list

Photos¶

• Add photo — returns presigned PUT URL
• List photos — ordered by sort_order
• Update caption — success
• Delete photo — soft delete; photo_count decremented on delivery
• Maximum 20 photos — 21^st upload → 422

Cross-tenant isolation (mandatory)¶

• GET delivery from another tenant's site → 404
• POST delivery with site_id from another tenant → 404
• POST photo on a delivery from another tenant → 404

Permission boundaries¶

• Site Manager can create delivery → 201
• Site Manager cannot delete delivery → 403
• Viewer cannot create or edit → 403
• Viewer can view deliveries and photos → 200

Default Tenant Labels¶

Foundation Dependencies¶