Email Integration -- Runtime Design

Superseded

This document’s content has been subsumed by ../architecture-overview.md § 3 (Runtime topology) and § 4 (Functional → runtime → artifact mapping). It is retained as historical exploration. For the authoritative runtime design, refer to architecture-overview.md.

Runtime topology for the email integration, showing how the functional subsystems (see functional.md) map to deployed infrastructure resources.

Runtime Topology

Functional-to-Runtime Mapping

The functional subsystems described in functional.md map to runtime resources as follows:

Functional Subsystem	Runtime Resource	Notes
SPA (React / Next.js Pages)	AWS Amplify	Static asset hosting + Next.js SSR
BFF (Next.js API Routes)	AWS Amplify (server-side)	Runs as part of the Amplify deployment, proxies to backend via API Gateway
Backend (ShopAccess/Email module)	EKS namespace (Kotlin/Ktor pod)	Part of the operations runtime component; the email module is a module within the monolith
EmailJob persistence	Aurora RDS (PostgreSQL)	email_job table in the partition’s database
EmailConfiguration persistence	Aurora RDS (PostgreSQL)	tenant_email_config table
Postmark event endpoint	API Gateway → EKS	Inbound REST from Postmark, authenticated via Bearer token (see DQ-011)
Tenant DNS provisioning	Partition R53 Zone	Per-tenant DKIM TXT, Return-Path CNAME, DMARC TXT records
ESP sending	Postmark Server (per tenant)	Outbound REST from EKS to Postmark API
ESP provisioning	Postmark Account API	Server/domain creation, webhook configuration

Inbound Event Path (Postmark → Arda)

Postmark delivery events (Delivery, Bounce, SpamComplaint) follow this path:

1. Postmark sends POST to the webhook URL configured per server (see postmark-service.md)
2. The request hits the API Gateway at <partition>.<infra>.io.arda.cards
3. API Gateway routes to the EKS runtime component
4. The POST /v1/shop-access/email/postmark-events endpoint validates the Authorization: Bearer header
5. The endpoint updates the corresponding EmailJob status in Aurora RDS

The “Partition R53 Zone” label in the diagram refers to the partition-specific hosted zone (e.g., prod.{mail-root-domain} in Alpha001, dev.{mail-root-domain} in Alpha002). The root zone ({mail-root-domain}) lives in the platformRoot account and is not accessed at runtime — only during infrastructure provisioning via CDK. See infrastructure.md for the full zone structure.

Runtime Configuration

The email module requires partition-specific configuration injected at deployment time. See functional.md for the module’s configuration requirements and infrastructure.md for the Secrets Manager paths and IAM roles.