ENG-01 — Engineering Foundation and Platform Standards¶

Engineering Foundation · Working Draft · Working Draft v6 · Updated September 7, 2026

1. Objective¶

Establish the foundational technology decisions, shared implementation patterns, development scaffolding, and engineering controls required for DragonPay development.

ENG-01 defines the common engineering foundation consumed by Payment Hub, Payment Product, Channel Experience, Operations Experience, and future DragonPay work. It prevents individual stories, modules, or engineers from independently selecting foundational technologies or implementing cross-cutting platform behavior differently.

Select and record the initial cloud, runtime, persistence, messaging, orchestration, observability, infrastructure, testing, security, and development-tool choices required to begin implementation.
Provide reusable implementations or reference scaffolding for STD-01 cross-cutting behaviors that should not be recreated independently by each PH module.
Define repository, environment, CI/CD, testing, observability, security, and AI-assisted development conventions.
Provide a standard Connector scaffold, deterministic simulator, and reusable fixtures for external-integration development.
Capture recurring implementation controls as reusable engineering readiness checklists rather than repeating them inside every domain story.
Record intentionally deferred decisions so they are not accidentally made inside downstream implementation work.

ENG-01 is not a requirement to fully build every shared capability before domain development begins. It establishes the approved direction and the minimum working scaffolding needed so parallel implementation starts from one consistent foundation.

2. Operating model and decision classification¶

Foundation work is intentionally split between decisions, shared implementation, and reusable engineering standards. A decision may be made before its implementation is complete; a shared component may begin as a reference scaffold and mature as real PH work exposes additional needs.

Type	Meaning
TECHNOLOGY_DECISION	Select the initial technology/library/service and document its responsibility and usage boundary.
SHARED_IMPLEMENTATION	Provide a reusable package, module, scaffold, Terraform module, pipeline template, simulator, or reference implementation.
ENGINEERING_STANDARD	Define a convention, checklist, or conformance requirement that downstream development must follow.

Material technology choices should also be classified so the team can distinguish durable standards from pragmatic initial selections:

Classification	Meaning
REQUIRED_STANDARD	DragonPay implementations use this approach unless an approved ADR explicitly supersedes it.
INITIAL_PLATFORM_CHOICE	Initial implementation choice that may later be replaced behind a stable contract or boundary.
DEFERRED	Intentionally unresolved until a concrete Product, scale, regulatory, operational, or integration need requires the decision.

Material decisions record the selected technology/pattern, responsibility, classification, significant constraints, and ADR reference when warranted. ADRs are written into this repository's existing docs/decisions/ sequence (see §6) — ENG-01 does not establish a separate ADR trail in the engineering repository.
ENG-01 should make decisions only when downstream work needs them; it should not force premature selection of technologies with no near-term dependency.
Shared engineering packages own technical mechanics, not payment-domain decisions. Domain behavior remains with the owning PH/PP/CX/OX requirement.
An approved ADR may supersede an ENG-01 decision without rewriting historical implementation evidence; the current baseline references the active ADR.

3. Architecture boundaries¶

Owner / Artifact	Responsibility
STD-01	Defines platform-wide command, event, idempotency, outbox, resilience, telemetry, and related behavioral contracts. ENG-01 defines the reusable engineering implementation approach for those contracts.
PH epics	Own Payment Hub domain behavior and data. PH modules consume foundation components rather than redefine them.
PP / CX / OX	Own Product, channel, and operator behavior while using ENG-01 runtime, testing, security, and delivery standards.
ENG-01	Owns technology baseline, shared technical scaffolding, common implementation standards, engineering checklists, and foundation conformance.
ADRs	Record significant technology/architecture decisions, tradeoffs, and superseding decisions — in this repository's `docs/decisions/` sequence.
Cloud / managed services	Provide runtime capabilities selected by ENG-01; service-specific behavior must remain behind defined application boundaries where replaceability matters.
CI/CD and IaC	Validate/provision/deploy software and infrastructure; they do not define business behavior.
Observability platform	Receives telemetry and operational evidence; it is not authoritative payment state or a replacement for PH domain records.

ENG-01 must not become a generic internal platform program. Prefer a small shared package, reference implementation, simulator, or checklist when that is sufficient. New abstraction should be justified by repeated implementation needs, not created preemptively.

4. Initial technology baseline¶

The baseline below captures DragonPay's current technology direction and the open questions ENG-01 makes explicit before dependent work requires them. Each row marked "Decision required" below is open specifically because it was never routed through the Foundation decision-package process (ENG02-15) — not because it lacks a reasonable current lean; each such row's stated current lean is a prior planning assumption preserved as guidance, not a decision. The Decision Register (ENG02-25) is the authoritative record of which of these items are open versus decided once each is registered there; this table is kept in sync with it, and a closing decision is additionally recorded as an ADR in docs/decisions/ per §2 when the decision itself is significant enough to warrant one — §10's "technology/library decision register" row refers to this same table and its closing ADRs, not a separate artifact. Where sections below name a current-lean technology by name (e.g. "Terraform", "Datadog", the ### Temporal subsection, or TypeScript/Node.js, NestJS, Next.js, Prisma, PostgreSQL, Auth0, HashiCorp Vault, and Kubernetes/Istio elsewhere in this document), that naming is illustrative shorthand for the corresponding row's current lean above and does not itself constitute a decision beyond what this table states.

