The regulated-finance BFF.
A TypeScript Express 5 service that owns provider secrets, identity bridging, money movement, invoicing, statements and reconciliation. Clients stay thin; the backend stays in charge.
At a glance
Inside the BFF
Express boot → middleware → routers → controllers → providers + Postgres.
HTTP surface
Every namespace mounted in src/app.ts, with endpoint counts from route extraction.
| Base path | Purpose | Endpoints |
|---|---|---|
| /api/users | Signup, login, Cognito flows, profile, notifications, SumSub token / status, account deletion | 27 |
| /api/if | Integrated Finance clients, accounts, cards, beneficiaries, transfers, transactions, graphs, open banking, webhooks | 41 |
| /api/sumsub | SumSub webhook + SSE status stream | 2 |
| /api/phyllo | Phyllo users, SDK tokens, work platforms, accounts, profiles, social / income data, webhooks | 36 |
| /api/monite/common | Counterparts, addresses, bank accounts, contacts, VAT IDs | 27 |
| /api/monite/entity | Entities, roles, entity users, bank accounts, VAT IDs, settings | 19 |
| /api/monite/payables | Payables and credit notes | 6 |
| /api/monite/receivables | Units, products, VAT rates, payment terms, invoices, recurrences | 20 |
| /api/statements | Account, confirmation, balance, fee and email statement generation | 5 |
| /api/support | Intercom tickets, tickets metadata, tags, replies | 18 |
| /api/support/kb | Intercom knowledge base facade | 5 |
| /api-docs | Swagger UI · OpenAPI | — |
| /webhook | Generic placeholder webhook logger | — |
Tech stack
Every layer of the runtime, with the file or surface that proves it.
Core flows
The chains the backend actually orchestrates day to day.
Signup, verification, login
Email + SMS OTP staged onboarding, Cognito user creation, admin-confirm bypass for dev, refresh-token rotation persisted in PostgreSQL.
KYC / KYB → financial provisioning
SumSub access token issuance, webhook upserts SumSubStatus, then Integrated Finance external user + bank account, then Monite entity / role / entity user.
Accounts, cards, transfers
Wraps Integrated Finance: client + account + card lifecycle, beneficiary requirements, transfer creation, card transaction authentication approval/reject, IF webhook reconciliation.
Statements & documents
Handlebars HTML → Puppeteer PDF → S3 → presigned URL. Account, confirmation, balance summary, statement of fees and password-protected statement by email.
Phyllo creator data
Create Phyllo user linked to cognitoId, SDK tokens, work platforms, profiles, audience, content, income transactions, payouts and balances. Webhook payloads stored in PhylloData.
Monite invoicing
Entities, roles, entity users, counterparts, products, VAT rates, payment terms, payables, receivables, recurring invoices and PDF generation.
Support & knowledge base
Intercom-backed: ticket lifecycle, replies, tagging, KB collections / sections / articles / search — all brokered server-side.
Notifications
OneSignal push and SMTP email with persisted Notification rows, send status and read/unread state per user.
Signup → login sequence
KYC approved → provider provisioning
Webhook fan-out
Provider events become Lobster-owned state — and an audit trail.
Environment contract
The names of every secret the runtime expects. Values stay in the secret manager.
- NODE_ENV
- PORT
- DATABASE_URL
- FRONTEND_URL
- APP_PATH
- IF_API_BASE_URL
- IF_CLIENT_ID
- IF_INSTANCE_ID
- IF_OIDC_ISSUER
- IF_TOKEN_ENDPOINT
- IF_PRIVATE_KEY_PATH
- SUMSUB_BASE_URL
- SUMSUB_APP_TOKEN
- SUMSUB_SECRET_KEY
- SUMSUB_WEBHOOK_SECRET
- PHYLLO_BASE_URL
- PHYLLO_CLIENT_ID
- PHYLLO_CLIENT_SECRET
- AWS_REGION
- COGNITO_USER_POOL_ID
- COGNITO_CLIENT_ID
- COGNITO_CLIENT_SECRET
- AWS_S3_BUCKET
- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
- SMTP_HOST
- SMTP_PORT
- SMTP_SECURE
- SMTP_USER
- SMTP_PASS
- MONITE_CLIENT_ID
- MONITE_SECRET
- ONESIGNAL_APP_ID
- ONESIGNAL_REST_API_KEY
- SMS_BYPASS_ENABLED
- HARDCODED_SMS_OTP
- EMAIL_BYPASS_ENABLED
- HARDCODED_EMAIL_OTP