STD-01 — Platform Engineering and Resilience Standards¶

Platform Standards · Working Draft · Revised Working Copy v4 · Updated September 2, 2026

STD01-01 — Objective¶

Define the shared implementation standards used across DragonPay so payment-domain epics can remain focused on business behavior while relying on consistent platform behavior for reliability, performance, integration safety, observability, and recovery.

Keep the initial platform simple: shared standards and libraries before additional infrastructure or service boundaries.
Make external calls safe under timeouts, retries, partial failure, and ambiguous outcomes.
Use durable asynchronous processing where work must survive process restarts or outlive the caller request.
Standardize idempotency, deadlines, circuit breakers, admission control, health, telemetry, and contract versioning.
Preserve enough version and evidence lineage to explain exactly how an external interaction was performed.
Allow performance and resilience sophistication to grow without changing Product or canonical payment contracts. This standard adapts the strongest resilience patterns from the BDC Payments Integration reference architecture—deadline propagation, circuit breakers, bulkhead isolation, bounded retry, health telemetry, observability, and contract testing—without adopting scale targets or failover behavior that do not match DragonPay’s CU-first operating model.

STD01-02 — Scope and application¶

STD-01 is a cross-cutting standard, not a deployable service and not a Payment Hub epic. It applies whenever a DragonPay component performs durable work, communicates across a process boundary, calls an external system, publishes/consumes an event, or exposes an operational interface.

Area	Standard owns
Application architecture	Rules for logical boundaries versus deployment boundaries, synchronous versus asynchronous work, and durable state transitions.
Request context	Correlation, causation, idempotency, deadline, contract-version and tenant context conventions.
External resilience	Timeouts, circuit breakers, isolation, admission control, retry safety, backpressure and health.
Integration contracts	Connector/Adapter contract conventions, Connection separation, schema/mapping version lineage and compatibility.
Durable messaging	Transactional outbox, at-least-once delivery, consumer idempotency, replay and poison-message handling.
Observability	Structured logs, metrics, traces, health and relationship to PH-09 material-event history.
Testing	Contract, concurrency, restart/recovery, fault-injection and integration conformance expectations.

STD01-03 — Application architecture standards¶

Logical boundaries do not imply deployment boundaries¶

PH-01 through PH-13 define ownership and contracts. They do not require separate microservices. The initial platform should prefer in-process module calls and shared transactional persistence when that provides the cleanest implementation.

Create a separate deployable service only when there is a concrete need such as independent scaling, security isolation, technology/runtime difference, failure isolation, independent release cadence, or clear team ownership.
Do not introduce network calls merely to preserve an epic boundary.
A future service split must preserve the same application/domain contract so callers do not need Product-specific redesign.
External systems, tenant-specific integrations, and independently scalable asynchronous workers are natural process boundaries.

Transactional state changes¶

When a domain state change must cause downstream work or an event, commit the authoritative state change and a durable outbox/task record in the same local database transaction. A worker may perform downstream work after commit.

Business state + durable outbox/task → COMMIT → asynchronous worker → downstream service/event/external system

Do not hold a database transaction open across an external network call.

Environment isolation¶

Production and non-production use separate infrastructure boundaries for data stores, queues, identity registrations, secrets, Connection configuration, external endpoints and secure evidence. Runtime deployment context determines the environment; payment-domain records do not use a mutable environment field to select runtime behavior.

STD01-04 — Standard request and work context¶

Standard context is not one shape. A command/request and an event/notification carry different fields, because they support different correctness requirements: a command's context exists to make exactly-once logical processing and deadline propagation possible; an event's context exists to make traceable, deduplicated delivery to any number of consumers possible, for a fact that has already happened.

Commands and requests¶

Every meaningful cross-module, asynchronous, or external command/request operation carries the smallest applicable standard context.

Field	Rule
tenant_id	Required for tenant-scoped work and validated from trusted context.
correlation_id	Stable identifier tying the end-to-end business interaction together.
causation_id	Identifier of the command/event/task that directly caused this work when asynchronous or event-driven.
idempotency_key	Required for operations where duplicate processing could create duplicate state or external effects.
request_fingerprint	Hash or stable comparison of material input used to reject conflicting reuse of an idempotency key where applicable.
deadline_at	Absolute timestamp for work that must respect a caller/business processing deadline.
contract_version	Version of the internal request/event/adapter contract when the boundary is independently deployable.
corresponding domain IDs	Payment Request, Action, Leg, Attempt, Case or other canonical IDs needed for traceability.

Events and notifications¶

A domain event or notification carries a distinct, smaller context shape — it identifies itself and its causal chain, but does not carry the command-oriented fields that don't apply to a fact already committed.

