CCM-17943: Add function Readme documentation#608
Open
francisco-videira-nhs wants to merge 1 commit into
Open
Conversation
Contributor
Author
There was a problem hiding this comment.
Copilot replaced this one for some reason... Might have to combine with current version
There was a problem hiding this comment.
Pull request overview
This PR adds and surfaces “function-level” documentation across the repository by introducing/refreshing README files for Lambdas, internal workspace packages, test suites, sandbox, and supplier configuration, then bundling them into the documentation site via the docs include-generation script.
Changes:
- Added new README documentation for Lambdas and internal packages (purpose, flows, integration points, nuances).
- Added an aggregated docs page (
function-readmes.md) and updateddocs/generate-includes.shto copy these READMEs into the docs build. - Minor documentation cleanups in root README, contributing guidance, and consumer docs table formatting.
Reviewed changes
Copilot reviewed 20 out of 21 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
tests/README.md |
Introduces a tests workspace overview and how to run different test suites. |
sandbox/README.md |
Replaces generator-scaffold text with a concise sandbox purpose/flow/run guide. |
README.md |
Removes stale “Examples” placeholder and adds a short unit testing section. |
lambdas/upsert-letter/README.md |
Documents upsert-letter Lambda responsibilities, flows, and edge cases. |
lambdas/update-letter-queue/README.md |
Documents queue projection Lambda behavior and Kinesis/DDB-stream processing rules. |
lambdas/supplier-config-ingress/README.md |
Documents supplier-config ingestion Lambda entity parsing, validation, and upsert behavior. |
lambdas/supplier-allocator/README.md |
Documents allocation Lambda selection flow, quota considerations, and edge cases. |
lambdas/mi-updates-transformer/README.md |
Documents MI stream transformer publishing behavior and filters. |
lambdas/letter-updates-transformer/README.md |
Documents letter update transformer publish rules (INSERT/MODIFY changes). |
lambdas/authorizer/README.md |
Documents REQUEST authorizer behavior and certificate-expiry monitoring. |
lambdas/api-handler/README.md |
Documents API handler exports, request flow, and integration points. |
internal/README.md |
Adds a top-level overview of internal workspace packages and intended usage. |
internal/helpers/README.md |
Documents shared logging/metrics helpers package. |
internal/events/README.md |
Documents published supplier-api event schema package structure and constraints. |
internal/event-builders/README.md |
Documents CloudEvent construction helpers and usage. |
internal/datastore/README.md |
Documents shared DynamoDB repositories/types and queue-table behavior. |
docs/generate-includes.sh |
Extends includes generation to copy function/package READMEs into docs _includes. |
docs/collections/_developers/guides/function-readmes.md |
Adds a docs page that includes the generated README includes and a data-flow overview. |
docs/collections/_consumers/acceptance.md |
Normalizes markdown table separator formatting. |
CONTRIBUTING.md |
Adds guidance to keep function READMEs updated alongside code changes. |
config/suppliers/README.md |
Documents supplier config entity files and the allocation lookup chain. |
Comment on lines
+48
to
+52
| ## Prerequisites | ||
|
|
||
| # TODO | ||
|
|
||
| - **Unit and Pact tests** run locally with no external dependencies. |
Comment on lines
+11
to
+12
| - **`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/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. |
Comment on lines
+33
to
+35
| - `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. |
Comment on lines
+17
to
+19
| - Imported by every Lambda and by `@internal/datastore` and `@internal/event-builders`. | ||
| - `pino` is the only logging library used across the codebase. | ||
| - `aws-embedded-metrics` is used for CloudWatch metric emission in Lambda context. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Context
Type of changes
Checklist
DT3-Specific Checklist
Sensitive Information Declaration
To ensure the utmost confidentiality and protect your and others privacy, we kindly ask you to NOT including PII (Personal Identifiable Information) / PID (Personal Identifiable Data) or any other sensitive data in this PR (Pull Request) and the codebase changes. We will remove any PR that do contain any sensitive information. We really appreciate your cooperation in this matter.