Enterprise Forex Brokerage CRM built on Convex real-time infrastructure.
The complete back-office and trader self-service platform for NAMH Global Ltd. Manages the entire broker lifecycle — from trader onboarding and KYC verification through MT5 trading account management, treasury operations with double-entry bookkeeping, IB partner commissions, sales pipeline, support tickets, risk monitoring, and real-time analytics.
graph TB
subgraph "Client Layer"
ADMIN["Admin Panel<br/><i>apps/admin</i><br/>Next.js 15 + React 19"]
PORTAL["Client Portal<br/><i>apps/portal</i><br/>Next.js 15 + React 19"]
end
subgraph "Shared Packages"
UI["packages/ui<br/><i>Shared components</i><br/>Charts, TradingView"]
TYPES["packages/types<br/><i>TypeScript types</i><br/>Permissions, enums"]
end
subgraph "Convex Backend"
direction TB
AUTH["Auth<br/><i>@convex-dev/auth</i>"]
RBAC["RBAC Layer<br/><i>withPermission()</i><br/>6 roles, 100+ perms"]
subgraph "Domain Modules"
USERS["users/"]
KYC["kyc/"]
TRADING["trading/"]
MT5["mt5/"]
TREASURY["treasury/"]
IB["ib/"]
SALES["sales/"]
SUPPORT["support/"]
RISK["risk/"]
ORG["org/"]
REPORTS["reports/"]
SEARCH["search/"]
NOTIF["notifications/"]
end
CRON["Cron Jobs<br/><i>5-min MT5 sync</i><br/><i>Commission calc</i>"]
AUDIT["Audit Log<br/><i>Every mutation tracked</i>"]
end
subgraph "External"
MT5SRV["MT5 Trade Server<br/><i>mt5api.namhglobal.com</i>"]
TV["TradingView<br/><i>lightweight-charts</i>"]
STORAGE["Convex File Storage<br/><i>KYC docs, proofs</i>"]
end
ADMIN --> AUTH
PORTAL --> AUTH
ADMIN --> UI
PORTAL --> UI
ADMIN --> TYPES
PORTAL --> TYPES
AUTH --> RBAC
RBAC --> USERS & KYC & TRADING & TREASURY & IB & SALES & SUPPORT & RISK & ORG & REPORTS
MT5 -- "REST/Bearer" --> MT5SRV
TRADING --> MT5
CRON --> MT5
ADMIN --> TV
PORTAL --> TV
KYC --> STORAGE
style ADMIN fill:#0f3460,stroke:#53a8b6,color:#fff
style PORTAL fill:#0f3460,stroke:#53a8b6,color:#fff
style MT5SRV fill:#1a1a2e,stroke:#e94560,color:#fff
style RBAC fill:#533483,stroke:#e94560,color:#fff
style CRON fill:#16213e,stroke:#d3ae37,color:#fff
style AUDIT fill:#16213e,stroke:#d3ae37,color:#fff
sequenceDiagram
participant Trader as Trader (Portal)
participant Admin as Admin Panel
participant Convex as Convex Backend
participant MT5 as MT5 Server
participant Cron as 5-min Cron
Note over Trader,MT5: Deposit → Trading Flow
Trader->>Convex: Submit deposit request
Convex->>Convex: Create pending transaction
Admin->>Convex: Approve deposit
Convex->>Convex: Credit wallet (atomic double-entry)
Admin->>Convex: Transfer wallet → trading account
Convex->>MT5: POST /user/deposit (via action)
MT5-->>Convex: Deal ticket returned
Convex->>Convex: Reconcile balance
Note over Cron,MT5: Automated Sync
Cron->>MT5: GET /account/{login} (50 accounts/batch)
MT5-->>Cron: Balance, equity, margin
Cron->>Convex: Upsert account data
Cron->>MT5: GET /positions/{login}
MT5-->>Cron: Open positions
Cron->>Convex: Upsert positions
Cron->>Convex: Run risk detection (scalp/hedge/HFT)
Note over Trader,Admin: Real-time Updates
Convex-->>Admin: Reactive subscription (auto-update)
Convex-->>Trader: Reactive subscription (auto-update)
| Module | Features |
|---|---|
| Dashboard | 6 KPI cards, date range filtering, trend charts, CSV/Excel export |
| Client Management | 360-degree profiles, advanced search, bulk operations, tagging |
| KYC Verification | 2-step document review, inline viewer, approve/reject/force-verify, corporate KYC |
| Trading Accounts | MT5 account CRUD, Live/Demo tabs, 3-step creation wizard, balance operations |
| MT5 Management | Groups and symbols (view-only sync), sync status indicators |
| Positions | Global positions view, floating P&L with color coding, auto-refresh |
| Treasury | Deposit/withdrawal approval workflow, dual-approval for high amounts, double-entry ledger |
| Wallets | User wallet viewer, main + IB wallets, balance history |
| Transfers | Wallet ↔ trading account, wallet ↔ wallet, MT5 balance sync |
| Payment Methods | CRUD with fee configuration (percent + fixed), min/max limits |
| Vouchers | Code generation, bulk creation, redemption tracking, CSV export |
| IB Partners | Application workflow, 5-level hierarchy tree, commission reports |
| Sales Pipeline | Kanban drag-and-drop, lead scoring (0-100), tasks, one-click conversion |
| Support | Ticket system with SLA tracking, conversation threads, quick reply templates |
| Risk Hub | Real-time alerts (scalp, hedge, HFT, unverified), dismiss workflow |
| TradingView Charts | Candlestick charts, 7 timeframes, symbol selector, NAMH dark theme |
| Reports | Module-specific reports, date range filtering, CSV/Excel export |
| Organization | Staff CRUD, departments, branches, role/permission matrix editor |
| Employee Onboarding | 4-step wizard (personal → department → role → confirm) |
| Settings | Roles/permissions, audit log viewer, tag management |
| Page | Features |
|---|---|
| Dashboard | Account cards with balance/equity/P&L, quick actions, recent transactions |
| Accounts | Trading account list, new account request |
| Deposit | Payment method selector, amount input, proof upload, fee preview |
| Withdraw | Amount input, anti-fraud validation display, method selection |
| Transfer | Bidirectional wallet ↔ trading account transfer |
| Transactions | Full history with type/status/date filters |
| KYC | Step-based document upload with progress indicator |
| Profile | Personal info editing, password change |
| Support | Create tickets, view conversations, reply to staff |
| IB Partner | Commission stats, sub-partner tree, referral link (conditional) |
| Charts | TradingView with symbol selector and timeframes |
| Capability | Implementation |
|---|---|
| Real-time sync | Convex reactive subscriptions — zero polling |
| MT5 integration | REST API client with auto-reconnect, 5-min cron sync |
| Double-entry ledger | Atomic debit/credit pairs in single Convex mutation |
| Dual-approval | Configurable threshold ($10K), second approver required |
| Commission engine | 5-level IB hierarchy, 4 tiers (Bronze/Silver/Gold/Platinum), per-symbol rates |
| Risk detection | Scalp (<5min), hedge pairs, HFT (20+/day), unverified trading |
| RBAC | 6 roles, 100+ granular permissions, server-side enforcement |
| Audit logging | Every mutation logged with old/new values, actor, timestamp |
| File storage | KYC documents, deposit proofs via Convex built-in storage |
| Global search | Cmd+K command palette across users, tickets, leads |
| Presence | @convex-dev/presence — see who's viewing the same record |
| Notifications | Real-time bell with unread count, mark as read |
| Badge counts | Sidebar shows pending KYC, tickets, deposits in real-time |
graph LR
subgraph "Frontend"
NJS["Next.js 15"]
R19["React 19"]
TW["Tailwind v4"]
SHAD["shadcn/ui"]
TANK["@tanstack/react-table"]
RCH["Recharts"]
LWC["lightweight-charts"]
end
subgraph "Backend"
CVX["Convex"]
CVXH["convex-helpers"]
CVXA["@convex-dev/auth"]
CVXP["@convex-dev/presence"]
CVXAG["@convex-dev/aggregate"]
end
subgraph "Tooling"
TURBO["Turborepo"]
PNPM["pnpm"]
BIOME["Biome"]
TS["TypeScript 5.5"]
end
NJS --> R19
R19 --> TW
TW --> SHAD
SHAD --> TANK & RCH
NJS --> CVX
CVX --> CVXH & CVXA & CVXP & CVXAG
TURBO --> PNPM
style CVX fill:#ff6600,stroke:#fff,color:#fff
style NJS fill:#000,stroke:#fff,color:#fff
| Layer | Technology | Version |
|---|---|---|
| Backend | Convex | ^1.34.x |
| Framework | Next.js | 15.x |
| UI Library | React | 19.x |
| Language | TypeScript | ^5.5 |
| CSS | Tailwind CSS | v4.x |
| Components | shadcn/ui | latest |
| Data Tables | @tanstack/react-table | v8.x |
| Charts | Recharts + lightweight-charts | v3.x / v5.x |
| Auth | @convex-dev/auth | latest |
| Presence | @convex-dev/presence | ^0.1.x |
| Aggregation | @convex-dev/aggregate | latest |
| Monorepo | Turborepo | ^2.9 |
| Package Manager | pnpm | ^10.8 |
| Linter | Biome | latest |
namh-crm-v3/
├── apps/
│ ├── admin/ # Broker staff admin panel
│ │ ├── app/(auth)/ # Login, signup
│ │ ├── app/(dashboard)/ # 40+ authenticated pages
│ │ │ ├── clients/ # User management, KYC
│ │ │ ├── trading/ # Accounts, MT5, positions, charts
│ │ │ ├── treasury/ # Deposits, withdrawals, wallets, vouchers
│ │ │ ├── partners/ # IB partners, commissions
│ │ │ ├── sales/ # Leads, pipeline, tasks, reports
│ │ │ ├── support/ # Tickets, templates
│ │ │ ├── risk/ # Risk alerts dashboard
│ │ │ ├── org/ # Staff, departments, branches
│ │ │ ├── settings/ # Roles, audit log, tags
│ │ │ └── reports/ # Reports hub
│ │ ├── components/ # 126 React components
│ │ └── hooks/ # Custom hooks
│ └── portal/ # Trader self-service portal
│ ├── app/(auth)/ # Portal login
│ ├── app/(dashboard)/ # 13 authenticated pages
│ └── components/ # Portal-specific components
├── packages/
│ ├── backend/
│ │ └── convex/ # 68 Convex backend files
│ │ ├── tables/ # 10 schema definition files (40+ tables)
│ │ ├── lib/ # Shared helpers (RBAC, audit, money)
│ │ ├── mt5/ # MT5 API client ("use node")
│ │ ├── trading/ # Trading account CRUD, sync, crons
│ │ ├── treasury/ # Double-entry ledger, approvals
│ │ ├── ib/ # Commission engine, tiers
│ │ ├── sales/ # Lead pipeline, scoring
│ │ ├── support/ # Tickets, SLA, templates
│ │ ├── risk/ # Detection engine, alerts
│ │ ├── org/ # Staff, departments
│ │ ├── portal/ # Portal-specific queries/mutations
│ │ ├── reports/ # KPI aggregations
│ │ ├── notifications/ # Real-time notifications
│ │ └── search/ # Global search across entities
│ ├── types/ # Shared TypeScript types
│ └── ui/ # Shared UI components (charts)
├── .planning/ # GSD workflow artifacts
├── CLAUDE.md # Project conventions
├── turbo.json # Turborepo config
└── package.json # Root workspace
- Node.js 20+
- pnpm 10+
- Convex account (convex.dev)
git clone https://github.com/darshjme/namhcrmv3.git
cd namhcrmv3
pnpm install# Start Convex backend + both frontends
pnpm dev
# Or start individually
npx convex dev # Backend
pnpm --filter admin dev # Admin panel (port 3000)
pnpm --filter portal dev # Client portal (port 3001)pnpm build# Deploy Convex backend
npx convex deploy
# Deploy frontends (Vercel, or any Next.js host)
pnpm --filter admin build
pnpm --filter portal buildSet these in your Convex Dashboard under Settings → Environment Variables:
| Variable | Description | Example |
|---|---|---|
MT5_API_URL |
MT5 Manager REST API base URL | https://mt5api.namhglobal.com |
MT5_MANAGER_LOGIN |
MT5 Manager login number | 1032 |
MT5_MANAGER_PASSWORD |
MT5 Manager password | your-password |
AUTH_SECRET |
Secret for @convex-dev/auth sessions | your-random-secret-32chars |
Create .env.local in each app:
apps/admin/.env.local:
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloudapps/portal/.env.local:
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloudAfter first deployment, run the seed functions from Convex Dashboard → Functions:
trading.seed:seedAccountTypes— Creates 5 default account typesib.seed:seedIbTiers— Creates 4 commission tiers (Bronze/Silver/Gold/Platinum)support.seed:seedQuickReplyTemplates— Creates 8 quick reply templates
| Role | Access Level |
|---|---|
| Super Admin | Full access to everything |
| Admin | All operations except system settings |
| Manager | Client management, trading, treasury, reports |
| Staff | View clients, process deposits, handle tickets |
| Viewer | Read-only access to all modules |
| Technical Admin | Full access + system configuration |
100+ granular permissions across modules: trading.create_account, treasury.balance_ops, ib.manage_partners, sales.convert_lead, support.manage_tickets, risk.view_alerts, etc.
| Token | Value | Usage |
|---|---|---|
| Primary Gold | #D3AE37 |
Buttons, accents, active states |
| Background | #060504 / #030303 |
Page and card backgrounds |
| Financial Positive | #39A86B |
Profit, deposits, approved |
| Financial Negative | destructive |
Loss, withdrawals, declined |
| Financial Font | JetBrains Mono | All monetary values (font-mono) |
Private. Copyright (c) 2026 NAMH Global Ltd.