ZuluTrade CRM at a glance

Services

Sign-up Sequence — Email + OTP

1. Register request — FE submits the registration form to client-express.
2. Lead created — client-express writes a lead record into MariaDB via client-mysql.
3. OTP email — client-express triggers communication service, which dispatches the OTP email through Sendgrid.
4. OTP verified — user submits the OTP; client-express → client-mysql creates the user record in MariaDB. This record is later used by client-express to issue JWT tokens and manage login sessions / auth.
5. Postgres mirror — client-express sends a POST to users-service, which creates the matching user record in the Postgres zulu3 database.
6. Event broadcast — users-service publishes a userRegister event on RabbitMQ so every downstream service can react.
7. ACT customer profile — connector-hub listens to the userRegister event and passes it on to temp-trader, which creates an ACT customer profile. On successful profile creation, an ActCustomer event is published on RabbitMQ; users-service consumes it and stores the details in the Postgres user profile.

Sign-up Sequence — SSO (Google / Apple)

1. client-express forwards the SSO request directly to auth-service.
2. The provider verifies email ownership. On success, client-express creates the user if it does not already exist (skipping the OTP step — the provider has already verified the address) and issues the session without requiring a password.

Flavour / Country

On the registration form, flavour-service provides the country list and tells the FE which flavour ID is linked to the current domain, so the right white-label configuration and feature flags are applied.

Services

Role availability

