Development

Running the Notification service locally

The Notification service is a Lambda application rather than a long-running HTTP server. Local development mainly consists of installing dependencies, configuring environment variables, building the TypeScript output, previewing templates, and invoking the handler with test events.

To get started locally:

cd services/notification
npm install
cp .env.example .env

Then fill in the provider credentials and local configuration values you need.

Environment configuration

The service uses environment variables for provider credentials and runtime behaviour. Typical values include:

RESEND_API_KEY=re_...
EMAIL_FROM_ADDRESS=[email protected]
OVERRIDE_RECIPIENT_EMAIL=

TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...
TWILIO_FROM_NUMBER=+1234567890

WEBSITE_URL=https://example.com

Use OVERRIDE_RECIPIENT_EMAIL in development or staging if you want all outbound emails redirected to a safe inbox.

Build

Compile the Lambda locally with:

npm run build
npm run watch

The compiled handler is written to dist/index.js.

Adding a new notification

To add support for a new event:

1. Create a new strategy in src/strategy/notifications/.
2. Register that strategy in src/strategy/NotificationRegistry.ts.
3. Add the required content builder or React Email template under src/content/.
4. If needed, add or update the matching EventBridge rule in the infrastructure stack.

At a high level, each new strategy decides which channels to use and how to build the notification content for the incoming event.

Local iteration

The Lambda handler can be invoked directly with a mock EventBridge event payload during development. Existing tests provide examples of how strategies and handlers are exercised locally.