Phoenix Project Status
Phoenix is Simpaisa's full API platform rewrite - Go microservices replacing legacy Java/Spring Boot. This page tracks programme status, recent delivery, and outstanding work.
Programme Overview
| Attribute |
Detail |
| Programme |
Phoenix - API Platform Rewrite |
| Owner |
Daniel O'Reilly, CDO |
| Tech Stack |
Go 1.24, Echo v4.15, SurrealDB v2.x, KrakenD v2.x, NSQ, OAuth2 + JWT (RS256), OpenTelemetry - Grafana / Tempo / Loki, Cloudflare Pages |
| Last Updated |
10 April 2026 |
| Overall Status |
On Track - Active Development |
Delivered: 10 April 2026
Seven capability items shipped today across security hardening, developer tooling, API surface expansion, and a new platform service.
| # |
Capability |
Area |
What Was Delivered |
Status |
| 1 |
CORS Hardening |
Security |
Removed wildcard CORS middleware from card, pay-in, pay-out, and remittance services. All four are internal-only behind the KrakenD gateway - no public CORS required. |
Done |
| 2 |
KrakenD Dev Config |
Developer Experience |
Added krakend.dev.json and docker-compose.dev.yml for local development. Engineers can now run the full gateway stack on localhost (ports 4321 and 3000) without touching staging. |
Done |
| 3 |
gRPC Code Generation |
Platform Quality |
Replaced 170 lines of hand-written gRPC stubs in the merchant service with protoc-generated code. A go:generate directive now ensures stubs stay in sync with .proto definitions automatically. |
Done |
| 4 |
Pay-Out State Machine |
Disbursements |
Added three missing states (in_review, on_hold, stuck) to match legacy system granularity. Full transition table, OpenAPI specs, and SurrealDB schema migrations updated. |
Done |
| 5 |
Reconciliation Service |
New Platform Service |
New services/reconciliation Go microservice (port 8447). Calculates customer and merchant fee, tax, and commission breakdowns per transaction. Full OTel tracing, idempotent design, SCHEMAFULL SurrealDB table. |
Done |
| 6 |
Settlement Fee Breakdown |
Disbursements |
Pay-out service now calls reconciliation and returns an inline settlement field on disbursement responses. Non-blocking - if reconciliation is unavailable the field is gracefully omitted. |
Done |
| 7 |
Pay-In Direct-Charge Endpoint |
Collections / Recurring Billing |
New POST /api/v1/payin/payments/charge endpoint. Accepts a stored paymentToken for no-OTP recurring charges (subscription billing). Cross-merchant token isolation enforced. OpenAPI specs updated. |
Done |
Pay-Out State Machine - Full Transition Reference
The disbursement state machine now has full parity with the legacy Java platform.
| State |
Transitions To |
Trigger / Reason |
New in This Release |
initiated |
processing, on_hold |
Payout request accepted; routed to partner or held for balance check |
- |
processing |
disbursed, reversed, in_review, stuck |
Partner processing; outcome determined by partner callback or timeout |
- |
disbursed |
(terminal) |
Funds successfully delivered to beneficiary |
- |
reversed |
(terminal) |
Partner rejected or returned funds; payout cancelled |
- |
in_review |
processing, reversed |
AML hold - transaction flagged for compliance review before disbursement continues |
New |
on_hold |
processing, reversed |
Insufficient balance or manual operations hold; awaiting resolution |
New |
stuck |
processing, reversed |
Partner timeout - no callback received within SLA; requires ops intervention or retry |
New |
Open Work Items
| Issue |
Priority |
Title |
Status |
Notes |
| phoenix-jo2 |
P2 |
Favicon - white background, blue logo across all sites |
Open |
- |
| phoenix-x58 |
P2 |
Design System (@simpaisa/ui) |
Blocked |
Deferred until portal MVP ships |
| phoenix-1ef |
P3 |
Deploy sandbox to controlplane.com |
Open |
- |
| phoenix-ggx |
P3 |
Nomad job files per service |
Open |
- |
Architecture Summary
| Layer |
Technology |
Role |
| Edge |
Cloudflare |
DDoS, WAF, CDN, Pages (portal) |
| Gateway |
KrakenD v2.x |
API gateway, rate limiting, auth enforcement, legacy compatibility via phoenix-proxy |
| Services |
Go 1.24 + Echo v4.15 |
Card, Pay-In, Pay-Out, Remittance, Merchant (gRPC), Reconciliation |
| Database |
SurrealDB v2.x |
SCHEMAFULL tables, RocksDB persistence + in-memory cache mode |
| Messaging |
NSQ v1.3 |
Async event distribution between services |
| Auth |
OAuth 2.0 + JWT (RS256) + mTLS |
All API auth; secrets via HashiCorp Vault |
| Observability |
OpenTelemetry + Grafana stack |
Alloy (collector), Tempo (traces), Loki (logs), Prometheus (metrics), Grafana dashboards |
| Compute |
controlplane.com + Nomad |
Service orchestration (Nomad job files in progress) |