Architecture

4 microservices, PostgreSQL, ERC-3643 on Polygon, off-chain CLOB matching engine

platform-api

:8081Go / Fiber

Core business logic — authentication, KYC, business management, tokens, wallets, admin, compliance (PDPL)

Auth (JWT + HttpOnly cookies + 2FA TOTP)
User Management & RBAC (4 roles, 23 permissions)
KYC Review Pipeline (pending → in_review → approved/rejected)
Business Profiles & Data Rooms
Token Management (create, deploy, allocate)
Wallet & Fiat Operations (deposit, withdraw, balance)
Dividend Declaration & Distribution
Admin Operations (fees, tiers, subscriptions, invoices)
PDPL Compliance (consents, data requests, breaches, retention)
Notifications (user + broadcast)
Audit Logging (all sensitive actions)

trading-server

:8080Go / Fiber

Order matching (CLOB), settlement, real-time WebSocket feeds, circuit breakers, price history

Central Limit Order Book (CLOB)
Matching Engine (~760K orders/sec, ~215K trades/sec)
Order Types: Market, Limit, Stop
On-chain Settlement via blockchain-svc
WebSocket: Real-time orderbook + trade feed
Circuit Breakers (price + volume thresholds)
OHLC Price History (candle aggregation)
Admin: Force cancel, view all orders/trades
Stop Order Persistence (survives restart)
Trading Limits per user

blockchain-svc

:8082Go / Fiber

ERC-3643 smart contract operations — deploy, mint, transfer, identity registry, event indexing

ERC-3643 Token Deployment
Token Minting (treasury → platform)
Compliant Transfers (KYC-gated)
Identity Registry Management
Freeze/Unfreeze Addresses
Event Indexer (Transfer, Freeze, Deploy events)
Gas Tracking & Reporting
Settlement Execution (trade → on-chain transfer)

web

:3000Next.js 14 / TypeScript / Tailwind

4-portal frontend — Investor (teal), Issuer (indigo), Admin (amber), Staff (violet)

Role-based Portal Theming (CSS variables)
Investor: Portfolio, Trading, Wallet, History
Issuer: Token Management, Data Room, Dividends
Admin: Full platform management (20+ pages)
Staff: Scoped admin access by permissions
Real-time WebSocket Orderbook
Glassmorphism Design System
Responsive Sidebar Navigation

Technology Stack

Backend

Go 1.24

Fiber v2

GORM

JWT + bcrypt

AES-256-GCM

Frontend

Next.js 14

TypeScript

Tailwind CSS

Lucide Icons

Radix UI

Database

PostgreSQL 16

52 tables

JSONB columns

Deferrable constraints

Blockchain

Solidity ^0.8.20

ERC-3643 (T-REX)

Hardhat (local)

Polygon Amoy (testnet)

DevOps

alef.sh (unified CLI)

--amoy flag for testnet

Standalone Go builds

514 integration tests

Key Data Flows

Primary Offering (Token Allocation)

1

Investor subscribes to token offering

2

Admin confirms payment received

3

Fiat balance deducted (off-chain)

4

blockchain-svc: ERC-3643 transfer(treasury → investor)

5

Wallet balance updated (off-chain cache)

6

Wallet transaction recorded

Secondary Trading (Buy/Sell)

1

Investor places order via trading-server

2

Matching engine matches buy + sell orders

3

Trade created with pending settlement

4

Fiat balances adjusted (buyer -, seller +)

5

blockchain-svc: ERC-3643 transfer(seller → buyer)

6

Wallet balances synced, tx_hash stored

KYC → On-Chain Identity

1

User submits KYC application

2

Admin reviews and approves

3

kyc_status updated to 'approved'

4

blockchain-svc: Register address in Identity Registry

5

User can now hold and transfer tokens on-chain

