# defra/waste-movement-backend architecture

> Architecture diagram of the GitHub repository defra/waste-movement-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/defra/waste-movement-backend
- Repository: https://github.com/defra/waste-movement-backend

## Overview

This is an internal DEFRA Digital Waste Tracking backend: the external API calls it to persist waste receipt movements, while this service stores current records and audit history in MongoDB. Its runtime surface includes versioned movement, collection, delivery and receipt routes; bulk operations; organization and payload validation; and production-approval scenarios. The graph preserves those documented and indexed capabilities. Some service implementations were not excerpted, so their internal calls are omitted where the available evidence does not establish them.

Main entry points: [`src/services`](https://github.com/defra/waste-movement-backend/tree/main/src/services) (Movement services), [`src/plugins/router.js`](https://github.com/defra/waste-movement-backend/blob/main/src/plugins/router.js) (Route registry), [`src/routes`](https://github.com/defra/waste-movement-backend/tree/main/src/routes) (Movement endpoints), [`src/routes/create-bulk-receipt-movement.js`](https://github.com/defra/waste-movement-backend/blob/main/src/routes/create-bulk-receipt-movement.js) (Bulk create)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and routing"]
  node_backend["Backend server<br/>[server.js]"]
  node_router["Route registry<br/>[router.js]"]
end

subgraph group_movement["Movement workflows"]
  node_versioned_routes["Versioned journeys"]
  node_movement_routes["Movement endpoints"]
  node_bulk_create_route["Bulk create"]
  node_bulk_update_route["Bulk update"]
  node_movement_services["Movement services"]
  node_mongo[("MongoDB")]
  node_audit_history["Movement history<br/>[movement-update.js]"]
end

subgraph group_delivery["Delivery workflows"]
  node_delivery_route["Record delivery<br/>[record-delivery.js]"]
  node_delivery_service["Delivery persistence<br/>[delivery.js]"]
  node_tracking_id_service["Tracking ID service"]
end

subgraph group_support["Validation and approval"]
  node_schemas["Request schemas"]
  node_validator["Schema validation<br/>[hapi-validator.js]"]
  node_org_validation["Organization validation"]
  node_production_routes["Approval endpoints"]
  node_approval_runner["Approval scenarios"]
end

node_external_api["External API"]

node_external_api -->|"calls internally"| node_backend
node_backend -->|"registers routes"| node_router
node_router -->|"registers journeys"| node_versioned_routes
node_router -->|"registers endpoints"| node_movement_routes
node_movement_routes -->|"delegates operations"| node_movement_services
node_bulk_create_route -->|"creates movements"| node_movement_services
node_bulk_update_route -->|"updates movements"| node_movement_services
node_movement_services -->|"persists movements"| node_mongo
node_movement_services -->|"maintains history"| node_audit_history
node_audit_history -->|"stores audit trail"| node_mongo
node_delivery_route -->|"records deliveries"| node_delivery_service
node_delivery_service -->|"writes records"| node_mongo
node_delivery_route -->|"loads movements"| node_movement_services
node_movement_services -.->|"requests identifiers"| node_tracking_id_service
node_movement_routes -->|"validates requests"| node_validator
node_bulk_create_route -->|"uses bulk schema"| node_schemas
node_validator -->|"checks schemas"| node_schemas
node_movement_routes -->|"resolves organization"| node_org_validation
node_bulk_update_route -->|"checks organization"| node_org_validation
node_router -->|"registers approval routes"| node_production_routes
node_production_routes -->|"runs scenarios"| node_approval_runner

click node_backend "https://github.com/defra/waste-movement-backend/blob/main/src/server.js"
click node_router "https://github.com/defra/waste-movement-backend/blob/main/src/plugins/router.js"
click node_versioned_routes "https://github.com/defra/waste-movement-backend/tree/main/src/routes"
click node_movement_routes "https://github.com/defra/waste-movement-backend/tree/main/src/routes"
click node_bulk_create_route "https://github.com/defra/waste-movement-backend/blob/main/src/routes/create-bulk-receipt-movement.js"
click node_bulk_update_route "https://github.com/defra/waste-movement-backend/blob/main/src/routes/update-bulk-receipt-movement.js"
click node_movement_services "https://github.com/defra/waste-movement-backend/tree/main/src/services"
click node_delivery_route "https://github.com/defra/waste-movement-backend/blob/main/src/routes/beta-2/record-delivery.js"
click node_delivery_service "https://github.com/defra/waste-movement-backend/blob/main/src/services/delivery.js"
click node_schemas "https://github.com/defra/waste-movement-backend/tree/main/src/schemas"
click node_validator "https://github.com/defra/waste-movement-backend/blob/main/src/schemas/validate/hapi-validator.js"
click node_org_validation "https://github.com/defra/waste-movement-backend/tree/main/src/common/helpers"
click node_production_routes "https://github.com/defra/waste-movement-backend/blob/main/src/routes/production-approval-tests.js"
click node_approval_runner "https://github.com/defra/waste-movement-backend/tree/main/src/services/production-approval-tests"
click node_audit_history "https://github.com/defra/waste-movement-backend/blob/main/src/services/movement-update.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend,node_router toneBlue
class node_versioned_routes,node_movement_routes,node_bulk_create_route,node_bulk_update_route,node_movement_services,node_mongo,node_audit_history toneAmber
class node_delivery_route,node_delivery_service,node_tracking_id_service,node_external_api toneMint
class node_schemas,node_validator,node_org_validation,node_production_routes,node_approval_runner toneRose
```

## Components

### Runtime and routing

- [Backend server](https://github.com/defra/waste-movement-backend/blob/main/src/server.js): `src/server.js`
- [Route registry](https://github.com/defra/waste-movement-backend/blob/main/src/plugins/router.js): `src/plugins/router.js`

### Movement workflows

- [Versioned journeys](https://github.com/defra/waste-movement-backend/tree/main/src/routes): `src/routes`
- [Movement endpoints](https://github.com/defra/waste-movement-backend/tree/main/src/routes): `src/routes`
- [Bulk create](https://github.com/defra/waste-movement-backend/blob/main/src/routes/create-bulk-receipt-movement.js): `src/routes/create-bulk-receipt-movement.js`
- [Bulk update](https://github.com/defra/waste-movement-backend/blob/main/src/routes/update-bulk-receipt-movement.js): `src/routes/update-bulk-receipt-movement.js`
- [Movement services](https://github.com/defra/waste-movement-backend/tree/main/src/services): `src/services`
- **MongoDB**
- [Movement history](https://github.com/defra/waste-movement-backend/blob/main/src/services/movement-update.js): `src/services/movement-update.js`

### Delivery workflows

- [Record delivery](https://github.com/defra/waste-movement-backend/blob/main/src/routes/beta-2/record-delivery.js): `src/routes/beta-2/record-delivery.js`
- [Delivery persistence](https://github.com/defra/waste-movement-backend/blob/main/src/services/delivery.js): `src/services/delivery.js`
- **Tracking ID service**

### Validation and approval

- [Request schemas](https://github.com/defra/waste-movement-backend/tree/main/src/schemas): `src/schemas`
- [Schema validation](https://github.com/defra/waste-movement-backend/blob/main/src/schemas/validate/hapi-validator.js): `src/schemas/validate/hapi-validator.js`
- [Organization validation](https://github.com/defra/waste-movement-backend/tree/main/src/common/helpers): `src/common/helpers`
- [Approval endpoints](https://github.com/defra/waste-movement-backend/blob/main/src/routes/production-approval-tests.js): `src/routes/production-approval-tests.js`
- [Approval scenarios](https://github.com/defra/waste-movement-backend/tree/main/src/services/production-approval-tests): `src/services/production-approval-tests`

### Other components

- **External API**

## Connections

- External API → Backend server: calls internally (evidence: `README.md`)
- Backend server → Route registry: registers routes (evidence: `src/server.js`)
- Route registry → Versioned journeys: registers journeys (evidence: `src/plugins/router.js`)
- Route registry → Movement endpoints: registers endpoints (evidence: `src/plugins/router.js`)
- Movement endpoints → Movement services: delegates operations (evidence: `src/routes/beta-1/record-delivery.js`)
- Bulk create → Movement services: creates movements (evidence: `src/routes/create-bulk-receipt-movement.js`)
- Bulk update → Movement services: updates movements (evidence: `src/routes/update-bulk-receipt-movement.js`)
- Movement services → MongoDB: persists movements (evidence: `README.md`)
- Movement services → Movement history: maintains history (evidence: `README.md`)
- Movement history → MongoDB: stores audit trail (evidence: `README.md`)
- Record delivery → Delivery persistence: records deliveries (evidence: `src/routes/beta-2/record-delivery.js`)
- Delivery persistence → MongoDB: writes records (evidence: `src/services/delivery.js`)
- Record delivery → Movement services: loads movements (evidence: `src/routes/beta-2/record-delivery.js`)
- Movement services → Tracking ID service: requests identifiers
- Movement endpoints → Schema validation: validates requests (evidence: `src/routes/beta-2/record-delivery.js`)
- Bulk create → Request schemas: uses bulk schema (evidence: `src/routes/create-bulk-receipt-movement.js`)
- Schema validation → Request schemas: checks schemas (evidence: `src/schemas/validate/hapi-validator.js`)
- Movement endpoints → Organization validation: resolves organization (evidence: `src/routes/beta-2/record-delivery.js`)
- Bulk update → Organization validation: checks organization (evidence: `src/routes/update-bulk-receipt-movement.js`)
- Route registry → Approval endpoints: registers approval routes (evidence: `src/plugins/router.js`)
- Approval endpoints → Approval scenarios: runs scenarios (evidence: `src/routes/production-approval-tests.js`)