MoMo›Me
Pay Mobile Money from anywhere. To the user it's "Pay Mobile Money"; underneath it's a
settlement network that takes crypto in (Lightning / on-chain BTC / USDT-TRON), runs FX
to XAF, and pays out to MTN / Orange / Airtel across the CEMAC franc zone via PawaPay.
This repo is a full-stack TypeScript implementation built from the original
design-tool prototypes (archived in docs/archive/prototypes/).
app/ Vite + React + TypeScript frontend (@momome/app) — the canonical UI
server/ Express + TypeScript settlement engine (@momome/server)
shared/ Domain types + constants shared by both (the API contract)
mobile/ Expo (React Native) app — isolated project, not a workspace member
BACKEND_DESIGN.md The settlement architecture this backend implements
Run it
pnpm install
pnpm dev # runs the API (:4000) and the app (:5173) together
Then open http://localhost:5173. The Vite dev server proxies /api → :4000.
Run them separately if you prefer: pnpm dev:server and pnpm dev:app.
Build for production: pnpm build. Typecheck everything: pnpm typecheck.
Routes
| Route | Surface |
|---|
/ | Marketing landing |
/send | The pay app — send flow, Activity, Help (EN/FR) |
/admin | Partner/admin console — overview, payments, customers, rails, settings |
/ops | Live operations dashboard (polls every 2s) |
/capital-intelligence/* | Capital Intelligence — executive overview, capital health, transactions, liquidity + stress tests, revenue, routes, forecasts, scenarios, capital requirements, fundraising, investor matching, efficiency, concentration, risk, recommendations (human approval workflow) |
/investors /investments/* | Investor OS — CRM, qualification, KYC (four-eyes), opportunities → proposals → term sheets → investments → funding (four-eyes), documents, communications |
/capital/* | Capital products — OWN / POWER / SCALE / STRATEGIC, one ledger each; allocations (propose → approve → execute) |
/reports /ai-copilot/* | Reports; AI Capital Copilot (structured engine, source + calculation trace, AI audit) |
/investor/* | Investor portal — an investor's own room (role Investor) |
/terms /privacy /contact | Legal & contact |
How it works end-to-end
The send flow is wired to the real settlement engine:
- Resolve the recipient name from the number (
/api/recipients/resolve).
- Quote —
/api/quotes prices the inbound crypto with a per-rail FX spread
(Lightning/USDT tight, on-chain wider for the confirmation-window exposure).
- Create payment —
/api/payments returns a real, scannable pay instruction
(BOLT11-shaped invoice / on-chain address / TRC20 address) rendered as an actual QR.
- Confirm —
/api/payments/:id/confirm drives the payment state machine
(AWAITING_INBOUND → INBOUND_CONFIRMED → FX_LOCKED → PAYOUT_REQUESTED → DELIVERED),
writing balanced double-entry ledger entries and paying out exactly once
(idempotent on the payment ref). The UI polls /api/payments/:id to render progress.
The Capital Intelligence module lives in app/src/capital/ (lazy chunk behind the
admin session gate) and server/src/core/capital/ (engine over the real
payments/ledger/float, Investor OS records persisted through the snapshot seam, copilot, reports).
Set VITE_CAPITAL_DATA_SOURCE=mock on the app to develop the UI against the isolated fixture
adapter — the shell paints a permanent MOCK banner; the default (api) is the live backend.
See server/src/core/ for the ledger, FX engine, and state machine,
and BACKEND_DESIGN.md for the architecture rationale.
What's real vs. simulated
The orchestration is real: the FX quote/spread/expiry logic, the double-entry ledger
(every transaction balances per currency or it throws), the payment state machine, and
the exactly-once idempotent payout contract.
The external integrations are adapters behind a clean seam, selected by
RAILS_MODE (default sandbox — zero credentials):
Going live: copy server/.env.example, set RAILS_MODE=live + the IBEX/TRON
credentials, and inbound confirmation switches from the user tap to signed provider
webhooks (POST /webhooks/ibex, POST /webhooks/tron) that drive the same state
machine. The FX lock, ledger, and exactly-once payout are untouched. Data is in-memory
(seeded on boot); the store is a repository seam ready for SQLite/Postgres.
Try the demo number
On /send, the prefilled number 6 70 12 34 56 resolves to a verified recipient.
Tap through to the Pay step, hit "I've sent the payment", and watch the state machine
deliver it. Numbers ending in 8/9 come back unverified (manual-name path); ending in
7 resolve as a returning recipient.
docs/archive/prototypes/ holds the original design prototypes,
archived as of the initial build. They are historical reference only — app/ is the canonical
UI, and app/src/styles/momome.css is the design system of record.
