4.1 KiB
title, tags, created, status, reviewers
| title | tags | created | status | reviewers | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Backend Core Stack Decision Record - 2026-05-24 |
|
2026-05-24 | approved |
|
Backend Core Stack Decision Record - 2026-05-24
1. Decision
Keep the security-critical backend core on TypeScript/Node in the first 12 months.
Do not perform a full greenfield rewrite before the payment/auth/escrow core is fully specified and observable.
2. Why this stack (today)
The highest current risk is not framework selection; it is financial state correctness.
For the next phase, the team needs:
- provider-neutral payment abstraction,
- immutable funds ledger,
- webhook hardening and reconciliation,
- strict dispute hold behavior,
- admin step-up controls,
- production-grade operational runbooks.
Moving to Go/Kotlin/Rust now would preserve existing risks while adding migration uncertainty and a delay in launch-readiness.
TypeScript remains the fastest way to ship the required controls while keeping operational visibility and team velocity.
3. Scope of extraction
The “backend core” now means:
Paymentorchestration and payout/release state transitions,- auth/session validation for financial actions,
- webhook intake and reconciliation,
- ledger-derived escrow eligibility checks,
- admin-risk operations (payout/refund/adjustment).
These modules stay in the same service boundary during migration-in-place, but all calls must go through:
- Payment Provider Adapter Spec
- Webhook Security Spec
- Funds Ledger and Escrow State Machine Specification
Non-core modules remain where they are:
- marketplace browsing, templates, shop settings,
- chat and notifications,
- file uploads/downloads.
4. Evaluation of alternatives
Go
- Pros: smaller runtime and dependency surface, better static guarantees.
- Cons: highest immediate migration cost, new operational tooling, delayed delivery of core money-movement correctness.
Kotlin/Java
- Pros: strong enterprise ecosystem, mature auth/security libraries.
- Cons: heavier stack and slower delivery for a small team.
Rust
- Pros: high correctness potential.
- Cons: steep delivery cost and limited team familiarity.
Keep TypeScript (selected)
- Pros: existing team velocity, reduced migration risk, direct integration with current deployment and frontend contracts.
- Cons: npm supply-chain risk remains; mitigated by Secure Build and Supply-Chain Policy and strict dependency policy.
5. Migration and rollout plan
- Phase A (this quarter): lock down high-risk flows in TypeScript (ledger, adapter, webhook, auth/session, runbooks).
- Phase B (next two quarters): extract core services behind stable interfaces and add adapter-level contract tests.
- Phase C (deferred): evaluate Go/Kotlin pilot for payout+webhook worker only if:
- Phase A and B are stable for 60 days,
- team staffing supports dual-stack operations,
- audit requirements demand lower runtime dependency exposure.
6. Non-goals
- Full frontend rewrite.
- New language migration without closed-loop reconciliation and signed-state invariants.
- New provider support that bypasses the adapter contract.
7. Rollback criteria
- Any increase in incident rate above baseline +20% for 24h after migration activity.
- Any unresolved ledger invariant violation (held + disputed + released + refunded mismatch).
- Any provider outage recovery that requires non-operator-tuned workarounds.
Rollback to prior TS implementation:
- disable any split deployment feature flag,
- switch
PAYMENT_ENABLED_PROVIDERSback to legacy-only, - freeze new provider routing until incident review is complete,
- complete post-incident update in this ADR.
8. Ownership
- CTO: final stack decision + dual-stack approvals.
- Backend Lead (BL): contract and adapter enforcement.
- Security Lead (SL): webhook/security acceptance criteria.
- DevOps Lead (DL): deployment safety and rollback testing.