Architecture & Integrations

Libertum is a distributed system: three end-user web applications, a constellation of backend services, a smart-contract layer on Base Mainnet plus Cardano Mainnet and Preview, and a cluster of third-party integrations.

1. The high-level shape

┌─────────────────────────────────────────────────────────────────────┐ │                            END-USER LAYER                           │ │  Investor / Issuer / AM    Admin Portal     Transfer Agent Portal   │ │              React 18 / TypeScript / Vite — Cloudflare Pages        │ └─────────────────────────┬─────────────────────────┬─────────────────┘
                          │ HTTPS / WSS             │
┌─────────────────────────▼─────────────────────────▼─────────────────┐ │                           SERVICE LAYER                             │ │       Marketplace · Admin · Transfer Agent · Notification           │ │       Event indexer · Dividend · Bonding/DEX · Cardano              │ │              Node.js / Express / TypeScript — gRPC + Kafka          │ └─────────────────────┬───────────────────────────────┬───────────────┘
                      │                               │
        ┌─────────────▼──────────┐         ┌──────────▼──────────────┐
        │      DATA LAYER        │         │     INTEGRATION LAYER   │
        │  MongoDB · Redis ·     │         │  SumSub · Stripe ·      │
        │  PostgreSQL · Kafka    │         │  DocuSign · SendGrid ·  │
        │                        │         │  Twilio · Transak ·     │
        │                        │         │  Bridge · Blockfrost    │
        └────────────────────────┘         └─────────────────────────┘
                                                    │
                                ┌───────────────────▼──────────────────┐
                                │           BLOCKCHAIN LAYER           │
                                │  Base Mainnet (8453) ERC-3643 stack  │
                                │  Cardano Mainnet — CIP-20 native     │
                                │  Cardano Preview — CIP-113 + CIP-20  │
                                └──────────────────────────────────────┘

2. Frontend applications

Three React 18 single-page apps, all on Cloudflare Pages.

Marketplace

Investor + Issuer + Asset Management UI. The largest and most feature-rich SPA — combines all three primary platform experiences and routes by user role.

Stack: React 18, TypeScript, Vite, Redux Toolkit + redux-persist, TanStack React Query, RainbowKit + wagmi + viem + ethers v6, Formik + Yup/Zod, React Bootstrap + SCSS, Recharts, Sentry.

Mode detection: the app inspects the request hostname and switches between three modes:

• Core — Libertum’s own marketplace at libertum.io / app.libertum.io.
• Platform whitelabel — full marketplace at custom domain / non-reserved subdomain.
• Shopfront — single-offering branded page.

Admin

Libertum platform administration. Dashboard, user management, KYC review queue, offering approvals, sub-admin RBAC, fee config, transaction history, transfer-agent management, gas treasury, multi-chain ops.

Transfer Agent

Cap table, wallet whitelist approval, force transfer journal, transaction history. Heavy direct contract interaction via ethers.

3. Backend services

A set of cleanly-separated Node.js / Express / TypeScript services. Each owns a domain:

Service	Domain
Marketplace	Users, offerings, orders, payments, KYC mediation, P2P, NFT, subscriptions, whitelabel, custodian wallets
Admin	Admin operations, sub-admin RBAC, fee config, plan/module sync, gas treasury
Transfer Agent	Cap-table queries, force transfer, freeze/unfreeze, wallet whitelist
Notification	Email (SendGrid) + SMS (Twilio) + WebSocket in-app push
Event Indexer	Listens for on-chain Token Transfer, Mint, Burn, Pause, Identity Registry updates, Escrow deposits, Marketplace orders, Bonding buys/sells
Dividend	Dividend snapshot + distribution
Bonding / DEX	Bonding curve operations, staking rewards
Cardano (×2 instances)	CIP-20 + CIP-113 operations on Cardano. One instance per network (mainnet, preview).

4. Data layer

