Core Platform Services
This section describes each service in the Gravv platform, its responsibilities, and its principal interfaces. All services communicate over gRPC internally; the API gateway is the only HTTP-facing service for clients.
API Gateway
The API gateway (Go / Gin) is the single HTTP entry point for the entire platform. It terminates all client traffic — dashboard JWT users, API-key merchants, and third-party provider webhooks — applies authentication, rate limiting, and idempotency, then fans out to approximately sixteen downstream gRPC microservices.
Authentication surfaces. JWT bearer (dashboard), API keys (
grvSec_live_*/grvSec_sandbox_*), super-admin tokens (operations), and dedicated hosted-payment-page authentication.Product surface. Identity and team management, API keys, accounts and account applications, sweep rules, cards, customers, external accounts (payees), settlement instructions, collections (onramp, card collections, hosted payment links), KYC/KYB, transfers, transactions, wallets, stablecoin payment links, merchant webhooks, FX and OTC orders, billing (fees, invoices, subscriptions), and savings (OpenTrade).
Webhook ingestion. Dedicated live and sandbox endpoints for every integrated provider; events are forwarded to Kafka for downstream processing.
Resilience. Per-service circuit-breaker profiles with tight thresholds for mutating finance services; retries deliberately disabled on mixed read/write services; Redis-backed idempotency middleware on POST requests.
Statelessness. The gateway holds no database — only Redis for idempotency, rate limiting, and caching.
Identity Service (Auth)
The Identity service manages authentication and tenant administration: signup/login via Stytch passwordless magic links, JWT issuance (HS256), API-key lifecycle (create, activate, deactivate, revoke, audit logs), teammates and roles, IP whitelisting, passcodes, webhook configuration, and business/tenant records. A background provisioning worker creates customer and account records in sibling services when new tenants onboard, and a Kafka consumer processes KYB review events. Sensitive columns are AES-encrypted at rest with a dedicated sensitive-data key, and a live-access gate controls production access per tenant.
Customers Service
The Customers service is the system of record for per-tenant end-customer profiles (name, date of birth, address, country, blacklist flag). It exposes customer CRUD and internal service-to-service RPCs, emits customer lifecycle events to the outbound webhook topic, and traces operations to the Audit service. Tenant isolation is enforced through mandatory tenant metadata on every call.
Internal Accounts Service
The Internal Accounts service manages tenant and customer financial accounts. It creates Web3 wallets across chains (Stellar, Polygon, Ethereum, Solana), attaches fiat virtual accounts through banking providers (Bridge, HiFi, Noah, Duplo, Austin Capital, Yolat, Lead Bank), and orchestrates account provisioning workflows and account applications (including terms-of-service acceptance). It also operates the deposit pipeline (Kafka workers with reconciliation) and the automated sweep system — tenant-defined rules that move inbound funds onward automatically, with sweep executions and reconciliation.
Transfer Service
The Transfer service (Rust) is the money-movement orchestrator. It owns the transfer workflow state machine: initiation, fee and exchange-rate computation, provider routing per corridor, the crypto settlement leg (coordinated with the Web3 service over Kafka), inflow processing, transfer limits, and dual-authorization approvals for transfers. It integrates directly with payout providers (Anchor, Attijariwafa, Balad, Bridge, Dlocal, Duplo, Erebor, Fincra, I&M Bank, Sokin, Thunes, Yellowcard, Circle, HiFi, and a virtual-IBAN provider) and consumes provider webhook events for settlement confirmation. Operational alerts (e.g., manual-processing escalation) are raised to Slack.
Transactions Service
The Transactions service (Rust) is the system of record for customer-visible
transactions. It provides transaction CRUD, summaries, volume aggregation, and
CSV export, using an integer minor-units money model (amount + precision).
Statuses are kept in sync exclusively by consuming
transactions.update.status events emitted by the Transfer and Web3
services, preserving a single authoritative record.
Payees Service
The Payees service (Rust) manages payment destinations (beneficiaries). It validates and verifies account details against third-party providers, creates provider-side external accounts, and determines which provider a payout should route through (per-payee provider routing across bank accounts, mobile money, SWIFT, SEPA, and ACH/wire rails). It also manages payee institutions (bank/institution reference data) and settlement standing instructions.
FX Service
The FX service manages currency rates, quotes, and trade execution. It sources rates from banking/FX providers (Standard Bank, ABSA, NMBZ, Quidax) behind a provider-factory pattern, applies tenant-level markups and bonuses, refreshes rates on a scheduler, and enforces slippage bounds at execution. Quotes are short-lived (configurable TTL) and locked at execution time. The service also operates the OTC desk: order creation, cancellation, statistics, and a dual-authorization approval workflow with per-chain master wallets.
Billing Service
The Billing service centralizes per-tenant fee configuration and fee charging for all platform products (cards, transfers, FX, onramp, KYC). Charging follows a state machine (PENDING → CHARGING → CHARGED / FAILED / PERMANENT_FAIL → REFUNDED) with idempotency keys and bounded retries; the actual balance deduction is delegated to the Web3 service. It also manages subscription plans and lifecycle, invoice generation and payment (including PDF export), fee reporting, and full audit-log tables for fees, invoices, and subscriptions.
Onramp Service
The Onramp service converts fiat to crypto. It handles deposit requests, payment intents, card charging (including tokenized card-on-file, CVV association, and 3-D Secure completion) via Coinflow, local-currency collections via Yellow Card and other providers, provider webhooks, and settlement into Web3 wallets. Asynchronous workflows run on a Redis-backed task queue with idempotent task IDs, and multi-layer reconciliation (routine, full, batch, deep) detects stuck or critical transactions. Card-on-file velocity limits and payment-link secrets protect the collection surface.
Web3 Service
The Web3 service (Rust) provides blockchain custody and crypto settlement, built on the Dfns wallet-as-a-service platform. It creates and manages MPC wallets across eight networks (Ethereum, Polygon, Solana, Stellar, Avalanche, Sui, Tron, Base), executes on-chain transfers with gas fee sponsorship, tracks balances via direct chain RPC, and hosts the Circle integration (USDC wire on/off-ramp, cross-currency exchange, payouts), stablecoin payment links, OpenTrade savings, and an internal workflow state machine. Every mutating custody call is user-action signed with an ECDSA P-256 key. A Redis-backed job queue handles asynchronous wallet provisioning with retries.
Risk Service (KYC / KYB / Monitoring)
The Risk service operates identity verification through Sumsub: KYC initiation
(hosted and server-to-server), KYB, document upload, applicant share tokens,
and enrichment of verified document data (encrypted at rest). It consumes
Sumsub review webhooks to update verification status, performs Kafka-driven
transaction monitoring (transactions.monitoring.initiate →
passed / failed), and orchestrates feature eligibility and
activation across downstream services (accounts, cards) based on
verification state.
Integrations Service
The Integrations service (Go) is a stateless gRPC facade over external
payment and fiat providers. Other services call a single IntegrationService
interface; the service routes each call through a provider-pattern handler to
the correct HTTP client, normalizes the response, and emits per-provider Kafka
events (integration.<provider>.request / .response / .error). It
centralizes provider credentials and request signing for fourteen providers
(Yellow Card, Dlocal, Balad, Fincra, Beam, Coinflow, Flocash, Sokin, HiFi,
Passpoint, Duplo, Yolat, Quidax, Noah) — approximately 170 RPCs in total.
Webhooks Service
The Webhooks service is the outbound webhook delivery system. It ingests
events over gRPC or Kafka, persists them, and delivers HMAC-SHA256-signed
payloads (X-Signature header, per-tenant secret fetched from the Identity
service) to tenant-configured endpoints via a polling worker with exponential
backoff and bounded retries. It provides webhook history, call detail, manual
retry, and ingestion audit queries, and deduplicates deliveries on
idempotency keys via Redis.
Audit Service
The Audit service is the platform-wide audit and compliance sink. It consumes
audit events and response logs from Kafka (audit.events.log,
response.log.created), persists them to PostgreSQL, and provides
session-based request logging (route, method, IP, user agent, device ID,
headers, parameters) stored in MongoDB, plus admin query and statistics RPCs.
All money-movement services emit fire-and-forget traces to it.
Web Applications
The web layer is an Angular / Nx monorepo with three applications:
Gravv dashboard — the tenant-facing application: accounts, customers, transactions, team, recipients, wallets, cards, billing, invoices, subscriptions, OTC desk, stablecoin payment links, webhook configuration, and profile management. Authentication via Stytch magic links with KYB onboarding.
Admin console — the internal operations application: businesses, customers, transactions, cards, and accounts oversight.
Stables — the public hosted stablecoin payment-link page.
A shared UI kit (gravv-tailwind) and branding library provide consistent
components across applications.