How ministryofjustice/hmpps-digital-canteen-medusa-service works
This is an HMPPS Digital Canteen e-commerce backend built on Medusa. The principal workflow is a prison-facing client creating a PIN-phone cart, identifying or creating its prisoner/customer, adding phone credit, recording a BT payment outcome, and completing an order when authorised. Medusa supplies the commerce orchestration and persistence, while custom routes and modules handle prisoner linkage and payment status. The tree also documents an admin portal and an authenticated Digital Canteen API integration; those integrations are shown where supported by sampled source. Some framework internals were not sampled.
Components 18
API Surface
- Admin Portal
backend/src/admin - PIN Cart API
backend/src/api/store/pin-phone/carts/route.ts - Cart Items API
backend/src/api/store/pin-phone/carts/[id]/add-items/route.ts - Cart Completion API
backend/src/api/store/pin-phone/carts/[id]/complete/route.ts - Store Routes
backend/src/api/store/request-from-api/route.ts
Commerce Flow
- Medusa Commerce
backend/medusa-config.js - Cart Workflows
- Product Catalog
backend/src/api/store/pin-phone/carts/[id]/add-items/route.ts - Commerce Database
backend/medusa-config.js
Customer Identity
- Prisoner Service
backend/src/modules/prisoner-details/service.ts - Customer Module
backend/src/api/store/pin-phone/carts/route.ts - Customer Links
backend/src/api/store/pin-phone/carts/route.ts
Payment Processing
- BT Payment Provider
backend/src/modules/bt-payment/BtPaymentProviderService.ts - Payment Module
backend/src/api/store/pin-phone/carts/[id]/complete/route.ts
External Integrations
- Digital Canteen API
- API Client
backend/src/client/DigitalCanteenApiClient.ts - HMPPS Auth
backend/src/lib/hmpps-auth.ts
Other components
- Canteen Client
Connections 22
- Canteen Client → PIN Cart API: creates cart
- Canteen Client → Cart Items API: adds credit
- Canteen Client → Cart Completion API: submits payment
- PIN Cart API → Prisoner Service: finds prisoner
- PIN Cart API → Customer Module: creates customer
- PIN Cart API → Customer Links: links identities
- PIN Cart API → Medusa Commerce: creates cart
- PIN Cart API → Cart Workflows: runs workflow
- Cart Items API → Product Catalog: finds variant
- Cart Items API → Cart Workflows: adds item
- Cart Items API → Medusa Commerce: retrieves cart
- Cart Completion API → Medusa Commerce: retrieves cart
- Cart Completion API → Payment Module: creates session
- Cart Completion API → Cart Workflows: completes cart
- Payment Module → BT Payment Provider: dispatches payment
- Cart Workflows → Commerce Database: persists commerce
- Prisoner Service → Commerce Database: persists prisoner
- Customer Module → Commerce Database: persists customer
- Customer Links → Commerce Database: persists links
- Store Routes → API Client: calls API
- API Client → Digital Canteen API: requests data
- API Client → HMPPS Auth: gets token