• MongoDB — primary document store. Owns users, offerings, orders, transfers, dividends, P2P, NFT collections, subscriptions, plans, modules, KYC records, custodian wallets, audit log.
• Redis — session store, distributed locks, caches.
• PostgreSQL — backing store for the Cardano indexer.
• Kafka — async event bus.

5. Auth & identity model

JWT-based with refresh-token rotation. 2FA gates sensitive operations.

Token lifecycle:

1. User logs in (email + password); marketplace validates.
2. OTP issued (email or SMS). User submits OTP within 5 minutes.
3. If 2FA is enabled, TOTP / email-OTP / SMS-OTP challenge.
4. JWT issued (1-hour expiry). Refresh token issued (7-day expiry).
5. Frontend stores both. Sends JWT on every request.
6. On expiry, the frontend uses the refresh token to obtain a fresh JWT.
7. Idle timeout: 30 minutes (marketplace), 60 minutes (admin).

Roles:

• Investor — Marketplace investor surfaces
• Institution — Marketplace investor surfaces (institutional investor variant)
• Issuer — Marketplace issuer surfaces (in addition to investor)
• Admin — Admin Portal full access
• SubAdmin — Admin Portal subset filtered by RBAC permissions
• TransferAgent — Transfer Agent Portal

KYC vs KYB. Both run via SumSub. Status: NOT_STARTED → IN_PROGRESS → PENDING → APPROVED / REJECTED / RESUBMIT. KYC is for individuals; KYB is for entities.

6. Synchronous communication: gRPC

Services that need synchronous answers from each other use gRPC. Examples:

• Marketplace ↔ Admin: getUser, approveKyc, approveWhitelist, approveIssuer, rejectOffering.
• Marketplace ↔ Notification: ListNotifications, MarkSeen, MarkAllSeen.
• Marketplace ↔ Bonding: GetStakingTransactions, GetUserStakingSummary.

7. Asynchronous communication: Kafka

Async events flow through Kafka topics. Producers and consumers loosely coupled.

Topic	Producer	Consumer	Examples
Cron-to-user	Event indexer, dividend service	Marketplace	OrderCreated, TokensMinted, DividendDistributed, NAVUpdated
Admin-to-user	Admin	Marketplace	KYC approved/rejected, Offering approved/rejected
Realtime notifications	Marketplace	Notification	In-app notifications
Realtime email	Marketplace	Notification	Email dispatch triggers
Realtime socket	Marketplace	Notification	WebSocket push events

8. Scheduled jobs

Job	Frequency	Service
Dividend snapshot + push	Frequent (sub-minute)	Marketplace / dividend service
P2P order expiration check	Every 2 minutes (orders past their 20-min payment window)	Marketplace
Monthly staking rewards	Monthly	Bonding / DEX

9. Third-party integrations

Service	Used for
SumSub	KYC + KYB identity verification
Stripe	Card payments + Connect for issuer payouts + subscription billing
DocuSign	E-signatures on legal documents
Transak	Fiat on/off-ramp
Bridge	Stablecoin / fiat conversion
SendGrid	Transactional email
Twilio	SMS OTP
Azure Blob Storage	Document and image upload
Blockfrost	Cardano RPC + indexing
Sentry	Error tracking
WalletConnect / Thirdweb	Wallet UX

10. Notifications & email templates

Email is sent via SendGrid; SMS via Twilio; in-app via WebSocket. Email templates exist for: order created/minted/cancelled/rejected, wallet whitelist sent/approved/rejected, dividend distributed, P2P order created/payment confirmed/tokens released/cancelled/expired, investor invite. Brand colours and logo are configured per tenant for whitelabel.

11. Production posture

• Frontends are statically built and served via Cloudflare’s global CDN.
• Backends are containerised; horizontal scale where warranted.
• All external secrets live in a managed secret store, not in environment files.
• Observability via Sentry per service, application logs, on-chain monitoring (the event indexer is itself a monitoring point), and vendor dashboards.