Area	Current direction / decision	Expected classification
Cloud	Decision required: which cloud provider. Current lean: Azure — `docs/build-buy.md` itself frames this as unresolved ("Azure will have a slight edge but easily overridden by resource experience"). Persistence's managed database service and Messaging below are separate open decisions contingent on this one, not merely relabeling; the Azure-specific product names under Secrets and Runtime/deployment, and the Azure references under Cost/budget governance and Account/access bootstrap, would need relabeling, not re-deciding, once this resolves.	REQUIRED_STANDARD / service-specific choices may be INITIAL_PLATFORM_CHOICE
Infrastructure as Code	Decision required: which IaC tool. Current lean: Terraform. Once confirmed: define modules, state, environment parameterization, review/apply, and exception handling.	REQUIRED_STANDARD
Observability	Decision required: which observability/monitoring platform. Current lean: Datadog, per `docs/build-buy.md` ("Datadog or native + OpenTelemetry"). Once confirmed: initial logs, metrics, traces, dashboards, monitors, and operational visibility.	INITIAL_PLATFORM_CHOICE
Application telemetry	OpenTelemetry-compatible instrumentation where practical; define shared instrumentation and export/integration with whichever observability platform the Observability row above resolves to.	REQUIRED_STANDARD for application instrumentation boundary
Durable orchestration	Decision required: which durable workflow orchestration platform. Current lean: Temporal, per `docs/build-buy.md` ("Buy: Temporal Cloud"). Once confirmed: define hosting/service choice, namespace/environment structure, worker conventions, retries, timers, versioning, and testing.	INITIAL_PLATFORM_CHOICE
Application runtime	Decision required: primary server-side language and runtime (`DR-001`). Current lean: TypeScript / Node.js 22, conforming to the parent PE company's shared platform stack.	REQUIRED_STANDARD
Backend API framework	Decision required: backend application framework (`DR-002`). Current lean: NestJS 11, conforming to the parent PE company's shared platform stack; its guard/decorator model would fit PH-01's authorization pattern directly if confirmed (see ENG01-24).	REQUIRED_STANDARD
Frontend / BFF framework	Decision required: frontend/BFF framework (`DR-022` — DragonPay-owned frontend framework; `DR-004` tracks the separate API/transport-approach question and does not cover this row). Current lean: Next.js (App Router), conforming to the parent PE company's shared platform stack, which would implement the BFF pattern described in ENG01-24 if confirmed.	REQUIRED_STANDARD
Persistence — ORM/migration tool	Decision required: data-access/ORM/schema-migration approach (`DR-006`). Current lean: Prisma as the ORM/query-library and migration tool, conforming to the parent PE company's shared platform stack (see ENG01-04). Transaction/concurrency conventions remain to define on top of whichever tool is confirmed.	REQUIRED_STANDARD
Persistence — database engine	Decision required: primary transactional database engine (`DR-005`). Current lean: managed PostgreSQL — `docs/build-buy.md` recommends "Buy managed Postgres" under either cloud candidate (Aurora PostgreSQL or Azure Database for PostgreSQL), so this lean holds regardless of the Cloud decision above.	REQUIRED_STANDARD
Persistence — managed database service	Decision required: which cloud's managed PostgreSQL service, contingent on the Cloud decision above. Current lean: Azure Database for PostgreSQL.	INITIAL_PLATFORM_CHOICE
Messaging	Decision required: which async messaging/eventing service, contingent on the Cloud decision above. Current lean: Azure Service Bus / Event Grid — `docs/build-buy.md` recommends "buy cloud-native" messaging, which resolves to this specific pairing once Cloud=Azure is confirmed. Topic/queue/event conventions remain to define once confirmed.	INITIAL_PLATFORM_CHOICE
Identity / SSO / RBAC	Decision required: authenticated caller identity/trust approach (`DR-017`). Current lean: Auth0, for operational/workforce identity (PH-01 trusted auth context, machine access, application identity), conforming to the parent PE company's shared platform architecture. The integration pattern described in ENG01-24 (BFF, guard chain, no Auth0 Organizations) is contingent on this lean being confirmed.	INITIAL_PLATFORM_CHOICE
Notification delivery (SMS/email)	Decision required: which SMS/email delivery providers. Current lean: Twilio (SMS) + SendGrid (email), per `docs/build-buy.md`, for PH-12 CommunicationAdapter delivery.	INITIAL_PLATFORM_CHOICE
Secrets	Decision required: secrets/runtime-configuration mechanism (`DR-011`). Current lean: HashiCorp Vault, injected at pod startup, conforming to the parent PE company's shared platform stack. If confirmed, a cloud-native key-management service would be retained narrowly for Vault's own auto-unseal mechanism, not for direct application secret references (see ENG01-22) — Azure Key Vault specifically assumes the Cloud=Azure lean above and may need relabeling, not re-deciding, once that resolves.	REQUIRED_STANDARD
Runtime / deployment	Decision required: runtime/deployment platform (`DR-009`). Current lean: managed Kubernetes with Istio service mesh, conforming to the parent PE company's shared platform stack, for the operational tooling/runbook/support transfer this would give a small team if confirmed (see ENG01-21). Azure AKS specifically assumes the Cloud=Azure lean above and may need relabeling, not re-deciding, once that resolves.	REQUIRED_STANDARD
CI/CD	Decision required: pipeline technology, PR checks, artifact build, environment promotion, approvals, and rollback approach.	REQUIRED engineering standard
Repository / toolchain	Decision required: repo strategy, package manager, workspace/build tooling, lint/format standards (the backend and frontend/BFF framework rows above are current leans, not fixed; package manager/workspace tooling likewise open).	REQUIRED engineering standard
Testing	Decision required: unit, integration, contract, Temporal, database, and simulation libraries/tooling.	REQUIRED engineering standard
Security tooling	Decision required: dependency, SAST, secret, container, and Terraform/IaC scanning tools and gates.	REQUIRED engineering standard
AI-assisted development	Claude Code/project instructions, reusable agents/skills, requirement-to-test-to-code workflow, human review, and peer-review expectations (see §9).	REQUIRED engineering standard
Account/access bootstrap	Decision required: who holds initial founder-level root access to Azure, GitHub, Temporal Cloud, Datadog, and Auth0 before Terraform/CI govern access (see ENG01-14).	REQUIRED engineering standard
Cost/budget governance	Decision required: Azure budget/alert thresholds on Terraform-provisioned resources (see ENG01-15).	REQUIRED engineering standard
Backup / disaster recovery	Decision required: Postgres backup/restore approach and RPO/RTO statement, sized for current team/stage (see ENG01-16).	INITIAL_PLATFORM_CHOICE
Data classification	Decision required: field-level restricted/internal/public classification for Party/Payment Instrument and other sensitive data (see ENG01-17).	REQUIRED_STANDARD
Web SDK distribution	Decision required: which parts of CX-01's Web SDK build/bundling/CDN/versioning are ENG-01-owned shared tooling vs. CX-01-owned (see ENG01-18).	INITIAL_PLATFORM_CHOICE
Environment / domain naming	Decision required: environment naming convention and the domain the hosted claim page/demo environment lives at (see ENG01-19).	INITIAL_PLATFORM_CHOICE

5. Shared platform capability catalog¶

Cross-cutting behaviors defined by STD-01 should be implemented or scaffolded once when practical and consumed consistently by domain modules. The initial shared catalog should remain small and implementation-oriented.

Capability	Initial shared responsibility
Command context	Typed STD-01 command context, required-field validation, deadline/correlation/causation propagation helpers.
Event envelope	Typed STD-01 event envelope, event identity/version metadata, correlation/causation and publication helpers.
Command idempotency	Shared CommandIdempotencyRecord persistence/service behavior and deterministic fingerprint integration points.
Transactional outbox	Reference persistence helper/pattern ensuring material domain write + outbox row commit in one local transaction and asynchronous dispatch after commit.
Event-consumer deduplication	Shared event-consumer replay/conflict handling for event_id and source identity where required.
Error/result contracts	Common technical error envelope and reusable platform error codes without absorbing domain-specific decisions.
Resilience wrapper	Timeout, bounded retry, circuit/admission/backpressure hooks, telemetry, and safe configuration integration for external boundaries.
Connection health contract	Common representation/contract for Connection status, health, circuit/admission/suspension and observed freshness where STD-01/PH-08 requires shared behavior.
Configuration/secrets	Validated configuration loading, environment/Tenant references, HashiCorp Vault references, and startup validation conventions (see ENG01-22).
Telemetry helpers	OpenTelemetry-compatible trace/metric/log correlation, service/version/environment metadata, and sensitive-data-safe defaults.
Testing utilities	Deterministic clock/ID abstractions, fixture builders, test context factories, event/idempotency helpers where repeated use justifies them.
Communication delivery adapter	Base CommunicationAdapter scaffold plus concrete Twilio (SMS) and SendGrid (email) implementations, consumed by PH-12 rather than rebuilt per-Product — mirrors the Connector scaffold pattern (see ENG01-20).
Identity/session foundation	BFF session helpers (token storage, silent refresh), JWKS-based JWT validation, and the `JwtAuthGuard -> TenantGuard -> PermissionGuard` chain, consumed by OX-01 and any other Auth0-backed application rather than rebuilt per-app (see ENG01-24).

Each shared package must define its public contract, owner, supported usage, and explicit boundary between platform mechanics and domain behavior.
Shared packages should have conformance/contract tests sufficient for PH modules and AI coding agents to use them without reinterpreting semantics.
Do not create a shared package merely because two stories contain similar code; promote behavior only when the contract is stable enough to be safely reused.

6. Repository, application, persistence and API conventions¶

Repository and module structure¶

Choose monorepo versus multi-repo and define the initial module/package boundaries.
Define supported Node.js/TypeScript versions, package manager, workspace/build tooling, lint/format standards, and standard local commands.
Define dependency rules so domain modules cannot create circular or unauthorized dependencies through shared packages.
Provide a standard module/service scaffold, shared-package scaffold, local development startup path, and developer setup instructions.
Reference the dragonpay product-docs repository per ENG-02's Product-repository contract: repository_id/path/baseline_commit in .dragonpay/config.yaml, remote optional until CI or another machine/contributor needs it. PH/PP/STD/ADR requirements reach engineers and AI coding agents by reading the pinned Product checkout at that path, not through a separate copy. The baseline commit is advanced explicitly — as its own small commit — when a docs change should take effect in an in-flight build; a docs edit does not silently ripple into the engineering repo until that advance happens. See §9's AI-assisted development section for how this is consumed, and ENG-02 for the full contract.

Persistence¶

Use Prisma (current lean, §4/DR-006, open) as the database access/ORM/query library and migration framework, against managed PostgreSQL (current lean as the engine, §4/DR-005, open) on the confirmed cloud's managed service (current lean: Azure Database for PostgreSQL, open — see §4 and the Decision Register, ENG02-25).
Define local transaction boundaries, atomic domain-write + outbox behavior, optimistic concurrency, immutable-record conventions, migration ownership, identifiers, and timestamps.
Provide at least one reference persistence implementation demonstrating command idempotency and atomic outbox behavior.
Domain tables remain owned by their modules; shared persistence utilities must not become a generic business repository.

APIs and contracts¶

Select the HTTP framework and request/schema validation approach.
Define Tenant/authentication context propagation, authorization integration, standard error envelope, versioning, pagination/filtering, and OpenAPI generation.
Provide a reference command endpoint and read endpoint showing STD-01 context, validation, authorization boundary, and error behavior.
External API/client-generation choices should be made only when required by a concrete integration or channel need.