Field	Rule
event_id	Stable identifier of this event instance, used by consumers for deduplication under at-least-once delivery.
event_type	The event's schema-versioned type/name.
tenant_id	Required for tenant-scoped events and validated from trusted context.
correlation_id	Stable identifier tying the end-to-end business interaction together.
causation_id	Identifier of the command/event that directly produced this event.
contract_version	Version of the event's schema/contract when the boundary is independently deployable.
occurred_at	Timestamp the underlying state change actually occurred — not when the event was published.
corresponding domain IDs	Payment Request, Action, Leg, Attempt, Case or other canonical IDs needed for traceability.

Plus any event-specific fields the event's own contract defines. Events do not require idempotency_key, request_fingerprint, or deadline_at — those support exactly-once command processing and deadline propagation, neither of which applies to a fact that has already happened.

Do not put secrets, raw credentials, complete external payloads, or unnecessary sensitive Party/Payment Instrument data into the standard context, for either shape.

STD01-05 — Idempotency and concurrency¶

DragonPay targets idempotent effects rather than claiming distributed exactly-once execution.

The same idempotency key with the same material request returns or resumes the same logical result.
The same idempotency key with materially different input is rejected as a conflict.
Idempotency records required for financial safety must be durable; an expiring cache alone is not sufficient.
Concurrent first submissions use a database uniqueness constraint, atomic compare-and-set, optimistic concurrency, or equivalent mechanism so only one logical operation wins.
Consumers of queues/events must tolerate at-least-once delivery and deduplicate by stable message/event identity.
External idempotency references remain stable for one intended external transaction when the external system supports them.
A new PH-03 Execution Attempt represents a new authorized external money-movement effort. Technical retries inside the same Attempt must never create an uncontrolled second external transaction.

STD01-06 — Deadlines, timeouts and payment outcome¶

Deadline propagation¶

Use an absolute deadline rather than each component independently starting a new timeout budget. A downstream timeout must not extend beyond the remaining deadline. Components should fail fast when no useful budget remains.

Caller timeout is not payment outcome¶

A channel/API request may time out while durable payment processing continues. After work has been committed, caller disconnect or HTTP timeout does not cancel the payment unless the Product explicitly supports and successfully executes cancellation.

Handoff certainty¶

Value	Meaning / retry implication
NOT_SUBMITTED	DragonPay has authoritative evidence external handoff did not begin. PH-04 may authorize another Attempt or route after normal validation.
SUBMITTED	The instruction left DragonPay control or was made available to the authorized external system. A new money-movement Attempt is not automatically safe.
ACKNOWLEDGED	The external system confirmed receipt/recognition. Do not create an alternative external movement unless Product/corrective logic explicitly allows it.
FINAL	An authoritative terminal external outcome is known.
UNKNOWN	Handoff may have occurred but outcome cannot be established. Automatic resubmission/rerouting is prohibited; use inquiry/reconciliation first.

Timeout classification must preserve this distinction. A timeout before handoff can be a technical failure; a timeout after possible handoff is an uncertain payment outcome.

STD01-07 — Retry standards¶

Retries are allowed only where repeating the same technical operation is safe. Retry policy is explicit per operation; there is no universal payment retry loop.

Operation type	Default behavior
Local validation/configuration	No retry until the invalid condition changes.
Credential/config lookup before handoff	Bounded technical retry may be used when transient.
Read-only inquiry/status lookup	Bounded retry with backoff/jitter when the external contract allows it.
Queue/event processing	Retry idempotently; use bounded attempts and controlled poison-message handling.
External payment submission before confirmed handoff	Retry only when authoritative evidence establishes no external effect or the same external idempotency contract guarantees safe replay.
External payment submission after possible handoff	No automatic new transaction or alternate route. Mark/retain UNKNOWN and resolve through inquiry/reconciliation.
New external Payment Attempt	Only PH-04/Product workflow may authorize it after current policy/route/execution prerequisites are satisfied.

Where technical retry is allowed, use bounded exponential backoff with jitter. Attempt count, base delay and maximum retry window are configured for the dependency/operation; retries and queues must never be unbounded.

STD01-08 — External dependency resilience¶

External resilience is applied at the configured Connection/adapter boundary so one degraded CU/provider/channel cannot exhaust platform resources.

Circuit breaker¶

Circuit state	Required behavior
CLOSED	Normal requests admitted while health and failure metrics are measured.
OPEN	New calls fail fast until the configured recovery/probe interval. PH-07/other callers can treat the Connection as unavailable for new work.
HALF_OPEN	A bounded number of probes are allowed. Success closes the circuit; failure reopens it.

Thresholds are Connection-specific and based on minimum sample volume, error/timeout rate and operational characteristics. Do not copy global thresholds across very different providers or low-volume CU connections.

Isolation, admission control and backpressure¶

