118 lines
4.1 KiB
Markdown
118 lines
4.1 KiB
Markdown
---
|
|
title: Backend Core Stack Decision Record - 2026-05-24
|
|
tags: [adr, architecture, backend]
|
|
created: 2026-05-24
|
|
status: approved
|
|
reviewers: [CTO, backend, security]
|
|
---
|
|
|
|
# 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:
|
|
|
|
- `Payment` orchestration 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
|
|
|
|
1. **Phase A (this quarter):** lock down high-risk flows in TypeScript (ledger, adapter, webhook, auth/session, runbooks).
|
|
2. **Phase B (next two quarters):** extract core services behind stable interfaces and add adapter-level contract tests.
|
|
3. **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_PROVIDERS` back 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.
|
|
|
|
## Related
|
|
|
|
- [[Backend Stack Security and Refactor Assessment - 2026-05-24]]
|
|
- [[Secure Build and Supply-Chain Policy]]
|
|
- [[Backend Funds Migration and Operational Runbooks]]
|