# MT5 Trade Copier SaaS — Architecture

## 1. Purpose

This document is the shared architecture contract for all project components.

Components:

- Copier Server
- Dashboard
- Master Reader EA
- Follower EA
- MySQL
- MT5 Hosts

All implementation plans must follow this document.

## 2. Terminology

### Master Source
An MT5 trading account belonging to another party. The system observes its trading activity using authorized read-only/investor credentials.

### Follower
An MT5 trading account that receives and executes copied trades.

### Master Reader EA
MQL5 EA running inside MT5 Desktop connected to a Master Source. It observes and reports trading state. It must never trade.

### Follower EA
MQL5 EA running inside MT5 Desktop connected to a Follower account. It receives commands and executes trades.

### Copier Server
Debian 13 server hosting Go, CodeIgniter 4, MySQL 8, and Apache.

### MT5 Host
A Windows environment used to run MetaTrader 5 Desktop and `.ex5` EAs. It does not need to be Windows Server.

## 3. High-Level Architecture

```text
                        INTERNET
                           │
                    HTTPS / WSS / TLS
                           │
                           ▼
              ┌─────────────────────────┐
              │      COPIER SERVER      │
              │        Debian 13        │
              │                         │
              │ Apache                  │
              │ CodeIgniter 4           │
              │ Go Copier Core          │
              │ MySQL 8                 │
              │ systemd                 │
              └────────────┬────────────┘
                           │
                 ┌─────────┴─────────┐
                 │                   │
                WSS                 WSS
                 │                   │
                 ▼                   ▼
          ┌──────────────┐    ┌──────────────┐
          │   MT5 Host   │    │   MT5 Host   │
          │   Windows    │    │   Windows    │
          │              │    │              │
          │ MT5 Desktop  │    │ MT5 Desktop  │
          │ MasterReader │    │ Follower EA  │
          │    .ex5      │    │    .ex5      │
          └──────┬───────┘    └──────┬───────┘
                 │                   │
           Master Source           Follower
             Read Only             Trading
```

## 4. Multi-Master / Multi-Follower

The core model is:

```text
MASTER-A
├── F-A1
├── F-A2
└── F-A3

MASTER-B
├── F-B1
└── F-B2

MASTER-C
└── F-C1
```

Routing belongs to Go. A Master event must only reach Followers linked to that Master.

## 5. Network Topology

All MT5 terminals establish outbound secure connections to the Copier Server.

No direct Master VPS → Follower VPS connection is required.

```text
Master MT5 Host ──WSS──► Debian Copier Server ◄──WSS── Follower MT5 Host
```

## 6. Server Stack

Development on Mac is native:

```text
Go
PHP
CodeIgniter 4
MySQL 8
MQL5 source
Git
```

Production on Debian 13 is native/non-Docker:

```text
Apache
PHP
CodeIgniter 4
MySQL 8
Go
systemd
```

Docker is not used.

## 7. MT5 Runtime

MQL5 source:

```text
MasterReader.mq5
FollowerCopier.mq5
```

Compiled:

```text
MasterReader.ex5
FollowerCopier.ex5
```

`.ex5` runs inside MT5 Desktop on Windows.

MT5 Android is monitoring only and does not run EA files.

## 8. Data Ownership

Go owns real-time MT5 communication and event routing.

CodeIgniter owns administration and dashboard operations.

MySQL stores durable shared application state.

MQL5 EAs own broker-side observation and trade execution.

## 9. Core Event Types

Initial:

```text
POSITION_OPEN
POSITION_MODIFY
POSITION_PARTIAL_CLOSE
POSITION_CLOSE
```

Future:

```text
PENDING_ORDER_CREATE
PENDING_ORDER_MODIFY
PENDING_ORDER_CANCEL
```

## 10. Position Mapping

Every copied position must preserve:

```text
master_id
master_position_id
follower_id
follower_position_id
```

Never close a follower position by symbol alone when an explicit mapping exists.

## 11. Reliability

Use:

- unique event IDs
- per-Master sequences
- at-least-once delivery
- idempotent follower execution
- ACKs
- replay after reconnect
- periodic synchronization
- reconciliation

## 12. Security

- TLS/WSS
- separate copier credentials
- read-only Master broker credentials
- no Master trading password in the server
- no secrets in logs
- role-based dashboard access
- private MySQL
- Go internal port protected
- credential rotation

## 13. Shared Contract

The following must be agreed before component implementation diverges:

- IDs
- event schema
- sequence semantics
- ACK semantics
- position mapping
- authentication
- synchronization protocol
- API contract
- database relationships