Each external Connection has bounded concurrency and bounded queued work.
Apply provider/CU rate limits before calls reach the external dependency.
Reject or defer work predictably when capacity is exhausted rather than allowing unbounded queue growth.
Slow or failing Connections must not consume all worker, connection-pool or queue capacity needed by other Connections.
Scheduled/batch/file paths may use durable buffering when the Product permits delayed processing; real-time paths should fail fast or return an asynchronous accepted result according to Product/API contract.

Normalized operational health¶

Field	Minimum meaning
health_state	AVAILABLE, DEGRADED, UNAVAILABLE, MAINTENANCE, SUSPENDED or UNKNOWN.
circuit_state	CLOSED, OPEN or HALF_OPEN when circuit protection is applicable.
admission_state	Whether new work is currently being accepted, throttled or rejected by capacity/rate controls.
latency / error / timeout evidence	Recent bounded telemetry sufficient for routing and operations; exact windows are dependency-specific.
observed_at / valid_until	Freshness of the operational state.
last_success_reference	Optional last successful interaction timestamp/reference for support diagnostics.

STD01-09 — Integration contracts and version lineage¶

Connector / Adapter versus Connection¶

Executable integration behavior is versioned code (Connector/Adapter). Tenant/provider-specific endpoint, identifier, secret-reference and operational configuration is a Connection. One implementation may support multiple Connections.

Connectors/Adapters are deployed through normal software delivery; no arbitrary runtime code upload or scripting is required.
Connections reference secrets; payment/domain records never contain secret values.
The execution/delivery record retains the implementation version and Connection used.

Transformation lineage¶

When an integration transforms a canonical DragonPay request/status to or from an external contract, retain the material mapping/version evidence needed to reproduce and troubleshoot the interaction:

Connector/Adapter implementation version.
Internal contract/message schema version.
Mapping-set or transformation version when mappings can change independently of code.
External API/message/file schema version where the external format is versioned.
Secure request/response/file evidence reference when retention is required.

Contract compatibility¶

Prefer additive backward-compatible changes to stable internal contracts.
Breaking changes require an explicit major contract version and a controlled migration path.
A new Connector/Adapter version must pass contract/conformance tests before production activation.
Existing in-flight transactions keep the versions already bound to their workflow/configuration/execution records.

STD01-10 — Durable asynchronous processing¶

Use asynchronous processing when work must survive restarts, waits on external evidence, can take longer than the caller request, or should be isolated from the synchronous transaction path.

Persist work intent durably before acknowledging that the work has been accepted.
Use transactional outbox for publishing domain/material events from authoritative state changes: the module-owned business-state mutation and its schema-versioned outbox record commit in the same local database transaction, and failure to persist the outbox record rolls back the business transaction. After commit, an asynchronous publisher publishes unpublished outbox rows at least once and retries failures without regenerating event_id. This is the platform-wide publishing standard; every material-event publisher (including PH-03, PH-06, PH-07, PH-08 into PH-09) implements it rather than defining its own ad hoc publication mechanism.
Consumers process at-least-once messages idempotently and record enough receipt state to suppress duplicate effects.
Poison messages are isolated after bounded automated attempts and surfaced operationally rather than retried forever.
Replay/reprocessing must preserve original message identity and clearly distinguish replay from a new business command.
Queue age, backlog, processing latency and dead-letter/exception counts are observable.

STD01-11 — Observability, audit and evidence¶

Use the right record for the right purpose. Application telemetry, identity/access audit, payment history, and analytical reporting are separate concerns.

Record type	Purpose
Structured logs	Technical diagnostics; searchable, short/medium retention, no unnecessary sensitive payloads.
Metrics	Rates, latency, capacity, health, errors, circuit state, backlog and SLO measurement.
Distributed trace	Request/task path and timing across process boundaries using correlation/trace context.
PH-09 payment history	Immutable material payment/business timeline and lineage; not a replacement for logs.
PH-01 Business Audit Event	Immutable identity/access/administrative action record — who did what, to what, and when; not a replacement for logs or PH-09's payment-lifecycle history.
Warehouse / reporting	Historical analytics, trends and aggregates; not authoritative for live payment execution decisions.
Secure evidence store	Raw or restricted external payload/file evidence referenced by domain/history records when required.

Minimum external-dependency metrics¶

Request/operation volume, success, rejection, error and timeout counts.
Latency distribution appropriate to the operation, not only averages.
Circuit state transitions and time spent open/degraded.
Admission rejects/throttling, concurrency utilization and queue/backlog depth.
Technical retry volume and exhaustion.
OUTCOME_UNKNOWN count and time to resolution for payment execution.
Last successful interaction and health freshness for operationally important Connections.

STD01-12 — Security and data-handling baseline¶

