Skip to content

How It Works

Ryan Bayne edited this page Oct 31, 2026 · 1 revision

How It Works

Status: active Category: E (product / user) Created: 2026-10-31 Last updated: 2026-10-31 Owner: TCS team

Three processes and a database. Nothing is hosted; there is no service in the middle.

flowchart LR
  subgraph your machine
    UI["React PWA<br/>:5173"] -->|HTTP JSON| API["NestJS API<br/>:3201"]
    API -->|SQL| DB[("MySQL")]
    API -->|HTTP| BR["MT5 bridge<br/>:5000, :5001 …"]
    API -->|HTTPS| P["14 data providers"]
    BR -->|native API| T["MetaTrader 5 terminal"]
  end
Loading

The four moving parts

Part Port What it is
Frontend 5173 React + Vite PWA. Renders server-computed state; it does not re-derive a score from a number
API 3201 NestJS. Scoring, gating, automation loop, persistence, and every business rule
Bridge 5000 + A Python process, one per brokered account, holding the MetaTrader 5 terminal connection
Database 3306 MySQL via Prisma

The scoring pipeline

flowchart TD
  A[Market data<br/>bars + quotes] --> B[Protocol selects its directives]
  B --> C[Each directive scores 0..maxScore]
  C --> D[Composite = sum of directive scores]
  D --> E{Gates<br/>threshold · session · risk · liquidity}
  E -->|refused| F[Recorded with a reason]
  E -->|passed| G[Signal]
  G --> H{Bot subscribed<br/>to this protocol?}
  H -->|no| I[Nothing queued — deliberately]
  H -->|yes| J[Envelope: size, SL, TP]
  J --> K[Risk chain]
  K --> L{Broker can trade<br/>this symbol?}
  L -->|no| F
  L -->|yes| M[Order]
  M --> N[Decision trail]
Loading

Why the order matters. A score that never becomes a trade is not a failure — it is a filter working. The stages are ordered cheapest-first so the expensive work (broker capability checks, order validation) only runs on candidates that already survived the cheap ones.

Two things people misread

A composite is not a percentage. Each directive declares its own maxScore, and the protocol total is the sum of those. The UI shows a normalised 0–100 for display only; the stored number is unbounded. A directive worth 200 carries ten times the weight of one worth 20 — that is the whole weighting system.

tradeMode means three different things depending on where you read it: MT5's symbol permission (0–4), the bot mode (auto | manual), and — since 2026-10 — the account kind (demo | real), which is why that last one is called accountKind. If you are reading the schema, check which you have.

The automation loop

A tick scores the symbols a bot is subscribed to, gates them, and dispatches. It is a loop, not a daemon per bot: one cycle, one pass, one set of decisions, all recorded. A failed status call renders "status unavailable" — never "stopped" — because those mean opposite things.

Where a bug usually hides

The failure signature this project keeps meeting is plausible output with no error: a stale symbol still returns a score, a mis-sized trade still returns a fill, a wrong denominator still returns a percentage. When something looks wrong, check whether the system knew it could not answer — a CANNOT JUDGE next to the number is usually the whole explanation.

More depth: Scoring architecture · Risk controls · How a bot becomes a trade.

Clone this wiki locally