Where Offline Ends: Designing CareReady's Serverless Trust Boundary

How CareReady combines an offline-first PWA with Cognito, API Gateway, Lambda, and DynamoDB without forcing families into an account-first workflow.

CareReady has two users who should not be given the same architecture.

A family caregiver needs a checklist that opens quickly, survives a weak connection, and does not begin with account creation. A care facility needs a controlled way to create and distribute instructions that appear as its template. The first workflow benefits from local state and low friction. The second requires identity, authorisation, and an operational record.

The architecture is therefore not “a PWA with an API.” It is a deliberate boundary between local family work and facility-authored cloud data.

Start with the work that does not need the cloud

The family checklist is a static web application served through Amazon S3 and CloudFront. A service worker caches the application shell and bundled product data. Checklist state is written synchronously to an in-memory cache and persisted asynchronously to IndexedDB, with a localStorage fallback when IndexedDB is unavailable.

This keeps the interaction responsive and lets the family continue checking items, marking them unnecessary, assigning containers, adding personal items, and completing the return check without waiting for a network round trip.

It also limits what the backend needs to know. The current cloud service stores facility templates; it does not receive the family’s personal checklist state. That is both an architectural simplification and a privacy boundary.

The trade-off is explicit. Local state cannot currently be recovered after browser-data deletion or device loss, and it does not synchronise across family devices. Those capabilities are designed as a later phase, not implied by the current implementation.

Retrieval is online; use after retrieval is local

A family can receive a six-character facility code or a QR link containing that code. Redeeming a new code requires a network connection because the authoritative template is stored in DynamoDB. After retrieval, the template is saved on the device and merged into the local checklist.

This produces a useful offline boundary:

Online once
  facility code -> public redeem endpoint -> facility template

Local afterwards
  product defaults + facility template + personal changes -> rendered checklist

Calling the whole product “offline” would be inaccurate. Template retrieval, facility login, and template editing remain network operations. The family packing workflow continues offline after the required data has crossed the boundary.

One product, two authorisation models

Facility staff authenticate through an Amazon Cognito User Pool. Self-sign-up is disabled; facility users are administered rather than publicly registered. The browser receives Cognito tokens, and API Gateway applies a JWT authorizer to facility template routes.

The route split is small:

  • POST /v1/templates/redeem is public and accepts a share code.
  • GET/POST /v1/facility/templates requires a facility JWT.
  • GET/PUT/DELETE /v1/facility/templates/{tplId} also requires a facility JWT.

The Lambda does not trust a facility identifier supplied in a request body. It derives facilityId from a custom JWT claim and falls back to the Cognito subject. DynamoDB keys are then built from that identity, so a template lookup uses the authenticated facility partition.

The share code is not an editing credential. It is a retrieval reference to a deliberately narrow representation: template name, items, overrides, facility display name, and share code. Families do not receive an authenticated facility session.

That does not make a six-character public code a secret. Enumeration, code lifecycle, abuse monitoring, and rate controls remain security considerations before broader use. The architectural claim is narrower: a public retrieval path does not grant facility CRUD authority.

DynamoDB follows the access patterns

The current table uses a composite primary key:

PK = FAC#<facilityId>
SK = TPL#<templateId>

This supports listing and retrieving templates within one authenticated facility partition. A global secondary index resolves the family access pattern:

GSI1PK = CODE#<shareCode>

The redeem endpoint queries the index with a limit of one. The facility routes query or address the base table using the identity-derived partition key.

This is a small single-table design because the implemented service is small. The broader design document includes possible family lists, memberships, and progress projections, but those entities have not been added merely to make the data model look comprehensive. The production schema supports the current facility-template loop.

The table uses on-demand billing, which fits an early product with irregular traffic and no reason to reserve capacity. It also has a retain policy, so deleting or replacing the infrastructure stack does not silently delete production templates. Retention creates its own operational responsibility: stack deletion is not data deletion, and name collisions must be handled deliberately.

Keep the Lambda boring

The API is one Python 3.12 Lambda with an internal router and boto3 as its only runtime dependency. It validates template names, item counts, item names, and the shape of overrides before writing to DynamoDB.

For the current route count, one function keeps deployment and permissions simple. The table grants read/write access to that function, while API Gateway owns the public-versus-authorised route distinction.

This choice is not a universal recommendation. As the service grows, one function can create a broad IAM and deployment blast radius. Splitting by bounded context, narrowing permissions, adding structured observability, and preventing internal exception details from reaching clients would be reasonable next hardening steps. At the pilot stage, the value of the single function is that the whole API boundary remains easy to inspect and test.

Infrastructure as a product artefact

The backend is defined with AWS CDK rather than assembled only through the console. The stack creates the DynamoDB table and index, Cognito pool and browser client, Lambda function, HTTP API, CORS policy, JWT authorizer, routes, and outputs.

This gives the architecture a reviewable representation. A product decision such as “families retrieve without signing in, but facilities edit with authentication” is visible in route definitions, not only in a diagram. The retain policy and token lifetimes are similarly inspectable.

Infrastructure as code does not remove operational work. Cognito user recovery exposed one example: staff sign in using an email alias, while an administrative password operation may require the pool’s internal UUID username. The code was functioning; the runbook did not yet explain both identities. The recovery test corrected the documentation as well as the account.

Delivery architecture includes the browser cache

The static frontend deploys to S3 and CloudFront through GitHub Actions. CI checks syntax, JSON, backend behaviour, content policy, source policy, and headless-browser rendering before main-branch deployment.

For an offline PWA, deployment correctness includes service-worker behaviour. A cache version that is not incremented can leave existing devices on stale assets even when S3 and CloudFront contain the new release. CareReady therefore has a source-policy check that compares frontend changes with the service-worker cache name.

This is a useful architectural lesson: CDN invalidation and browser cache invalidation are different layers. A green cloud deployment does not guarantee that an installed PWA is running the intended code.

The current deployment workflow uses repository-managed AWS credentials. Moving it to GitHub OIDC with a least-privilege deploy role is a clear infrastructure hardening opportunity; it should not be described as already implemented.

Architecture decisions are product decisions

Each major boundary answers a product question:

  • Local family state preserves low-friction and offline use, while accepting no cross-device recovery yet.
  • Authenticated facility routes protect authorship of facility templates.
  • Public code redemption avoids forcing a family account into the first-use journey.
  • Client-side three-layer merging preserves separate ownership of product, facility, and personal content.
  • A minimal production schema avoids building family sync and dashboards before pilot evidence selects them.
  • Retained infrastructure and automated policy checks treat operability as part of delivery.

This is the intersection I want my technical product-management work to show. Cloud architecture is not a separate diagram produced after the roadmap. It is where user friction, trust, privacy, failure modes, cost, and future options become concrete trade-offs.

The implementation and CDK stack are public in the CareReady repository, and the CareReady product page tracks its status. My broader technical-PM and cloud profile is at hire-veai.com.

CareReady supports belongings preparation and handovers. It is not a medical device and does not replace instructions from a care facility or healthcare professional.

Thanks for reading — built with care, for caregivers.