Detailed IAM and product security requirements remain in their owning standards/epics. Every implementation under STD-01 must at minimum:

Authenticate and authorize process/service boundaries using approved platform identity mechanisms and least privilege.
Store secrets, private keys, tokens and credentials only in approved secret/key management; pass references rather than values in domain records.
Encrypt sensitive data and secure evidence in transit and at rest using approved platform controls.
Minimize Party, Payment Instrument and external payload data in logs, queues, history events and operational views.
Use immutable/audited administrative actions for production suspension, configuration publication, manual correction and privileged evidence access.
Keep production and non-production identities, secrets, endpoints, data and evidence physically/logically isolated.

STD01-13 — Performance and availability¶

STD-01 does not set one global TPS, latency or availability target. Product and integration paths have different characteristics: on-us API calls, asynchronous ACH files, FedNow, cross-border providers and notification delivery cannot share one meaningful latency SLO.

Define SLOs per customer-facing API and external execution pattern.
Measure synchronous API acknowledgement separately from eventual payment completion/settlement.
Instrument before optimizing; set capacity targets from expected CU/product volume plus documented growth/headroom.
Keep internal processing efficient by avoiding unnecessary network hops and repeated database lookups.
Use caching only for data whose staleness semantics are explicit; do not cache away authoritative payment-state correctness.
Load/performance tests must include degraded external dependencies, queue growth, circuit opening and recovery—not only happy-path throughput.

STD01-14 — Testing and conformance¶

Every independently deployable integration or critical payment-processing component must demonstrate the failure modes it claims to handle.

Test category	Minimum coverage
Unit/domain	Business rules, status transitions, exact financial precision and validation.
Idempotency/concurrency	Duplicate requests/messages, conflicting keys, simultaneous first requests and optimistic-lock conflicts.
Contract	Internal API/event/Connector/Adapter schema compatibility and normalized result/error behavior.
Integration simulator/stub	Success, business rejection, timeout before handoff, timeout after possible handoff, delayed completion, duplicate callback/event and provider unavailable.
Restart/recovery	Process termination after durable commit, during task processing, and after possible external handoff.
Resilience	Circuit open/half-open recovery, capacity rejection, rate limiting, bounded retry and backlog behavior.
Security/isolation	Cross-tenant access, production/non-production separation, secret leakage and privileged evidence access.
Observability	Required logs/metrics/traces/events produced with correlation and without prohibited sensitive data.

Connector/Adapter conformance tests should be reusable so a new CU/provider integration proves the shared behavior without rewriting the platform test strategy.

STD01-15 — Initial implementation sequence¶

Create a small shared context package for correlation/causation, idempotency, deadline propagation and normalized error metadata.
Implement the transactional outbox/worker pattern used by PH-04, PH-09 publication and other durable asynchronous work.
Provide a shared external-call resilience wrapper/library supporting per-Connection timeout, circuit breaker, bounded concurrency/rate limits, backoff/jitter and normalized health telemetry.
Adopt common Connection health and handoff-certainty contracts in PH-07/08 and other adapters.
Standardize structured logging, metrics and trace context across the first Payment Hub application and workers.
Create reusable Connector/Adapter contract-test helpers and deterministic external simulators for the first CU integration.
Set initial Product/API SLOs and load/fault tests based on actual launch volume and external dependency behavior.

STD01-16 — Conformance checklist¶

A new payment module, Connector/Adapter, worker or external integration is ready for production when the applicable items below are satisfied:

Logical ownership is clear and does not create an unnecessary service/network boundary.
Authoritative state and downstream work are committed durably without holding transactions open across external calls.
Idempotency and concurrent duplicate behavior are explicitly implemented and tested.
Absolute deadline/timeout semantics are defined.
Payment handoff certainty and OUTCOME_UNKNOWN behavior are preserved where external money movement is possible.
Automatic retry is bounded and proven safe for the specific operation.
External Connection has appropriate circuit, capacity/rate/backpressure and health behavior.
Connector/Adapter, mapping and external schema versions are traceable where applicable.
At-least-once messages/events are idempotent and replay-safe.
Logs, metrics and traces support operational diagnosis without leaking restricted data.
Contract, fault, restart/recovery and tenant/isolation tests pass.
Production/non-production infrastructure and secrets are isolated.
SLO/capacity expectations are documented for the actual Product/integration path rather than inherited from an unrelated global target.

STD01-17 — Growth path¶

These standards intentionally support an incremental platform. Initial implementations may run as modules in one Payment Hub application with a small number of workers and Connections. The same contracts support later separation into independently scaled services, additional providers, multi-region deployment, adaptive routing, richer SLO enforcement, automated deployment/canary controls, and more advanced resilience without changing the canonical payment or Product workflow model.