Eve library

ADR-0006: Transaction Service Consolidation Strategy

ADR

Revision 1

On this page

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-core to 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:
    • TransactionStatus enum and nextState guard
    • buildTransactionId idempotent-friendly ID helper
    • validateTransferRequest baseline validator
  • Kept helpers small; adoption can be incremental per service.

Testing#

  • Unit tests in transaction-core cover 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.