Architecture & Integrations
Architecture & Integrations
Libertum is a distributed system: three end-user web applications, a set of containerised backend services, a smart-contract layer on several EVM chains and Cardano, and a group of third-party integrations. This page is a high-level overview; for integration details see the Developers section.
1. The high-level shape
┌─────────────────────────────────────────────────────────────────────┐
│ END-USER LAYER │
│ T-Suite app (Marketplace) Admin console Transfer Agent app │
│ React 18 / TypeScript / Vite │
└─────────────────────────┬─────────────────────────┬─────────────────┘
│ HTTPS + SSE │
┌─────────────────────────▼─────────────────────────▼─────────────────┐
│ SERVICE LAYER │
│ Marketplace API · Admin API · Transfer Agent API · Notification │
│ Event service · Dividend service · Cardano service │
│ Node.js / TypeScript — gRPC + Kafka │
└─────────────────────┬───────────────────────────────┬───────────────┘
│ │
┌─────────────▼──────────┐ ┌──────────▼──────────────┐
│ DATA LAYER │ │ INTEGRATION LAYER │
│ MongoDB · Redis · │ │ SumSub · Stripe · │
│ cloud blob storage │ │ Bridge.xyz · SendGrid ·│
│ │ │ Gmail · Anthropic · │
│ │ │ RPC providers │
└────────────────────────┘ └─────────────────────────┘
│
┌───────────────────▼──────────────────┐
│ BLOCKCHAIN LAYER │
│ EVM mainnets: Base, Ethereum, │
│ Polygon, Arbitrum (ERC-3643 …) │
│ Cardano mainnet — CIP-20 · CIP-113 │
│ Cardano preview — CIP-113 │
│ XRPL mainnet — IC · MPT (XLS-33) │
└──────────────────────────────────────┘2. Frontend applications
Three React 18 single-page apps built with TypeScript and Vite.
Marketplace (the T-Suite app)
The main app at app.libertum.io. It combines the persona tabs a user is entitled to: Investor, Issuer, Asset Management, Distribution Hub, Structuring, Funds and Stablecoin Studio.
Stack: React 18, TypeScript, Vite, Redux Toolkit, TanStack React Query, RainbowKit + wagmi + viem + ethers v6, Formik, React Bootstrap and Tailwind CSS, Recharts, Sentry.
Mode detection: the app inspects the hostname and switches between two modes:
- Core — Libertum’s own T-Suite app.
- Platform whitelabel — a tenant’s branded platform on its own custom domain. Each tenant marketplace shows its own offerings plus offerings hosted through the Ecosystem Directory.
The older single-offering shopfront mode is deprecated.
Admin
The Libertum SuperAdmin console: user and KYC/KYB review, offering approvals, sub-admin permissions, platform fees, country restrictions, plans and modules, withdrawal approvals and other platform controls.
Transfer Agent
A separate web app for transfer agents. It talks to the Transfer Agent API and interacts with the token contracts through ethers. Screens:
- Dashboard — summary cards, charts (for example asset valuation and top holders) and recent activity.
- Cap Table — holders and balances per offering.
- Wallet Whitelist — approve or reject investor wallets per offering, with the investor’s KYC proof available for review.
- User Details — the profile and verification details of an investor behind a whitelist request.
- Transfer Journal — the record of token transfers, including forced transfers.
- Transactions — transaction history.
- Settings — account settings, including password change.
3. Backend services
A set of Node.js / TypeScript services, each owning a domain:
| Service | Domain |
|---|---|
| Marketplace API | The main API: users, offerings, orders, subscriptions, agreements, Custodian Wallet, Distribution Hub, Structuring, Funds, Stablecoin Studio, redemptions, scheduled jobs and the real-time notification stream |
| Admin API | SuperAdmin operations: fees, country restrictions, approvals |
| Notification service | Email and real-time notifications |
| Event service | Blockchain event indexer: polls chains on a schedule and publishes events to Kafka |
| Dividend service | Dividend processing |
| Transfer Agent API | Cap-table queries, whitelist decisions and transfer-agent actions |
| Cardano service | CIP-20 and CIP-113 token operations, and Cardano custodian signing |
The marketplace API is served under the /marketplace/v1 base path. Authenticated routes sit under /auth/...; a few public routes sit under /public/... (for example, country restrictions). There is no public OpenAPI specification yet.
4. Data layer
- MongoDB — primary document store: users, offerings, orders, transfers, dividends, P2P, subscriptions, plans, modules, KYC records, custodian wallets, audit records.
- Redis — caches, short-lived tokens and distributed locks for scheduled jobs.
- Cloud blob storage — uploaded documents and images.
- Kafka — the asynchronous event bus between services (see section 7).
5. Auth & identity model
- Sign-in: email and password.
- Sessions: JWT bearer tokens backed by a server-side session per browser, with a sliding inactivity timeout (60 minutes by default); signing in on another domain or device does not end other sessions.
- Two-factor authentication: authenticator app (TOTP) with backup codes.
- Sensitive actions (for example Custodian Wallet withdrawals or signing an agreement) need an extra verification step, such as an email OTP.
Who uses what:
- Investors (individuals and institutions) and issuers use the T-Suite app; a user can hold several personas, and access to each persona tab follows the subscription.
- Libertum administrators use the Admin console; sub-admins see only what their permissions allow.
- Transfer agents use the Transfer Agent app.
KYC vs KYB. Both run through SumSub. KYC is for individuals; KYB is for entities.
6. Synchronous communication: gRPC
Services that need synchronous answers from each other use gRPC for internal service-to-service calls. gRPC connects the marketplace, admin, notification and transfer agent services — for example, user and KYC lookups, approval actions, and reading or marking in-app notifications.
7. Asynchronous communication: Kafka
Asynchronous events flow through Kafka topics, so producers and consumers stay loosely coupled.
| Topic group | Producer | Consumer | Examples |
|---|---|---|---|
| Notification topics | Marketplace API and other services | Notification service | In-app notifications, email dispatch triggers |
| Product-update topics | Event service, Admin API | Marketplace API | On-chain events (mints, transfers, escrow activity), approval decisions |
8. Scheduled jobs
Scheduled work runs with node-cron inside the marketplace API — about two dozen jobs. Each job takes a Redis-based lock so only one instance runs it at a time. Examples include dividend handling, expiring unpaid orders and P2P orders, opening Coming Soon listings at their launch time, redemption processing, hosting-request expiry, the platform notification digest, monthly AI-usage billing, subscription access expiry and the paper-trading engine.
Separately, the event service polls each supported chain on a schedule and publishes what it finds to Kafka.
9. Third-party integrations
| Service | Used for |
|---|---|
| SumSub | KYC and KYB identity verification |
| Stripe | Card payments, subscription billing, and Stripe Connect for issuer payouts |
| Bridge.xyz | T-Pay fiat on/off-ramp (limited availability) |
| SendGrid | Transactional email |
| Gmail (read-only OAuth) | Distribution Hub inbox connection |
| Anthropic Claude models | Libby AI and Structuring |
| Cloud blob storage | Document and image uploads |
| Commercial RPC providers | EVM chain access, with failover |
| Blockfrost | Cardano chain data |
| WalletConnect / RainbowKit | Connecting external wallets |
| Cloudflare | Custom domains for whitelabel tenants (Cloudflare for SaaS) |
| Sentry | Error tracking |
Payments can also be made by bank wire; in USDC or USDT through the Escrow contract on EVM chains; in RLUSD or USDC on the XRP Ledger (verified on-ledger — USDT is not accepted on XRPL, as there is no native Tether there); and from the investor’s custodian balance, with network fees sponsored for the investor and billed to the offering’s issuer.
10. Notifications & email templates
Email is sent by the notification service. Templates cover orders, wallet whitelist decisions, dividends, P2P orders, invitations and platform events. Brand colours and logo are configured per tenant for whitelabel.
Real-time notifications in the browser use a Server-Sent Events stream. To open the stream, the app first requests a short-lived, one-time stream ticket and connects with it, so the access token never appears in the stream URL.
11. Production posture
- Frontends are statically built single-page apps.
- Backend services run as containerised services.
- Admin endpoints are called server-to-server through an admin proxy and every request is signed (HMAC).
- RPC access uses commercial providers with failover.
- Observability via Sentry per service, application logs, and on-chain monitoring (the event service is itself a monitoring point).
12. Backend components
The marketplace API is organised into components. The main ones:
| Component | What it does |
|---|---|
| structuring | Structuring projects, intake, AI research, document generation, guest legal review and draft-offering creation |
| aiUsage | Metering of AI usage per owner and product, included credit and overage billing |
| sseNotifications | The Server-Sent Events notification stream and its one-time stream tickets |
| custodianWallet | Platform-managed wallets: deposits, saved withdrawal addresses, withdrawals and their controls |
| gasTreasury | Network-fee estimates, prepaid gas balances and gas charges for custodian transactions |
| bridge | T-Pay fiat on/off-ramp through Bridge.xyz |
| governance | Governance proposals and investor voting |
| p2p | The P2P secondary market: listings, orders and their fees |
| hosting | Cross-marketplace hosting requests and the hosting inbox |
| investorStatements | The investor statements summary and transaction feed |
| agreements | Agreement templates, e-signature with OTP and the per-agreement audit trail |
| redemption | Redemption windows, requests, payout accounts and settlement |
| distributionHub | Distribution Hub CRM, investor discovery, matching, campaigns and Libby AI |
| countryRestrictions | The platform-wide country grey-list and black-list |
| feeConfig | Platform fee defaults and per-issuer and per-offering overrides |
XRPL components
Status: Live — XRPL is live on mainnet and selectable in the Tokenization Wizard (XRPL Issued Currency and XLS-33 MPT).
Three further components support XRPL offerings:
| Component | What it does |
|---|---|
| xrplPlatform | Libertum’s XRPL platform accounts |
| xrplCredentialIssuer | On-ledger credential issuance (XRPL Credentials) and trust-line authorisation |
| xrplReserve | XRPL account reserve management |