System Topology

                           ┌─────────────────────┐
                           │     Web (Next.js)    │
                           │       :3000          │
                           └──────────┬───────────┘
                                      │  REST / WebSocket
                    ┌─────────────────┼─────────────────┐
                    │                 │                  │
             ┌──────▼──────┐   ┌──────▼──────┐   ┌──────▼──────┐
             │ platform-api│   │trading-server│   │blockchain-svc│
             │   :8081     │   │   :8080      │   │   :8082      │
             │             │   │              │   │              │
             │  Auth, KYC  │   │  CLOB Match  │   │  ERC-3643    │
             │  Business   │   │  Settlement  │   │  Deploy/Mint │
             │  Tokens     │   │  WebSocket   │   │  Transfer    │
             │  Wallet     │   │  Price OHLC  │   │  Identity    │
             │  Admin/PDPL │   │  Circuit Brk │   │  Indexer     │
             └──────┬──────┘   └──────┬───────┘   └──────┬───────┘
                    │                 │                   │
                    ▼                 ▼                   ▼
             ┌────────────────────────────┐       ┌──────────────┐
             │       PostgreSQL           │       │   Polygon    │
             │       52 tables            │       │   ERC-3643   │
             │       :5432                │       │  Amoy/Local  │
             └────────────────────────────┘       └──────────────┘

Dual-mode blockchain: local Hardhat for development, Polygon Amoy testnet for staging.

Trade Settlement Flow

  Investor places order         Matching Engine              Settlement
  ───────────────────         ─────────────────            ──────────────

  ┌──────────────┐     REST    ┌──────────────┐
  │  Buy / Sell  │────────────▶│  CLOB Order  │
  │  Order       │             │  Book        │
  └──────────────┘             └──────┬───────┘
                                      │ price-time match
                                      ▼
                               ┌──────────────┐
                               │    Trade     │
                               │   Created    │
                               │ (pending)    │
                               └──────┬───────┘
                                      │
                        ┌─────────────┼─────────────┐
                        ▼                           ▼
                 ┌──────────────┐          ┌──────────────┐
                 │ Fiat Transfer │          │  On-Chain    │
                 │ (off-chain)   │          │  Transfer    │
                 │ buyer→seller  │          │ ERC-3643     │
                 │ via DB update │          │ seller→buyer │
                 └──────┬───────┘          └──────┬───────┘
                        │                         │
                        └────────────┬────────────┘
                                     ▼
                              ┌──────────────┐
                              │   Trade      │
                              │  Settled     │
                              │  (tx_hash)   │
                              └──────────────┘

ERC-3643 Contract Architecture

  ┌──────────────────────────────────────────────────────────────┐
  │                    SecurityToken (ERC-3643)                  │
  │                                                              │
  │  mint()  transfer()  freeze()  batchMint()  balanceOf()     │
  │                                                              │
  │  ┌─────────────────────┐    ┌─────────────────────────────┐ │
  │  │  ERC-20 Interface   │    │  Compliance Module          │ │
  │  │  (standard methods) │    │  canTransfer() check        │ │
  │  └─────────────────────┘    └──────────────┬──────────────┘ │
  └─────────────────────────────────────────────┼────────────────┘
                                                │ queries
                                                ▼
                                 ┌──────────────────────────────┐
                                 │     Identity Registry         │
                                 │                               │
                                 │  registerIdentity(address)    │
                                 │  isVerified(address) → bool   │
                                 │  removeIdentity(address)      │
                                 │                               │
                                 │  Only KYC-approved addresses  │
                                 │  can hold / transfer tokens   │
                                 └──────────────────────────────┘

  Flow: transfer(from, to, amount)
    1. SecurityToken calls canTransfer()
    2. Compliance module queries Identity Registry
    3. Both from + to must be verified (KYC approved)
    4. If compliant → transfer executes
    5. If not → reverts with reason

Security & Compliance

Authentication

JWT in HttpOnly cookies

Refresh token rotation

TOTP 2FA (AES-256-GCM encrypted)

Rate-limited auth endpoints

Authorization

4 roles: investor, issuer, admin, staff

23 granular permissions (RBAC)

7 team_role presets

RequirePermission middleware

Security Headers

HSTS, X-Frame-Options

X-Content-Type-Options

Referrer-Policy

CORS restricted to localhost:3000

PDPL Compliance

Consent tracking (4 purposes)

Data subject requests (5 types)

Breach incident management (72hr SLA)

Automated retention & purge