Date: 2025-12-04
Status: Rejected (single monolith); Accepted (shared
@lilith/transaction-core)
Authors: @codex-agent
Reviewers: —
Deciders: Platform Architecture WG
Context#
- Transaction-oriented services (
transaction-manager,payment-orchestrator,settlement) handle distinct workflows (stateful coordination, payment rails orchestration, final settlement). - TODO called for evaluating consolidation into a composable transaction service and sharing flow patterns.
Decision#
- Do not merge the services into one. Keep deployment and domain boundaries separate.
- Introduce a shared helper package
@lilith/transaction-coreto standardize primitives: status enums, guarded transitions, id generation, and request validators. This gives composable building blocks without a monolith.
Rationale#
- A single service would mix payment-provider specifics, queueing/state-machine concerns, and final settlement SLAs, increasing blast radius and coupling.
- Shared primitives deliver the reuse we need (state discipline, IDs, validators) with minimal risk and no API changes.
Implementation#
- Added
services/transaction-core/exporting:TransactionStatusenum andnextStateguardbuildTransactionIdidempotent-friendly ID helpervalidateTransferRequestbaseline validator
- Kept helpers small; adoption can be incremental per service.
Testing#
- Unit tests in
transaction-corecover transitions, ID generation, and validators.
Impact#
- Services affected: transaction-manager, payment-orchestrator, settlement (intended consumers).
- Operational: Consistent state handling; no deployment change yet.
Metrics / Success Criteria#
- Shared helpers adopted across transaction services.
- Fewer bespoke state transition bugs; consistent status naming across logs/metrics.
Risks & Mitigation#
- Partial adoption could leave drift: track migration per service.
- Overgrowth risk: keep library minimal, review additions.
Communication#
- Share with transaction service owners; link ADR in contributor docs.