7. Infrastructure, configuration and environment model¶

Terraform is the current-lean mechanism for DragonPay-managed infrastructure (open, §4/Decision Register ENG02-25); the bullets below describe how that mechanism would be used once confirmed. Environment isolation and provisioning conventions must be defined early enough that application stories do not create local, one-off infrastructure patterns.

Define Terraform repository/module structure, remote state/locking, naming/tagging, environment inputs, plan/review/apply, and controlled exception/break-glass handling.
Define dev/test/stage/prod isolation for databases, messaging resources, Temporal namespaces/workers, secrets, object storage, service identities, and observability tags.
Define the Azure networking/security boundary and minimum connectivity model required for application services, managed services, and external Connector endpoints.
As the current-lean runtime/deployment platform (open, §4/DR-009 — see ENG01-21): provision an Azure AKS cluster with Istio service mesh for application services and workers, conforming to the parent PE company's shared platform stack: Azure Load Balancer terminates external traffic into the Istio Gateway (TLS termination), which forwards over mTLS into the AKS cluster; in-cluster service-to-service calls also go over Istio-enforced mTLS. Define namespace-per-environment conventions and resource/quota baselines.
As the current-lean secrets mechanism (open, §4/DR-011 — see ENG01-22): define HashiCorp Vault usage — injected into pods at startup rather than referenced by application code at request time — secret/config references, startup validation, and rotation expectations. Azure Key Vault's role is narrowed to Vault's own auto-unseal mechanism. Secret values must not be stored in ordinary application configuration or Terraform state when avoidable.
Define environment/Tenant configuration ownership so deployment configuration and business/Tenant configuration are not conflated.
Manual production infrastructure creation/change is exceptional and controlled; the normal reproducible state is represented through Terraform and the deployment process.
Define the environment naming convention and the domain(s) each environment resolves to, including where the hosted P2P claim page and demo environment live (see ENG01-19).
Define Azure budget/alert thresholds on Terraform-provisioned resources so spend is visible from the first environment onward (see ENG01-15).

8. Eventing, Temporal, resilience, Connector and Communication foundation¶

Messaging and asynchronous processing¶

Select topic/queue naming, producer/consumer conventions, outbox dispatch, consumer replay/deduplication, schema/version evolution, dead-letter/failure handling, and observability for the current-lean messaging technology (Azure Service Bus / Event Grid, open — see §4 and the Decision Register, ENG02-25).
Event infrastructure must preserve STD-01 event identity, Tenant, correlation/causation, and contract version semantics.
Shared job infrastructure may schedule/execute work, but domain-visible job state remains owned by the applicable domain requirement when a business/operational job object is required.

Durable orchestration (current lean: Temporal)¶

Temporal is the current-lean durable orchestration platform (open, §4/Decision Register ENG02-25), used by name below as the concrete illustration of the conventions this section defines — matching PH-04 §1 and §9's own position that the orchestration vendor is intentionally not selected at the Product level. Once a platform is confirmed (Temporal or otherwise), the bullets below apply to whichever platform that is; "Temporal Activity retry" below means "the confirmed platform's activity-retry mechanism."

Define the selected platform's service/hosting choice and namespace/environment isolation.
Define worker organization, workflow/activity ownership, deterministic-code expectations, timeout/heartbeat conventions, versioning, deployment compatibility, and test strategy.
Explicitly distinguish business workflow retry, Temporal Activity retry, Connector retry, reconciliation recheck, and scheduled/background job retry so one layer does not silently authorize another.
Provide a reference worker/workflow/activity that demonstrates the standard conventions without implementing Product-specific behavior.

Connector scaffold and simulator¶

Provide a standard Connector package/interface structure consistent with PH-08 and STD-01.
Support normalized request/result contracts, handoff_status, retry_classification, external_idempotency_reference, Connection identity/configuration, resilience, health, mapping/schema lineage, secure evidence references, and telemetry hooks.
Provide a deterministic simulated Connector and conformance suite covering success, rejection, pre-handoff failure, timeout, possible handoff/unknown outcome, delayed evidence, duplicate/conflicting events, unavailable/degraded service, and external status inquiry where supported.
The simulator is test infrastructure; it must not introduce behavior that is not defined by PH-08 or the Product/Connector contract being tested.

Communication delivery scaffold¶

Provide a base CommunicationAdapter package/interface structure consistent with PH-12, mirroring the Connector scaffold's normalized request/result/evidence pattern.
Provide concrete Twilio (SMS) and SendGrid (email) adapter implementations, plus a deterministic simulated adapter for testing delivery success, rejection, and provider-unavailable scenarios without sending real messages in non-prod.
Keep PH-12's domain decisions (which communication codes exist, retry/expiration behavior) out of the shared adapter; the adapter owns transport mechanics only.

9. Observability, testing, security and AI-assisted development¶

Observability¶

Datadog is the current-lean observability platform (open, §4/Decision Register ENG02-25) for application/infrastructure logs, metrics, traces, dashboards, monitors, and deployment/service visibility; the bullets below describe how it would be used once confirmed.
Prefer OpenTelemetry-compatible application instrumentation and shared DragonPay instrumentation packages where practical rather than direct Datadog-specific coupling throughout domain code.
Define service/environment/version naming, correlation/causation visibility, standard metrics, dashboard/alert conventions, Connector/Connection telemetry, and telemetry freshness.
Define sensitive-data restrictions for logs, traces, metrics, exception payloads, and provider/CU evidence, grounded in the data classification list (see ENG01-17).

Testing¶

Define TDD expectations and the boundary between unit, integration, contract, Temporal/workflow, Connector conformance, and end-to-end tests.
Select testing libraries and provide reusable database, messaging, Temporal, clock/ID, command/event, and Connector fixtures.
Reusable fixtures must include replay, duplicate, conflicting identity, timeout, unknown outcome, delayed evidence, concurrency, and failure-path scenarios where applicable.
CI should run the tests appropriate to the changed component and prevent bypass of required foundation conformance tests.

Security engineering¶

Select and configure dependency, source/static analysis, secret, container, and Terraform/IaC scanning.
Define which findings block pull requests/deployment, how exceptions are approved, and how findings are tracked to closure.
Security controls supplement PH-01 authorization and domain security requirements; ENG-01 does not define payment authorization policy.
As the current-lean identity provider (open, §4/DR-017 — see ENG01-24): baseline Auth0 security controls, conforming to the parent PE company's shared platform checklist: MFA enforced via Universal Login policies; password policy (minimum length, complexity, breach detection) configured in Auth0; brute-force protection via Auth0 anomaly detection; RS256 (asymmetric) token signing; JWKS key rotation handled automatically by Auth0 with backend-side caching; session cookies HttpOnly/Secure/SameSite=Lax; both the local session and the Auth0 SSO session destroyed on logout; M2M endpoints validate the gty: client-credentials claim so a user token cannot be replayed against a machine-to-machine endpoint.

AI-assisted development¶