• Leader → MT4, MT5, ACT, Ctrade, Telegram, Discord.
• Copier → MT4, MT5, ACT, Ctrade only (social sources can't act as copy execution venues).

Phase 1 · Account setup

User signs up or logs in. Detail lives in Module 01 Onboarding & Login — SSO flows (Apple / Google), OTP verification, profile writes by users-service, session issuance by auth-service. Not duplicated here.

Phase 2 · Broker connection

User connects a trading account. Detail lives in Module 02 Account Connection. The orchestrator is connector-hub; demo accounts route through temp-trader to S281. Live accounts go through the MT4 / MT5 / ACT / cTrader connectors.

Phase 3 · Subscription gating

The commercial layer. Copy-trading is gated by a subscription — free or paid.

• Paid path — subscriptions exposes plan / cart / payment endpoints. The user checks out through Stripe; a Stripe webhook triggers activation; the subscription is marked active and feature entitlements are written.
• Free path — a background consumer inside subscriptions processes free-plan activation events. Passing eligibility → auto-activation; failing → user falls back to a paid plan.
• Credits are allocated per plan; audit history is recorded; state lives in PostgreSQL.

Without an active subscription with the right entitlement, the Start Copying step (below) is blocked.

Phase 4 · Leader discovery / selection

The UI lists available Leaders. client-express fronts the requests; Leader records are fetched via leaders-service, which forwards to FTL. leaders-service owns no data — it's a thin HTTP gateway with logging / validation.

Phase 5 · Start copying

The actual activation. connector-hub orchestrates:

1. Calls copier-service to create the follower record — forwarded to FTL.
2. Publishes a startCopy event on RabbitMQ (Social Trader broker, vhost /zulu, exchange zulu).
3. rewards-service consumes startCopy, creates a copy session in PostgreSQL, and schedules recurring reward jobs via BullMQ. Detail in Module 08 Rewards.
4. notifications-service sends a "you're now copying X" confirmation via the user's preferred channel.

From this point on, the Copier is active. Signals from the Leader's trades flow through Module 05 Trading Flow and Module 06 Bridges — not this module.

Phase 6 · Stop copying (closeout)

1. User stops from UI → connector-hub → copier-service removes the follower record on FTL.
2. connector-hub publishes stopCopy on RabbitMQ.
3. rewards-service closes the copy session. Background workers continue to process pending reward transactions, handle overdue / recovery, and run month-end settlement so earned rewards aren't lost even if the service was briefly down.
4. The subscription itself continues unless the user cancels / pauses separately via subscriptions APIs.
5. If the subscription ends, copying also stops — subscriptions publishes the subscription-end event; connector-hub reacts by triggering stopCopy for the affected follower records.

Services touched in this lifecycle

Phase 1 · Account setup

User signs up or logs in. Detail in Module 01 Onboarding & Login — SSO, OTP, profile writes. Not duplicated here.

Phase 2 · Broker connection

User connects the broker whose trades they want to publish. Detail in Module 02 Account Connection. Orchestrated by connector-hub; ACT-side connections go through temp-trader. Demo accounts aren't relevant here — Leaders need a live broker.

Phase 3 · Leader application

The user submits a Leader application from the client UI via connector-hub. The application creates a pending Leader record waiting for admin review.

Phase 4 · Admin approval

An admin reviews the application via admin-express. admin-service handles roles / permissions / approval audit on the admin side. The admin either approves or rejects:

• Rejected — the flow ends. The user is notified; no Leader record is created on FTL.
• Approved — the approval action triggers Phase 5. The audit record is retained in admin-service.

Phase 5 · Leader registration + strategy setup

1. On approval, connector-hub calls leaders-service to create the Leader record. leaders-service owns no state — it forwards to FTL, which holds the actual Leader record.
2. connector-hub handles leader / watchlist / strategy management (symbols, marketing description, copy settings — exact scope depends on how "strategy" is configured in the platform).
3. notifications-service sends a "you're now a Leader" confirmation.

Registration is synchronous — no RabbitMQ lifecycle events on the Leader side (unlike startCopy / stopCopy for Copiers).

Phase 6 · Active leader and closeout

Once registered, the Leader's trades become the source of signals. That flow lives in Module 05 Trading Flow. Earnings from copier activity accrue through Module 08 Rewards.

Closeout is two-path:

• Self-serve — user deregisters from the client UI → connector-hub → leaders-service (remove) → FTL.
• Admin-revoked — admin uses admin-express to revoke the Leader → same downstream path.

Services touched in this lifecycle

Pipeline Stages

1. Ingestion — MT4/MT5 and TG/Discord orders enter via Node Middleware. Web orders (Demo & Act accounts) enter via Act web trader System. ACT platform and Fxview s245 broker events enter via Order Update service over WebSocket.
2. Classification — Signal junction routes each MT/Social signal to a platform-specific queue (MT4, MT5, TG_CONNECTOR, DISCORD). Defect detection (price=0 for MT4/MT5/CTrade) writes a defect:<algo>_<order> key to Redis for the external signal-synchronizer to repair.
3. Processing — Signal Processor (ts-zulu3.0-signal-processor) consumes the platform queues and the shared ACT queue. It calls FTL s281 via HTTP (leader / copier / order URLs) to execute leader-copier fan-out and publishes signal_orders + trade_logs to the persistence pipeline.
4. Return / Routing — FTL pushes resulting signals over WebSocket to act-signal-processor, which publishes ftl-signal on the ftl queue. Signal Out consumes it and dispatches via platform publishers: MT copiers → routing key out on signal.out queue (consumed by Node Middleware → terminal); Demo/Act/TG/Discord copiers → routing key ACT on the ACT queue (looped back into Signal Processor); ACT broker dispatch → act signal out queue → Act Bridge Service.
5. Web-order ack path — For orders placed via Zulu Web, Signal Out also publishes an immediate acknowledgement on routing key OU<AccountID> (Order Update ack) and an RPC reply to the caller's reply queue, then ACKs the web-orders message last.
6. ACT execution feedback — ACT broker dealer sockets push trade / order events to Order Update service over WebSocket. Order Update republishes on the signalData exchange (routing key order). Act-bridge-signal-processor consumes the act.order queue, normalises, and publishes back into Signal Processor via the ACT queue to keep state coherent.
7. Persistence — Persistence service binds the persistence queue to the signal_orders and trade_logs topics published by Signal Processor and Signal Out. It writes to PostgreSQL (signal_processor.signals, signal_processor.trade_logs) asynchronously, keeping the hot path DB-free. Redis holds the live state; if it is lost the cache is rebuilt from Postgres.

Services

Sub-bridges

Services

Services

Responsibilities

• Session lifecycle — creates a copy session when a startCopy event arrives on RabbitMQ; closes it on stopCopy.
• Reward calculation — schedules recurring reward jobs at configured intervals after session creation.
• Job execution — background BullMQ workers (Redis-backed) create reward transactions, handle overdue or recovery scenarios, and run month-end settlement so earnings stay consistent even after downtime.
• Payout workflow — wallet and withdrawal modules own the payout-side data that gets hit after rewards are earned.
• Public APIs — schedule/stop rewards manually, fetch reward transactions, fetch reward stats, and CRUD-style endpoints on wallet + withdrawal.

Service

Badge event topics

Known topics per the Confluence catalogue. Implementation status per topic not documented here — ignore.

Responsibilities

• Event intake + validation — pulls messages from badges.*, validates payload structure.
• Rule mapping — topic → specific badge rule; per-user progress updated in PostgreSQL.
• Earned marking — when a rule's condition is met, the badge is marked earned for the user.
• History entry — every change recorded for audit / display.
• Public APIs — run badge check directly, fetch all active badges (catalogue), fetch user-specific badges with optional account-level context.

Service

Services

External Integrations

Admin-owned services

Services

Operational Tooling

Reality check — 2026-04-20

What the code assumes versus what's actually running today. Worth keeping in mind when reading the rest of the doc.

Onboarding · Login

Account Connection

Engagement

Analytics

Rewards

Badges

Trading Flow

Bridges

ACT Bridge

node-middleware

Admin

Ops / Data Pipeline

Infrastructure