first review pass

Author: francisco-videira-nhs

CONTRIBUTING.md

@@ -45,3 +45,9 @@ GitHooks **must** be configured and run on commits before pushing to remote. Ref
 ## Testing Your Branch
 
 You can test your branch in a dynamic environment prior to merging to `main`. These are created as part of the `cicd-1-pull-request.yaml` workflow, triggered when a PR is created or updated.
+
+## Function Documentation
+
+Each Lambda and internal package has a `README.md` alongside the source describing its purpose, flow, integration points, and peculiarities. These are bundled into the docs site via `docs/generate-includes.sh`.
+
+When making changes to a Lambda or internal package, check whether the corresponding README needs updating. Function documentation is not auto-generated and can become stale if not maintained alongside code changes.

README.md

@@ -24,7 +24,6 @@ This repository documents the Supplier API specification and provides an SDK wit
     - [Packages](#packages)
     - [Documentation](#documentation)
     - [SDK Assets](#sdk-assets)
-    - [Examples](#examples)
   - [API Developers](#api-developers)
     - [Setup](#setup)
       - [Prerequisites and Configuration](#prerequisites-and-configuration)
@@ -64,10 +63,6 @@ If packages are unavailable the latest SDKs can be downloaded directly from:
   - TypeScript `sdk-ts-[Version].zip`
   - CSharp `sdk-csharp-[Version].zip`
 
-### Examples
-
-TODO:CCM-11209 Links to example clients.
-
 ## API Developers
 
 New developers of the NHS Notify Supplier API should understand the below.
@@ -153,6 +148,14 @@ by default they will be available at [http://localhost:3050](http://localhost:30
 
 These are generated using [https://hub.docker.com/r/openapitools/openapi-generator-cli](https://hub.docker.com/r/openapitools/openapi-generator-cli)
 
+### Unit Testing
+
+Run unit tests from the repository root:
+
+```bash
+npm run test:unit
+```
+
 ### Documentation
 
 - You can preview the OAS locally by running `make serve-oas`

config/suppliers/README.md

@@ -0,0 +1,35 @@
+# Supplier Configuration
+
+## Purpose
+
+Static JSON configuration files that define the supplier allocation rules for the Supplier API. These are loaded into DynamoDB by infrastructure tooling and are queried at runtime by the `supplier-allocator` Lambda. Check relevant repositories (nhs-notify-internal, nhs-notify-supplier-config) as they orchestrate supplier config data ingress depending on target account, environment, etc.
+
+## Configuration Entities
+
+| Entity | Directory | Description |
+| --- | --- | --- |
+| **Supplier** | `supplier/` | Print supplier definitions with ID, name, channel type, daily capacity, and status (PROD/DRAFT) |
+| **Letter Variant** | `letter-variant/` | Letter type definitions with physical constraints (sheets, sides, ink coverage, delivery days), associated pack specification IDs, and volume group assignment |
+| **Volume Group** | `volume-group/` | Groupings of letter variants for allocation purposes, with status and date range validity |
+| **Supplier Allocation** | `supplier-allocation/` | Maps a supplier to a volume group with a target `allocationPercentage` and status |
+| **Pack Specification** | `pack-specification/` | Detailed print assembly specs (paper, envelope, print colour, duplex) with constraints and billing ID |
+| **Supplier Pack** | `supplier-pack/` | Links a supplier to a pack specification with approval status |
+
+## Allocation Lookup Chain
+
+When the `supplier-allocator` Lambda processes a `LetterRequestPreparedEvent`:
+
+1. The event's `letterVariantId` identifies the **Letter Variant**.
+2. The variant's `volumeGroupId` identifies the **Volume Group** (must be `PROD` status and within date range).
+3. **Supplier Allocations** for that volume group determine which suppliers are eligible and their target allocation percentages (must sum to 100).
+4. The variant's `packSpecificationIds` are filtered by the letter's physical constraints.
+5. **Supplier Packs** confirm which eligible suppliers support the selected pack specification.
+6. The supplier with the lowest weighted allocation factor (furthest below their target share) is selected.
+
+## Nuances and Peculiarities
+
+- These files are the source of truth for the supplier config DynamoDB table (`SUPPLIER_CONFIG_TABLE_NAME`). Changes here flow into DynamoDB via infrastructure deployment.
+- Runtime persistence is event-driven: supplier-config events are routed through SQS to the `supplier-config-ingress` Lambda, which upserts records into the config table.
+- `status: "PROD"` is required at multiple levels (supplier, volume group, allocation) for an allocation to be active.
+- Volume groups have `startDate` (and optional `endDate`) fields. Allocations are only valid when the current date falls within this range (evaluated in London timezone).
+- Supplier `dailyCapacity` is tracked separately in `SUPPLIER_QUOTAS_TABLE` and resets at midnight London time. It is not stored in these config files.

docs/collections/_consumers/acceptance.md

@@ -616,7 +616,7 @@ Once you pass this stage, we'll confirm your readiness for going live.
 ### Letter Status Definitions
 
 | Status | Description | Initiated By | Mandatory/Optional
-|---|---|---|---|
+| --- | --- | --- | --- |
 | PENDING | Initial state for all new letters. Indicates that the letter has been allocated to a supplier but not yet retrieved or accepted | NHS Notify | Mandatory Starting Status |
 | REJECTED | Used when a supplier determines a letter cannot be processed  Occurs immediately after PENDING , before any production begins | Supplier | Conditional |
 | ACCEPTED | Letter has passed validation checks and is ready for production | Supplier | Mandatory (core workflow transition) |
@@ -632,7 +632,7 @@ Once you pass this stage, we'll confirm your readiness for going live.
 ### Possible Scenarios and Applicable Letter Statuses
 
 | Scenario | Description | Typical Status flow |
-|---|---|---|
+| --- | --- | --- |
 | Standard print and delivery | Letter specification successfully provided, letter printed, dispatch and delivered to patient. | a) PENDING → ACCEPTED → PRINTED → ENCLOSED → DISPATCHED → DELIVERED<br>b) PENDING → ACCEPTED → PRINTED → DISPATCHED → DELIVERED<br>c) PENDING → ACCEPTED → ENCLOSED → DISPATCHED → DELIVERED<br>d) PENDING → ACCEPTED → DISPATCHED |
 | Letter rejected by letter Supplier | Letter fails validation before acceptance by the letter supplier. | PENDING → REJECTED |
 | Cancelled by client | Client cancels production before dispatched. | a) PENDING → ACCEPTED → CANCELLED<br>b) PENDING → ACCEPTED → PRINTED → CANCELLED<br>c) PENDING → ACCEPTED → PRINTED → ENCLOSED → CANCELLED |

docs/collections/_developers/guides/function-readmes.md

@@ -0,0 +1,124 @@
+---
+title: Function Documentation
+nav_order: 6
+parent: Developer Guides
+has_children: false
+has_toc: true
+---
+
+This page bundles function-level README files from the Supplier API codebase.
+
+## Data Flow Overview
+
+Primary data flows passing through the system:
+
+### Inbound (letter allocation and creation)
+
+```
+LetterRequestPreparedEvent (SNS)
+  → supplier-allocator (SQS consumer)
+    → resolves supplier via weighted fair-share algorithm
+    → upsert-letter (SQS consumer)
+      → inserts letter record into DynamoDB (letters table)
+        → DynamoDB Stream → Kinesis
+          → update-letter-queue: adds PENDING letters to queue table
+          → letter-updates-transformer: publishes LetterStatusChangeEvent to SNS
+```
+
+### Supplier-facing (status updates)
+
+```
+Supplier calls GET /letters (api-handler)
+  → reads from pending queue table with visibility timeout
+Supplier calls PATCH /letters/{id} or POST /letters (api-handler)
+  → enqueues UpdateLetterCommand to SQS
+    → transformAmendmentEvent (SQS consumer, in api-handler package)
+      → fetches current letter, publishes LetterStatusChangeEvent to SNS
+    → upsert-letter (SQS consumer)
+      → updates letter status in DynamoDB (letters table)
+        → DynamoDB Stream → Kinesis
+          → update-letter-queue: removes letter from pending queue
+          → letter-updates-transformer: publishes LetterStatusChangeEvent to SNS
+```
+
+### MI submission
+
+```
+Supplier calls POST /mi (api-handler)
+  → persists MI record to DynamoDB (mi table)
+    → DynamoDB Stream → Kinesis
+      → mi-updates-transformer: publishes MISubmittedEvent to SNS
+```
+
+### Supplier config ingestion
+
+```
+Supplier config event (SNS, type prefix uk.nhs.notify.supplier-config)
+  → supplier-config SQS queue
+    → supplier-config-ingress (SQS consumer)
+      → upserts entity into supplier-config DynamoDB table
+```
+
+## Lambda Packages
+
+### API Handler
+
+{% include components/generated/readmes/lambda-api-handler.md %}
+
+### Authorizer
+
+{% include components/generated/readmes/lambda-authorizer.md %}
+
+### Supplier Allocator
+
+{% include components/generated/readmes/lambda-supplier-allocator.md %}
+
+### Upsert Letter
+
+{% include components/generated/readmes/lambda-upsert-letter.md %}
+
+### Update Letter Queue
+
+{% include components/generated/readmes/lambda-update-letter-queue.md %}
+
+### Letter Updates Transformer
+
+{% include components/generated/readmes/lambda-letter-updates-transformer.md %}
+
+### MI Updates Transformer
+
+{% include components/generated/readmes/lambda-mi-updates-transformer.md %}
+
+### Supplier Config Ingress
+
+{% include components/generated/readmes/lambda-supplier-config-ingress.md %}
+
+## Internal Packages
+
+### Datastore
+
+{% include components/generated/readmes/internal-datastore.md %}
+
+### Events
+
+{% include components/generated/readmes/internal-events.md %}
+
+### Event Builders
+
+{% include components/generated/readmes/internal-event-builders.md %}
+
+### Helpers
+
+{% include components/generated/readmes/internal-helpers.md %}
+
+## Tests
+
+{% include components/generated/readmes/tests-overview.md %}
+
+## Sandbox
+
+{% include components/generated/readmes/sandbox.md %}
+
+## Supplier Configuration
+
+{% include components/generated/readmes/config-suppliers.md %}

docs/generate-includes.sh

@@ -7,8 +7,32 @@ cd "$(git rev-parse --show-toplevel)"
 mkdir -p ./docs/_includes/components/generated
 
 # Database mermaid diagrams
+# NOTE: This also regenerates internal/datastore/src/types.md as a side effect.
+# Review any changes to that file before committing.
 npm run -w internal/datastore diagrams
 cp ./internal/datastore/src/types.md ./docs/_includes/components/generated/types.md
 
 #Contributing file
 cp ./CONTRIBUTING.md ./docs/_includes/components/generated/contributing.md
+
+# Function documentation (lambdas)
+mkdir -p ./docs/_includes/components/generated/readmes
+cp ./lambdas/api-handler/README.md ./docs/_includes/components/generated/readmes/lambda-api-handler.md
+cp ./lambdas/authorizer/README.md ./docs/_includes/components/generated/readmes/lambda-authorizer.md
+cp ./lambdas/supplier-allocator/README.md ./docs/_includes/components/generated/readmes/lambda-supplier-allocator.md
+cp ./lambdas/upsert-letter/README.md ./docs/_includes/components/generated/readmes/lambda-upsert-letter.md
+cp ./lambdas/update-letter-queue/README.md ./docs/_includes/components/generated/readmes/lambda-update-letter-queue.md
+cp ./lambdas/letter-updates-transformer/README.md ./docs/_includes/components/generated/readmes/lambda-letter-updates-transformer.md
+cp ./lambdas/mi-updates-transformer/README.md ./docs/_includes/components/generated/readmes/lambda-mi-updates-transformer.md
+cp ./lambdas/supplier-config-ingress/README.md ./docs/_includes/components/generated/readmes/lambda-supplier-config-ingress.md
+
+# Function documentation (internal packages)
+cp ./internal/datastore/README.md ./docs/_includes/components/generated/readmes/internal-datastore.md
+cp ./internal/events/README.md ./docs/_includes/components/generated/readmes/internal-events.md
+cp ./internal/event-builders/README.md ./docs/_includes/components/generated/readmes/internal-event-builders.md
+cp ./internal/helpers/README.md ./docs/_includes/components/generated/readmes/internal-helpers.md
+
+# Function documentation (other)
+cp ./tests/README.md ./docs/_includes/components/generated/readmes/tests-overview.md
+cp ./sandbox/README.md ./docs/_includes/components/generated/readmes/sandbox.md
+cp ./config/suppliers/README.md ./docs/_includes/components/generated/readmes/config-suppliers.md

internal/README.md

@@ -0,0 +1,18 @@
+# Internal Packages
+
+## Purpose
+
+This directory contains shared workspace packages that export code used by other packages in the repository (especially Lambda workspaces).
+
+These packages provide common schemas, datastore repositories, event builders, and helper utilities so implementation code can reuse a single source of truth.
+
+## What is here
+
+- `datastore/`: shared DynamoDB repositories, domain types, and related errors.
+- `events/`: shared event schemas and TypeScript types.
+- `event-builders/`: shared mappers/builders for CloudEvent payloads.
+- `helpers/`: shared logging, metrics, environment, and utility helpers.
+
+## Usage
+
+Import from these packages in other workspaces rather than duplicating logic locally.

internal/datastore/README.md

@@ -0,0 +1,28 @@
+# @internal/datastore
+
+## Purpose
+
+Shared data-access layer providing DynamoDB repository implementations, domain types, and error classes for the supplier API.
+
+## General Structure
+
+- **`src/types.ts`**: Zod schemas and TypeScript types for `Letter`, `InsertLetter`, `UpdateLetter`, `PendingLetter`, `MI`, `Supplier`, and related entities.
+- **`src/letter-repository.ts`**: `LetterRepository` — CRUD for the main letters DynamoDB table
+- **`src/letter-queue-repository.ts`**: `LetterQueueRepository` — manages the pending letter queue projection table:
+  - `getLetters`: paginated query with visibility-timeout update to prevent duplicate dispatch.
+- **`src/mi-repository.ts`**: `MIRepository` — writes MI records.
+- **`src/supplier-repository.ts`**: `SupplierRepository` — looks up suppliers by APIM application ID / supplierId.
+- **`src/supplier-config-repository.ts`**: `SupplierConfigRepository` — reads letter variants, volume groups, supplier allocations, pack specifications, and supplier packs from the config table.
+- **`src/supplier-quotas-repository.ts`**: `SupplierQuotasRepository` — reads and writes daily and overall allocation counts used by the supplier-allocator.
+- **`src/healthcheck.ts`**: `DBHealthcheck` — verifies DynamoDB table and S3 bucket connectivity.
+- **`src/errors/`**: Common application errors, which determine some of the API's error responses.
+
+## Key Integration Points
+
+- **`@nhsdigital/nhs-notify-event-schemas-supplier-config`**: Zod schemas for supplier configuration entities.
+- **Consumers**: every Lambda in this repository depends on this package.
+
+## Nuances and Peculiarities
+
+- The **letter queue table** is a separate DynamoDB table from the main letters table. It acts as a priority queue projection, maintained by the `update-letter-queue` Lambda from Kinesis stream events.
+- `LetterQueueRepository` implements a **visibility timeout** pattern: each returned letter's `visibilityTimestamp` is updated so subsequent queries within the timeout window skip it, preventing duplicate dispatch.

internal/event-builders/README.md

@@ -1,7 +1,19 @@
 # @internal/event-builders
 
-Helper utilities to produce supplier api event types.
+## Purpose
 
-This package contains functions for constructing CloudEvent-compliant event payloads and related helpers.
+Provides functions to construct CloudEvent-compliant payloads from domain entities. Centralises event-building logic so that multiple lambdas produce structurally identical events.
 
-Independent package to allow for type imports across the project without circular dependencies.
+## General Structure
+
+- **`src/letter-mapper.ts`**: exports `mapLetterToCloudEvent(letter, source)` which converts a `Letter` domain object into a full `LetterStatusChangeEvent` CloudEvent.
+
+## Key Integration Points
+
+- **Used by**: `letter-updates-transformer` (publish letter updates to core) and `amendment-event-transformer` (process incoming letter updates).
+
+## Nuances and Peculiarities
+
+- Each call to `mapLetterToCloudEvent` generates a fresh `randomUUID` for the event `id` and random bytes for `traceparent`, so the same letter domain object will produce a unique event every time it is called.
+- The `data.origin.event` field is set to the **new event ID** (not the original event that created the letter), establishing a fresh trace link per emission.
+- Independent package to allow for type imports across the project without circular dependencies.

internal/events/README.md

@@ -0,0 +1,29 @@
+# @nhsdigital/nhs-notify-event-schemas-supplier-api
+
+## Purpose
+
+Defines the Zod schemas and TypeScript types for all CloudEvents produced and consumed within the supplier API domain. Published externally as `@nhsdigital/nhs-notify-event-schemas-supplier-api` and used by both internal lambdas and external consumers.
+
+## General Structure
+
+- **`src/domain/letter.ts`**: defines the `$Letter` schema (extends `DomainBase`) and `$LetterStatus`.
+- **`src/domain/mi.ts`**: defines the `$MI` schema for management information records.
+- **`src/events/event-envelope.ts`**: the `EventEnvelope` factory that creates the main schema for any domain entity. Generates `type` as `uk.nhs.notify.supplier-api.<resource>.<status>.v1`, representing letter status change events and MI submissions.
+- **`src/events/letter-events.ts`**: exports the `$LetterStatusChangeEvent` schema for letter lifecycle events.
+- **`src/events/mi-events.ts`**: exports `$MISubmittedEvent` for MI submission CloudEvents.
+
+## Key Integration Points
+
+- `upsert-letter` uses `$LetterStatusChangeEvent` on its update path. The same handler uses letter-rendering schemas (`LetterRequestPreparedEvent` v1/v2) for inserts, so `LetterStatusChangeEvent` is the key discriminator for *update* processing.
+- `api-handler` (`transformAmendmentEvent`) emits `LetterStatusChangeEvent` after supplier update commands are accepted and enriched.
+- `letter-updates-transformer` emits `LetterStatusChangeEvent` for downstream consumers when a letter is inserted or when `status` or `reasonCode` changes.
+- Those published events are consumed through EventPub by Core (and any other downstream consumers).
+- Published to npm for external consumers who need to parse or validate supplier API events.
+
+## Nuances and Peculiarities
+
+- **`LetterStatusChangeEvent` is a central domain event, not just a transport type.** It links supplier-facing updates, async persistence, and outbound publication to Core.
+- **Supplier status updates become domain events.** When suppliers call `PATCH /letters/{id}` or `POST /letters`, the API handler enqueues `UpdateLetterCommand` messages. These are transformed into `LetterStatusChangeEvent` payloads and ultimately persisted by `upsert-letter`.
+- **Outbound lifecycle publication uses the same event shape.** `letter-updates-transformer` emits `LetterStatusChangeEvent` on letter INSERT and on `status`/`reasonCode` updates, which are then routed to downstream subscribers.
+- **Must remain free of internal dependencies.** Since this package is published externally, it cannot import from `@internal/datastore`, `@internal/helpers`, or any other internal workspace package. All types are self-contained.
+- **Schema version alignment**: the `dataschemaversion` in CloudEvents is derived from this package's `package.json` version, so bumping the package version directly affects the schema version in all emitted events. There's a GH workflow related to this.