AI-assisted development is a normal DragonPay engineering practice and must have an explicit project framework rather than ad hoc individual prompting.
Define Claude Code project instructions/context, reusable agents/skills, and how shared foundation packages are referenced.
PH/PP/STD/ADR requirements are supplied to coding agents via the dragonpay docs repository referenced through ENG-02's Product-repository contract (§6) — a pinned path and baseline commit, not a specific VCS mechanism. Project instructions point coding agents at that path; the baseline is advanced explicitly, not automatically, when a docs change should take effect.
Use the expected workflow: understand requirement -> establish tests/TDD intent -> generate or modify code -> human review -> PR -> CI/conformance validation. Peer review is not a required step while the team is 1 developer; it becomes a required PR check the moment the team reaches 2 developers (matching docs/definition-of-done.md's bar for the team that exists at a given time — see ENG01-10).
Generated code is production code and is subject to the same architecture, security, testing, review, and observability requirements as manually authored code.
Coding agents must not invent undocumented domain behavior to fill requirement gaps; ambiguous behavior is surfaced for requirement/ADR clarification.

10. Required engineering artifacts and interfaces¶

Area	Minimum artifact / interface
Technology baseline	Current technology/library decision register with classification and ADR links.
Repository	Standard repository/application/shared-package scaffold plus local developer commands, including the Product-repository reference wiring.
STD-01 packages	Documented package APIs for command context, event envelope, idempotency, outbox, consumer dedupe, telemetry, and shared technical errors.
Persistence	Reference migration, transaction, optimistic-concurrency, command-idempotency, and atomic-outbox implementation.
API	Reference command/read APIs, validation/error/OpenAPI conventions, tenant/auth context integration.
Messaging	Reference event publisher/consumer, outbox dispatcher integration, replay/conflict fixtures, failure/dead-letter conventions.
Temporal	Namespace model, worker/workflow/activity scaffold, retry/version/test conventions.
Connector	Connector SDK/scaffold, simulator, conformance suite, standard fixtures.
Communication	CommunicationAdapter SDK/scaffold, Twilio/SendGrid implementations, simulated adapter, standard fixtures.
Infrastructure	Terraform module/repository skeleton, state/environment conventions, plan/apply controls, environment/domain naming record.
Container platform	AKS cluster/namespace conventions and Istio service-mesh (Gateway, mTLS) configuration.
Secrets runtime	HashiCorp Vault deployment, pod-injection configuration, and Azure Key Vault auto-unseal wiring.
Identity/BFF	Reference Next.js BFF (session management, token handling) and NestJS guard chain (`JwtAuthGuard`/`TenantGuard`/`PermissionGuard`) implementation.
Observability	Shared instrumentation/configuration, Datadog service/tagging conventions, initial dashboard/monitor examples.
CI/CD	PR/build/test/scan/artifact/deploy pipeline templates and environment-promotion controls, including the peer-review-at-2-developers gate.
Testing	Reusable test helpers/fixtures and testing/conformance standards.
AI development	Project instructions, initial agents/skills, AI coding workflow and review checklist.
Engineering review	Reusable readiness checklists for common change types.
Access bootstrap	Record of who holds founder-level root access to each vendor account and the transition plan to Terraform/CI-governed access.
Cost governance	Azure budget/alert configuration and spend-review cadence record.
Backup / DR	Documented Postgres backup/restore approach and RPO/RTO statement.
Data classification	Field-level restricted/internal/public classification list.
SDK distribution boundary	Documented line between ENG-01-owned and CX-01-owned Web SDK tooling.

11. Reference engineering flows¶

A. New domain command/event publisher¶

PH story defines command and material event -> engineer uses shared STD-01 command context/idempotency package -> domain transaction persists business state + outbox atomically -> outbox dispatcher publishes STD-01 event -> consumer deduplicates/rejects conflicts using shared event-consumer behavior -> Datadog/OpenTelemetry traces preserve correlation/causation.

B. New external Connector¶

PH-08/PP requirement defines external behavior -> engineer starts from Connector scaffold -> simulated Connector/conformance fixtures prove success/failure/timeout/unknown/replay semantics -> Terraform/config references provision required environment resources -> Connection/resilience/health and telemetry use shared contracts -> concrete Connector implements only provider/CU-specific mechanics.

C. AI-assisted PH implementation¶

Engineer reviews PH/STD/ADR requirements from the pinned Product checkout -> tests and acceptance behavior are established -> Claude Code receives approved project/domain context -> implementation uses shared foundation packages/scaffolds -> engineer reviews generated code and requirement coverage -> PR opened -> peer review if the team has reached 2 developers, otherwise proceeds directly -> CI runs tests, security checks and foundation conformance -> controlled deployment.

12. Implementation stories¶

The stories below are implementation contracts for foundational decisions and scaffolding. A story may complete through a documented decision, ADR, reference scaffold, or reusable implementation depending on its objective. Downstream PH development may proceed once the required foundation for that work is available; ENG-01 does not require every story to finish before all Product development starts.

ENG01-01 — Establish technology and library baseline¶

Objective: Select and record the initial technologies, libraries, and managed services required for DragonPay implementation.

Inputs / Preconditions

Current DragonPay architecture direction, STD-01, PH/PP requirements, Azure/Terraform/Datadog/Temporal/TypeScript direction, and current engineering/security constraints.
Known first-Product and first-CU implementation needs sufficient to avoid selecting technology without a concrete dependency.

Required Behavior

Review each baseline area in §4 and select the concrete service/library where implementation requires it.
Classify each material choice as REQUIRED_STANDARD, INITIAL_PLATFORM_CHOICE, or DEFERRED.
Record significant tradeoffs/constraints through ADRs in docs/decisions/; avoid unnecessary permanent coupling when a standard boundary is practical.
Do not silently select foundational technology inside a downstream PH story when ENG-01 has identified that choice as a shared decision.

Writes / Outputs

Publish/update the technology baseline and ADR references, including explicitly deferred choices.

Acceptance

An engineer starting the initial PH work can identify the approved runtime, persistence, messaging, IaC, observability, orchestration, testing, and supporting-tool direction without making independent foundational choices.
Deferred decisions are visible and have a stated trigger for future resolution.

ENG01-02 — Establish repository and application scaffold¶

Objective: Provide the standard repository, module/package, toolchain, and local-development structure used by DragonPay, including access to this project's product documentation.

Inputs / Preconditions

Technology/library decisions from ENG01-01 for Node/TypeScript and build/package tooling.
Initial modular/service boundaries expected by PH implementation and shared-library needs.

Required Behavior

Select repo strategy, package manager/workspace/build tooling, lint/format/test conventions, module naming, and dependency rules.
Provide a standard domain-module/service scaffold and shared-package scaffold.
Define local environment bootstrap commands and expected configuration/secret references.
Prevent shared packages from creating circular or unauthorized dependencies between domain modules.
Reference the dragonpay product-docs repository per ENG-02's Product-repository contract (repository_id/path/baseline_commit, remote optional) at a fixed path (e.g. docs-source/), document the baseline-advance process, and provide the initial project-level Claude Code instructions that point at it.

Writes / Outputs

Working repository/application skeleton, developer setup instructions, standard build/test/lint commands, dependency-boundary rules, and the Product-repository reference wired in at a fixed path with baseline-advance instructions.

Acceptance

A new PH module can be started from the scaffold without inventing a new project layout or toolchain.
Shared packages have a defined location and dependency direction.
An engineer or coding agent can read current PH/PP/STD/ADR content from the pinned Product-repository path without a separate copy step.

ENG01-03 — Establish STD-01 shared implementation foundation¶

Objective: Provide reusable packages/reference implementations for stable cross-cutting STD-01 mechanics.

Inputs / Preconditions

STD-01 command/event/idempotency/outbox/replay/correlation requirements and the selected persistence/messaging toolchain.
Approved package boundaries from ENG01-02.

Required Behavior

Implement or scaffold typed command context, event envelope, CommandIdempotencyRecord behavior, transactional outbox, event-consumer deduplication/conflict handling, correlation/causation helpers, and shared technical error contracts.
Keep domain-specific status transitions, retry authorization, matching, and business decisions outside shared packages.
Provide conformance tests/examples that downstream modules and coding agents can reuse.

Writes / Outputs

Version-controlled shared packages/reference modules plus tests and usage examples.

Acceptance

At least one reference command demonstrates STD-01 command idempotency and one material domain write demonstrates atomic outbox behavior.
At least one reference consumer demonstrates duplicate event safety and conflicting event identity handling.

ENG01-04 — Establish persistence and API standards¶

Objective: Select and scaffold common persistence and API implementation conventions used by PH modules, against Prisma (current lean, §4/DR-006, open) on managed PostgreSQL (current lean as the engine, §4/DR-005, open), on the confirmed cloud's managed service (current lean: Azure Database for PostgreSQL, open — see §4 and the Decision Register, ENG02-25).

Inputs / Preconditions

Persistence direction — all open: Prisma (DR-006) and the PostgreSQL engine (DR-005), each §4's current lean pending a Foundation decision-package resolution; which cloud's managed PostgreSQL service is also open (current lean: Azure Database for PostgreSQL, see §4/Decision Register ENG02-25). HTTP/schema-validation choices from ENG01-01.
STD-01 shared packages from ENG01-03 and PH-01 tenant/auth boundary requirements.

Required Behavior

As the current lean (open, §4/DR-006) pending confirmation: use Prisma as the database access/ORM/query library and migration framework, conforming to the parent PE company's shared platform stack. Define a Prisma tenant extension (or equivalent middleware) so tenant-scoping is enforced at the query layer by default rather than left to each domain module to remember, mirroring the pattern the parent company's shared platform already validated.
Define migrations, transactions, immutable-record conventions, optimistic concurrency, IDs/timestamps, and domain ownership of tables.
Define request validation, tenant/auth context propagation, authorization integration, standard error contract, versioning, OpenAPI, pagination/filtering.
Provide reference persistence and API implementations rather than a generic business repository/framework.

Writes / Outputs

Persistence/API conventions, reference migration/transaction, reference command/read endpoints, and API checklist.

Acceptance

Downstream modules can implement storage and APIs consistently without inventing transaction, validation, error, or API-version behavior.
Atomic domain/outbox and optimistic-concurrency examples are executable in tests.

ENG01-05 — Establish messaging and asynchronous processing foundation¶

Objective: Standardize DragonPay asynchronous messaging, event publication/consumption, replay, and failure behavior on the current-lean messaging technology (Azure Service Bus / Event Grid, open — see §4 and the Decision Register, ENG02-25).

Inputs / Preconditions

Messaging direction (current lean: Azure Service Bus / Event Grid — open, see §4/Decision Register ENG02-25), STD-01 event envelope/outbox behavior, environment model, and expected domain event producers/consumers.

Required Behavior

Define queues/topics/subscriptions/naming, publisher/consumer conventions, outbox dispatch, consumer deduplication, schema/version evolution, dead-letter/failure handling, replay, observability, and environment isolation.
Ensure message infrastructure preserves tenant, event identity, correlation/causation, and contract version.
Provide reference publisher/consumer and test fixtures for duplicate, conflict, out-of-order, and failed delivery scenarios.

Writes / Outputs

Messaging conventions, reference publisher/consumer, event-test fixtures, and operational failure-handling guidance.

Acceptance

Duplicate/replayed messages are safe under the reference implementation.
A failed consumer or downstream outage does not roll back an already committed source-domain transaction.

ENG01-06 — Establish Temporal foundation¶

Objective: Define and scaffold DragonPay durable-workflow conventions using the current-lean orchestration platform (Temporal, open — see §4 and the Decision Register, ENG02-25).

Inputs / Preconditions

Temporal as the current-lean orchestration platform (open, see §4/Decision Register ENG02-25) plus environment/runtime choices.
PH-04 and other domain requirements that depend on durable waits/timers/workflows.

Required Behavior

Select hosting/service approach and define namespace/environment isolation, workers, workflow/activity boundaries, deterministic-code rules, timeouts/heartbeats, versioning, deployment compatibility, and testing.
Explicitly document business workflow retry versus Activity retry, Connector retry, reconciliation recheck, and generic scheduled-job retry.
Provide a reference worker/workflow/activity that exercises the conventions without encoding Product behavior.

Writes / Outputs

Temporal foundation documentation, namespace model, reference worker/workflow/activity, test example, and checklist.

Acceptance

A PH workflow can be implemented without inventing the confirmed orchestration platform's namespace, retry, version, or testing conventions.
Reference tests demonstrate deterministic workflow behavior and controlled Activity retry.

ENG01-07 — Establish Connector scaffold and simulator¶

Objective: Provide reusable Connector scaffolding and deterministic simulation required for PH-08 and future external integrations.

Inputs / Preconditions

PH-08 Connector/Connection contracts, STD-01 resilience behavior, selected messaging/testing/telemetry tooling.
Initial execution scenarios required by the first Product/CU.

Required Behavior

Define Connector interface/package structure and common normalized request/result/evidence/version/health hooks.
Support handoff_status, retry_classification, external_idempotency_reference, Connection identity/configuration, resilience, secure evidence references, mapping/schema lineage, and telemetry.
Build simulated Connector behavior for success, rejection, pre-handoff failure, timeout, unknown possible handoff, delayed evidence, duplicate/conflicting events, degraded/unavailable service, and status inquiry where applicable.
Create conformance tests reusable by each concrete Connector.

Writes / Outputs

Connector scaffold/SDK, simulated Connector, deterministic fixtures, and conformance suite.

Acceptance

A concrete Connector can be started without redefining normalized execution, resilience, health, idempotency, evidence, or test contracts.
The simulator can deterministically reproduce the safety-critical failure/replay scenarios required by PH-08.

ENG01-08 — Establish Terraform and environment foundation¶

Objective: Define repeatable infrastructure provisioning and environment isolation on the current-lean cloud (Azure) using the current-lean IaC tool (Terraform) — both open, see §4 and the Decision Register (ENG02-25).

Inputs / Preconditions

Current-lean cloud (Azure, open) and IaC tool (Terraform, open) — see §4/Decision Register ENG02-25 — current-lean runtime/database/messaging/Temporal/observability services (§4), and security constraints.

Required Behavior

Define Terraform repository/module structure, state/locking, resource naming/tagging, environment inputs, secret references, plan/review/apply, and exception handling.
Define isolation for dev/test/stage/prod resources including databases, messaging, Temporal namespaces, AKS namespaces, storage, identities, Vault (and its Key Vault auto-unseal wiring), and Datadog tagging.
Provide enough reusable modules/scaffolding for initial application environments without attempting to build every future infrastructure component.

Writes / Outputs

Terraform skeleton/modules, environment model, state/apply conventions, and IaC review checklist.

Acceptance

Initial environment resources can be provisioned reproducibly through the confirmed IaC tool.
Environment isolation and secret-reference behavior are explicit rather than developer-specific.

ENG01-09 — Establish Datadog and telemetry foundation¶

Objective: Standardize DragonPay operational telemetry using the current-lean observability platform (Datadog, open — see §4 and the Decision Register, ENG02-25) with an OpenTelemetry-compatible application instrumentation boundary.

Inputs / Preconditions

Datadog as the current-lean observability platform (open, see §4/Decision Register ENG02-25), runtime/deployment model, STD-01 telemetry requirements, and sensitive-data constraints.

Required Behavior

Define structured logging, tracing, metrics, service/environment/version naming, correlation/causation, APM integration, dashboards/monitors, deployment markers, Connector/Connection telemetry, and telemetry freshness.
Provide shared instrumentation/configuration so domain modules avoid unnecessary direct Datadog-specific coupling.
Define prohibited sensitive data and evidence handling for logs/traces/metrics, grounded in the data classification list (ENG01-17).

Writes / Outputs

Shared telemetry package/configuration, Datadog conventions, reference dashboard/monitor definitions, and observability checklist.

Acceptance

A reference request/workflow/Connector call is traceable end-to-end with tenant-safe correlation metadata.
Sensitive payment/account/provider payloads are excluded from ordinary telemetry by default.

ENG01-10 — Establish CI/CD and security controls¶

Objective: Define the automated validation, artifact, infrastructure, and environment-promotion path for DragonPay changes.

Inputs / Preconditions

Repository/toolchain, Terraform, testing, runtime/deployment, and security-tool decisions.
Required branch/PR and environment authorization model.

Required Behavior

Define required PR checks for build/compile, lint/format, unit/integration/contract tests, migrations, dependency/SAST/secret/IaC/container scans, and Terraform validation as applicable.
Define artifact/container creation, versioning, deployment/promotion, approval, rollback, and release evidence.
Specify blocking findings and controlled exception handling.
Application/environment promotion must occur through controlled pipeline behavior rather than developer-local production deployment.
Peer review is not a required PR check while the team has 1 developer. Configure branch protection to add a required-approving-review rule the moment the team reaches 2 developers, matching docs/definition-of-done.md.

Writes / Outputs

Initial CI pipeline, deployment pipeline scaffold/design, security gates, branch/PR controls (including the headcount-conditional peer-review rule), and release checklist.

Acceptance

A standard PR receives the required automated validation before merge.
A deployable artifact is reproducibly created and promotable without rebuilding different source for each environment.
Peer review is enforced by branch protection starting the day the second developer's access is provisioned, not before.

ENG01-11 — Establish testing and simulation foundation¶

Objective: Select and provide reusable testing infrastructure for PH/PP implementation.

Inputs / Preconditions

Testing technology decisions, shared packages, database/messaging/Temporal/Connector choices, and TDD expectations.
Representative failure/replay scenarios from STD-01 and PH-08/10/11/12.

Required Behavior

Define unit/integration/contract/workflow/Connector/E2E boundaries and when each is required.
Provide deterministic clock/ID, command/event, persistence, messaging, Temporal, and Connector test helpers/fixtures where recurring use justifies them.
Provide representative tests for duplicate/replay, conflict, concurrency, timeout, unknown outcome, delayed evidence, and failure recovery.
Ensure CI runs foundation conformance tests required by the changed component.

Writes / Outputs

Testing standards, selected libraries, reusable helpers/fixtures, and representative executable test suite.

Acceptance

A PH module can start TDD without building its own test harness for shared platform behavior.
Foundation fixtures reproduce safety-critical failure/replay scenarios deterministically.

ENG01-12 — Establish AI-assisted development framework¶

Objective: Define how AI coding tools are used as a normal part of DragonPay engineering while preserving requirements, architecture, testing, and human accountability.

Inputs / Preconditions

Repository/project scaffold (including the Product-repository reference from ENG01-02), PH/PP/STD/ADR documentation, shared package catalog, CI/testing standards, and Claude Code availability.
Team development/review workflow and security constraints, including the headcount-conditional peer-review rule from ENG01-10.

Required Behavior

Define project-level Claude instructions/context and how the Product-repository baseline is kept current (advance process) so requirements/ADRs/shared contracts supplied to coding agents don't silently go stale.
Define reusable agents/skills for recurring DragonPay development tasks where useful.
Establish requirement understanding -> TDD/test intent -> generated implementation -> human review -> PR -> peer review once the team reaches 2 developers -> CI/conformance workflow.
Require generated code to use approved foundation packages and prohibit invention of undocumented domain behavior.
Define maintenance of AI context as standards/ADRs change, tied to the Product-repository baseline-advance process.

Writes / Outputs

Project AI instructions, initial agents/skills, AI development workflow, and generated-code review checklist.

Acceptance

An engineer can use Claude Code heavily without bypassing PH/STD requirements, testing, peer review (once applicable), or shared architectural contracts.
Ambiguous domain behavior is surfaced for clarification rather than silently invented by the coding agent.
A docs change does not reach coding agents' context until the Product-repository baseline is deliberately advanced.

ENG01-13 — Establish engineering readiness checklists¶

Objective: Capture recurring engineering controls once so PH/PP stories and PR reviews do not repeatedly rediscover platform requirements.

Inputs / Preconditions

STD-01, ENG-01 shared packages, PH security/tenant requirements, CI/testing standards, and recurring findings from PH requirement review.
Initial change types used by DragonPay development.

Required Behavior

Create concise checklists for new API/command, persistent object, material event publisher, event consumer, Connector/external integration, Communication delivery integration, Temporal workflow/activity, privileged operation, Terraform component, and production readiness.
Include applicable checks for command/event idempotency, atomic outbox, authorization, tenant isolation, correlation/causation, replay/conflict handling, sensitive data, resilience, observability, migrations, and tests.
Keep checklists short enough to use in implementation/PR review; link to STD-01/ENG-01 for detailed behavior instead of duplicating requirements.

Writes / Outputs

Version-controlled engineering readiness checklists linked from the developer workflow/PR process.

Acceptance

A reviewer can consistently identify missing cross-cutting controls without rereading every foundation document.
The material-event publisher checklist explicitly verifies atomic domain-write + outbox persistence and asynchronous downstream delivery.

ENG01-14 — Establish initial account and access bootstrap¶

Objective: Establish the first, pre-Terraform, pre-CI access to every vendor account ENG-01 depends on, and the plan for transitioning off founder-level root access once controlled access management exists. Where the vendor itself is still an open §4 decision, "account" here means an exploratory account sufficient to evaluate the option, not confirmation of the decision.

Inputs / Preconditions

The technology baseline (ENG01-01), naming Azure, GitHub, Temporal Cloud, Datadog, and Auth0 as accounts that must exist before any other ENG-01 story can begin — Azure, Temporal Cloud, Datadog, and Auth0 are exploratory pending their §4 decisions (DR-008, DR-007, DR-012, and DR-017 respectively, per the Decision Register); GitHub is not (GitHub is not a §4 decision item).

Required Behavior

Create the initial Azure subscription, GitHub organization, Temporal Cloud account, Datadog account, and Auth0 tenant under founder-controlled credentials.
For a vendor whose §4 row is still "Decision required" (Azure, Temporal Cloud, Datadog, Auth0): the account created here is exploratory and non-committing — a free/trial-tier account sufficient to evaluate the option and unblock other stories' scaffolding work, not the decision itself. The actual decision still requires the Foundation decision-package process (ENG02-15) before Terraform/CI treat that vendor as approved infrastructure; this story does not by itself satisfy that gate. If the decision resolves to a different vendor, the exploratory account is closed rather than migrated.
Record who holds root/owner access to each account and where those credentials are stored (a password manager or equivalent, not ad hoc).
Define the transition trigger and mechanism for moving from founder-held root access to Terraform/CI-provisioned, least-privilege access as the team grows (see ENG01-08, ENG01-10).
This story is sequenced before ENG01-01 through ENG01-13 can be executed against real accounts, even though its story number falls after them; §13 reflects its actual sequencing position.

Writes / Outputs

A short access-bootstrap record: which accounts exist, who holds root access, where credentials live, and the stated trigger for transitioning to managed access.

Acceptance

Every vendor account ENG-01 depends on exists and has a named, findable owner before any other ENG-01 story is executed against it.
The transition-to-managed-access trigger is stated, not left implicit.
No exploratory account for an open §4 vendor is treated, here or in any other ENG-01 story, as satisfying that vendor's Foundation decision-package requirement (ENG02-15).

ENG01-15 — Establish cost and budget governance¶

Objective: Provide visibility and guardrails on Azure spend from the first environment onward.

Inputs / Preconditions

Azure subscription from ENG01-14; Terraform foundation from ENG01-08.

Required Behavior

Configure Azure budgets and alert thresholds scoped to the resource groups Terraform provisions.
Define who receives budget alerts and the expected response (not a blocking gate — a lean startup does not need spend approval workflows yet, just visibility before a surprise bill).
Revisit thresholds as new environments or the first real CU integration (CI-01) add infrastructure.

Writes / Outputs

Documented budget/alert configuration and the named recipient(s).

Acceptance

A budget alert fires before spend materially exceeds the expected range for the current stage of development.

ENG01-16 — Establish backup and disaster-recovery policy¶

Objective: Define a lean, team-size-appropriate backup/restore approach for the canonical Postgres ledger.

Inputs / Preconditions

Persistence direction — managed PostgreSQL as the current-lean engine (§4/DR-005, open); which cloud's managed service also open (current lean: Azure Database for PostgreSQL, see §4/Decision Register ENG02-25; ENG01-04).

Required Behavior

Define automated backup frequency and retention using the confirmed managed PostgreSQL service's own managed backup capability (current lean: Azure Database for PostgreSQL, open — §4/Decision Register ENG02-25) rather than building custom backup tooling.
State an RPO/RTO appropriate to the current pre-revenue stage — this is explicitly not the same bar docs/definition-of-done.md and docs/build-buy.md's "build lean initially" guidance would set for a live paying customer; revisit before CI-01 goes live with real money.
Document the restore procedure and confirm at least one test restore before the first customer-facing environment goes live.

Writes / Outputs

A short backup/DR policy: backup frequency/retention, stated RPO/RTO, and restore-procedure documentation.

Acceptance

A test restore has been performed and documented at least once.
The stated RPO/RTO is explicit rather than assumed.

ENG01-17 — Establish data classification policy¶

Objective: Translate STD01-12's "minimize sensitive data" principle into a concrete, field-level classification engineers can check new tables/logs/telemetry against.

Inputs / Preconditions

STD01-12 security and data-handling baseline; PH-05's protected payment data handling requirements.

Required Behavior

Define classification tiers (e.g. restricted, internal, public) and list representative fields in each tier — Party/Payment Instrument identifiers and account numbers as restricted; operational IDs and status enums as internal; published Product configuration as public.
Apply this list when reviewing what a new table, log line, metric, or event payload is permitted to contain, per ENG01-13's readiness checklists.
Keep the list a living reference updated as new domain objects are added, not a one-time document.

Writes / Outputs

A version-controlled data classification list, linked from the engineering readiness checklists (ENG01-13).

Acceptance

A reviewer can classify a new field's sensitivity without guessing, using this list rather than ad hoc judgment.

ENG01-18 — Establish Web SDK build/distribution ownership boundary¶

Objective: Draw an explicit line between what ENG-01 provides as shared tooling and what CX-01 owns for its Web SDK's own build, distribution, and versioning lifecycle.

Inputs / Preconditions

CX-01's Web SDK stories (SDK build, distribution, developer kit); ENG-01's general API/repository conventions (§6).

Required Behavior

State explicitly that ENG-01 provides the base repository/build toolchain (bundler, lint/test conventions) shared with the rest of the codebase, but that CDN hosting, semantic versioning policy, and browser-compatibility matrix for the distributable SDK package are owned entirely by CX-01.
Avoid ENG-01 growing SDK-specific distribution infrastructure (a CDN, a package registry) unless a concrete CX-01 need requires it.

Writes / Outputs

A short boundary statement in this document (this story) that CX-01 can reference rather than re-deciding.

Acceptance

A CX-01 engineer knows without asking which parts of SDK tooling to build themselves versus reuse from ENG-01.

ENG01-19 — Establish environment and domain naming¶

Objective: Define the naming convention for DragonPay environments and the domain(s) they resolve to, including where a prospective CU will actually see the hosted claim experience.

Inputs / Preconditions

Terraform environment isolation model (ENG01-08); CX-01's hosted Recipient claim experience.

Required Behavior

Define environment names (e.g. dev/test/stage/prod, or DragonPay's preferred equivalents) and how they map to Azure resource naming/tagging.
Register or confirm the domain(s) used for the demo/staging environment shown to prospective CUs, and for each subsequent environment.
Keep this naming referenced from Terraform (ENG01-08) rather than redefined per environment.

Writes / Outputs

A documented environment naming convention and the domain(s) each environment resolves to.

Acceptance

Anyone provisioning a new environment resource follows the same naming convention without inventing one.

ENG01-20 — Establish Communication delivery foundation¶

Objective: Provide reusable CommunicationAdapter scaffolding and deterministic simulation for PH-12's delivery, against the current-lean Twilio/SendGrid providers (open — see §4 and the Decision Register, ENG02-25), mirroring ENG01-07's Connector scaffold pattern.

Inputs / Preconditions

PH-12 CommunicationAdapter contract; the current-lean Twilio/SendGrid notification-delivery technology (open, §4/Decision Register ENG02-25).

Required Behavior

Define a CommunicationAdapter interface/package structure with normalized send/result/evidence hooks, analogous to the Connector scaffold.
Provide concrete Twilio (SMS) and SendGrid (email) adapter implementations behind that interface.
Provide a deterministic simulated adapter for testing delivery success, rejection, and provider-unavailable scenarios without sending real messages outside production.
Keep PH-12's domain decisions (which communication codes exist, retry/expiration policy) out of the shared adapter — the adapter owns transport mechanics only, matching the Connector/domain boundary already established for PH-08.

Writes / Outputs

CommunicationAdapter scaffold/SDK, Twilio/SendGrid implementations, simulated adapter, and test fixtures.

Acceptance

PH-12's CommunicationAdapter.send contract can be implemented against the confirmed SMS/email providers (current lean: Twilio/SendGrid) without PH-12 redefining transport-level retry, evidence, or result normalization.
The simulated adapter can deterministically reproduce delivery success/rejection/unavailable scenarios for non-prod testing.

ENG01-21 — Establish AKS and Istio service mesh foundation¶

Objective: Provision the Azure AKS cluster and Istio service mesh that application services and workers run on, conforming to the parent PE company's shared platform stack.

Inputs / Preconditions

Runtime/deployment decision (managed Kubernetes + Istio, current lean — §4/DR-009, open; Azure AKS specifically, §4); Terraform foundation (ENG01-08, currently open — see §4); account bootstrap (ENG01-14).

Required Behavior

Provision an AKS cluster per environment (or per-environment namespace within a shared non-prod cluster, sized for current team/stage) through Terraform.
Install and configure Istio: Gateway for TLS termination at the edge, mTLS enforced for in-cluster service-to-service traffic, matching the parent's Azure Load Balancer -> Istio Gateway -> mTLS -> AKS topology.
Define namespace conventions, resource/quota baselines, and how a new domain module/service gets deployed into the cluster without inventing its own topology.
Keep the cluster/mesh configuration itself in Terraform, not manually applied.

Writes / Outputs

Terraform modules for the AKS cluster and Istio installation/configuration, namespace conventions, and a deployment guide for adding a new service.

Acceptance

A reference service can be deployed into the cluster and reached through the Istio Gateway with TLS termination and in-cluster mTLS demonstrated.
Cluster/mesh configuration is reproducible from the confirmed IaC tool (current lean: Terraform), not a manual one-off.

ENG01-22 — Establish HashiCorp Vault secrets foundation¶

Objective: Provide pod-injected secret delivery via HashiCorp Vault, conforming to the parent PE company's shared platform stack, narrowing Azure Key Vault to Vault's own auto-unseal role.

Inputs / Preconditions

Secrets decision (HashiCorp Vault, current lean — §4/DR-011, open); AKS cluster foundation (ENG01-21); Azure Key Vault availability for auto-unseal.

Required Behavior

Deploy Vault and configure Azure Key Vault auto-unseal so Vault does not depend on a manually-entered unseal key at every restart.
Configure pod-startup secret injection (e.g. a sidecar/init-container pattern) so application code reads secrets from its local filesystem/environment rather than calling Vault's API directly at request time.
Define secret path/namespace conventions per environment and per domain module, and the rotation process.
Ensure no secret value is ever committed to application configuration, Terraform state, or a Connection record — only references (per STD01-12 and ENG01-03's shared configuration/secrets package).

Writes / Outputs

Vault deployment configuration, auto-unseal wiring, pod-injection pattern/reference implementation, and secret path/rotation conventions.

Acceptance

A reference service starts with secrets already present in its environment via pod injection, without calling Vault's API itself.
Vault survives a restart without manual unseal intervention.

ENG01-23 — Establish backend/frontend framework foundation¶

Objective: Scaffold the current-lean NestJS (backend, §4/DR-002, open) and Next.js (frontend/BFF, §4, open) frameworks as the concrete implementation of ENG01-02's repository/application scaffold and ENG01-04's API conventions.

Inputs / Preconditions

Backend/frontend framework current leans (NestJS 11, Next.js App Router — §4, open); repository scaffold (ENG01-02); persistence/API conventions (ENG01-04).

Required Behavior

Scaffold a reference NestJS module structure (controllers, providers, guards) that ENG01-04's reference command/read endpoints are built on, and that ENG01-24's guard chain plugs into.
Scaffold a reference Next.js application structure for any DragonPay-side frontend (starting with OX-01's Ops console), including the BFF role ENG01-24 depends on.
Define how NestJS and Next.js projects are organized within the repository strategy chosen in ENG01-02 (e.g. as workspace packages), not as a separate, differently-conventioned project.

Writes / Outputs

Reference NestJS backend scaffold and reference Next.js frontend/BFF scaffold, wired into the repository from ENG01-02.

Acceptance

A new backend module can be started from the NestJS scaffold without inventing its own controller/provider/guard structure.
A new frontend surface can be started from the Next.js scaffold without inventing its own BFF/session pattern.

ENG01-24 — Establish Auth0 BFF integration and authorization guard chain¶

Objective: Implement the concrete Auth0 integration pattern DragonPay's operational/workforce identity uses, conforming to the parent PE company's shared platform architecture — a BFF that holds all tokens server-side, a backend that treats JWT claims as bootstrap metadata only, and an explicit decision not to use Auth0 Organizations.

Inputs / Preconditions

Identity decision (Auth0, current lean — §4/DR-017, open); NestJS/Next.js scaffolds (ENG01-23); PH-01 trusted auth context, machine access, and authorization enforcement requirements.

Required Behavior

The Next.js BFF holds access_token/id_token/refresh_token server-side only; none reach the browser. The browser receives only an HttpOnly/Secure/SameSite=Lax session cookie.
Authorization Code Flow with confidential client authentication (client_secret) between the BFF and Auth0; PKCE evaluated as an additional defense-in-depth layer, not currently required.
JWT custom claims are treated as session-bootstrap metadata only, never as the authorization source of truth. The NestJS backend re-resolves tenant membership and the full permission set from PostgreSQL on every protected request via the guard chain below.
Implement the guard chain on every protected backend request: JwtAuthGuard (validates the Auth0 JWT via JWKS, RS256) -> TenantGuard (validates the user has access to the requested Tenant) -> PermissionGuard (resolves the full permission set from PostgreSQL per PH-01 and checks the required permission).
Machine-to-machine calls (e.g. an Auth0 Action or another backend service calling this backend) use Client Credentials Grant; the backend validates the gty: client-credentials claim so a user-issued token cannot be replayed against an M2M-only endpoint.
Fail-closed authentication: if role/permission resolution fails during login, no session is issued rather than issuing a degraded/partial one.
Do not use Auth0 Organizations. Recorded explicitly per a parent-company shared-platform integration that attempted Organizations for a consumer multi-tenant model and abandoned it — DragonPay's Auth0 usage is workforce/operational only (P2P senders/recipients authenticate through their CU's own digital banking session per PH01-05, never through DragonPay's Auth0), so the problem Organizations solves for the parent doesn't arise here; PH-01's tenant/role/scope model is the authorization source of truth regardless.
Apply the §9 Auth0 security-controls checklist (MFA, password policy, brute-force protection, RS256, JWKS caching, CORS whitelist, dual session termination, M2M gty validation).

Writes / Outputs

Reference BFF session-management implementation, reference JwtAuthGuard/TenantGuard/PermissionGuard chain, M2M Client Credentials integration, and the recorded decision against Auth0 Organizations.

Acceptance

No Auth0 token is observable from the browser at any point in the sign-in flow.
A request with a valid JWT but no matching PH-01 permission is rejected by PermissionGuard, not by trusting a token claim.
A user-issued token presented to an M2M-only endpoint is rejected via the gty check.
If backend role/permission resolution is unavailable during login, no session is issued.

13. Initial implementation sequence¶

Establish the initial account/access bootstrap (ENG01-14) — every other story depends on these accounts existing.
Establish the technology/library baseline and ADR process (ENG01-01).
Establish repository/application scaffold, developer setup, the Product-repository reference, and the NestJS/Next.js framework scaffolds (ENG01-02, ENG01-23).
Select persistence, API, messaging, testing, and supporting libraries needed by the first PH work (ENG01-04, ENG01-05).
Scaffold STD-01 shared packages, including command context, idempotency, event envelope, transactional outbox, consumer deduplication, correlation/causation, and technical errors (ENG01-03).
Provide the reference persistence/API implementation including atomic domain-write + outbox behavior (ENG01-04).
Establish Terraform/environment conventions, environment/domain naming, cost/budget governance, the AKS/Istio cluster, and HashiCorp Vault; provision only the infrastructure needed for initial development (ENG01-08, ENG01-15, ENG01-19, ENG01-21, ENG01-22).
Establish the backup/disaster-recovery policy for the persistence layer just provisioned (ENG01-16).
Establish the Auth0 BFF integration and authorization guard chain, now that the AKS/Vault/framework foundation exists to run it on (ENG01-24).
Establish Datadog/OpenTelemetry instrumentation and baseline operational visibility, grounded in the data classification list (ENG01-09, ENG01-17).
Establish Temporal namespace/worker/workflow conventions before PH-04 workflow implementation depends on them (ENG01-06).
Establish Connector scaffold, simulator, and conformance fixtures before concrete external Connector implementation (ENG01-07).
Establish Communication delivery scaffold, simulator, and Twilio/SendGrid implementations before concrete PH-12 delivery work (ENG01-20).
Establish CI/CD, security scans, and foundation conformance checks, including the headcount-conditional peer-review gate (ENG01-10).
Publish reusable testing helpers/fixtures and the AI-assisted development framework (ENG01-11, ENG01-12).
Publish engineering readiness checklists (ENG01-13).
Document the Web SDK build/distribution ownership boundary before CX-01's SDK work begins in earnest (ENG01-18).
Refine shared components incrementally as real PH implementation demonstrates additional repeated needs; do not pre-build generalized internal platforms.

14. Out of scope¶

Payment, Product, channel, operator, risk, routing, execution, reconciliation, Case, communication, reporting, or other business-domain implementation owned by PH/PP/CX/OX requirements.
Building every possible shared library before Product work begins.
Building every future Connector or provisioning every future provider/CU integration.
Premature selection of technologies with no near-term implementation dependency.
General-purpose internal developer platforms, rules engines, workflow designers, service meshes, or abstraction layers unless actual scale/usage demonstrates the need.
Moving domain-specific retry authorization, payment state, risk policy, matching, routing, or Product behavior into shared technical packages.
Requiring all foundation stories to complete before any PH implementation can begin; dependencies should be sequenced according to actual work.
Treating Datadog, Temporal, Terraform, or other vendor/tool choices as business-domain contracts where a stable technical boundary can preserve future replaceability.
A formal spend-approval workflow, SOC 2 certification program, or enterprise access-governance tooling — these are real future needs, sized for a team and customer base this stage does not have yet.
Auth0 Organizations. DragonPay's Auth0 usage is workforce/operational identity only — P2P senders/recipients authenticate through their CU's own digital banking session, never through DragonPay's Auth0 — so the consumer multi-tenant/branding problem Organizations solves does not arise here. A parent-company shared platform attempted Organizations for exactly that problem and abandoned it after encountering RBAC-model mismatches; recorded here so DragonPay doesn't repeat that evaluation.
The consumer-facing multi-tenant/vertical/organization data modeling patterns from other shared-platform products in the parent PE company's portfolio — DragonPay's Tenant model (one CU, one Product at launch) is materially simpler and should not import that complexity preemptively.

15. Completion criteria¶

Initial development can begin without engineers independently selecting foundational cloud/runtime, persistence, messaging, IaC, observability, orchestration, testing, security, or repository technologies.
Azure, the managed PostgreSQL service, Terraform, Datadog, Temporal, Twilio/SendGrid, TypeScript/Node 22, NestJS, Next.js, Prisma, managed PostgreSQL as the database engine, managed Kubernetes/Istio, HashiCorp Vault, and Auth0 — see §4 and the Decision Register (ENG02-25) for each one's current decided/open status — have documented ownership, classification, current decided/open status, and usage expectations. (OpenTelemetry-compatible instrumentation, §4's Application telemetry row, is a standing engineering standard rather than a §4 decision item and is intentionally not part of this list.)
Repository/application scaffolding, local developer setup, and the Product-repository reference are available.
Persistence, API, messaging, configuration, environment, testing, and CI/CD conventions are explicit.
STD-01 command context, event envelope, command idempotency, transactional outbox, consumer replay/deduplication, correlation/causation, and shared technical errors have reusable implementation patterns or reference scaffolds.
Atomic material domain-write + outbox persistence is demonstrated by executable reference implementation/tests.
Temporal usage, environment isolation, workflow/activity boundaries, retry ownership, versioning, and testing are defined.
Connector development has a reusable scaffold, deterministic simulator, conformance tests, and shared resilience/health/idempotency/evidence contracts.
Communication delivery has a reusable scaffold, deterministic simulator, and working implementations against the confirmed SMS/email providers (current lean: Twilio/SendGrid).
The AKS cluster and Istio service mesh are provisioned from the confirmed IaC tool (current lean: Terraform), with a reference service reachable through the Gateway/mTLS topology.
HashiCorp Vault is deployed with Azure Key Vault auto-unseal, and a reference service demonstrates pod-injected secrets without calling Vault's API directly.
The Auth0 BFF integration demonstrates tokens never reaching the browser, the JwtAuthGuard/TenantGuard/PermissionGuard chain enforcing PH-01 authorization from PostgreSQL rather than token claims, and the decision against Auth0 Organizations is recorded.
The confirmed IaC tool's (current lean: Terraform) environment isolation, environment/domain naming, and Vault/secrets conventions are defined and reproducible for initial environments.
Datadog/OpenTelemetry observability conventions and sensitive-data restrictions are defined and demonstrated, grounded in the data classification list.
CI and security controls validate the foundation and downstream modules consistently, including a peer-review gate that activates automatically once the team reaches 2 developers.
AI-assisted development has explicit project context, workflow, review, and conformance expectations, including how the Product-repository baseline is kept current.
Common engineering changes have concise readiness checklists used during implementation/PR review.
Deferred decisions are explicitly recorded rather than decided ad hoc inside downstream PH work.
The initial account/access bootstrap is complete, with a named owner for each vendor account and a stated transition plan to managed access.
Cost/budget alerts and a backup/DR policy exist for the initial environment.
The Web SDK build/distribution ownership boundary is documented.
ENG-01 remains a focused engineering foundation and does not become an owner of payment-domain behavior.