# Master Reader EA — Implementation Plan

## 1. Scope

Build `MasterReader.mq5`.

After compilation:

```text
MasterReader.ex5
```

It runs inside MT5 Desktop on a Windows MT5 Host connected to a Master Source account using authorized read-only/investor credentials.

## 2. Core Rule

Master Reader is strictly read-only.

It must never:

- open trades
- modify trades
- close trades
- send broker trading commands

## 3. Runtime

```text
Windows MT5 Host
└── MT5 Desktop
    └── MasterReader.ex5
```

The `.mq5` source remains in Git.

The `.ex5` file is deployed to MT5.

## 4. Master Source Credentials

Input/configuration:

```text
MT5 Login
Investor / Read-Only Password
Broker Server
Copier Master ID
Copier API Credential
```

Never send the broker trading password to the Copier Server.

## 5. Observation Strategy

Because the source account is read-only, do not rely exclusively on `OnTradeTransaction()`.

Use a combination of:

- current open positions
- deals/history where accessible
- periodic polling
- local known-state cache
- change comparison
- reconciliation
- duplicate suppression

The exact detection algorithm must be proven in a POC.

## 6. Target Events

Generate normalized events:

```text
POSITION_OPEN
POSITION_MODIFY
POSITION_PARTIAL_CLOSE
POSITION_CLOSE
```

## 7. Local State

Maintain enough local state to identify:

```text
Master position
Symbol
Side
Volume
Price
SL
TP
Last observed state
```

Avoid sending unchanged state repeatedly.

## 8. Event Identity

Each event should contain:

```text
event_id
master_id
sequence
master_position_id
event_type
timestamp
```

Sequence increases per Master.

## 9. Network Layer

Preferred architecture:

```text
MasterReader EA
      │
      ▼
secure transport
      │
      ▼
Go Copier Server
```

The transport mechanism must be validated in a POC.

Test:

1. HTTPS/WebRequest approach
2. Persistent WebSocket approach if a reliable MQL5 implementation is available

Do not assume WebSocket support is trivial.

## 10. Heartbeat

Send heartbeat at a configurable interval.

Track:

```text
connection state
last sent event
last server response
```

## 11. Reconnect

On network failure:

```text
disconnect
→ backoff
→ reconnect
→ resynchronize local state
```

Do not produce duplicate events after reconnect.

## 12. Synchronization

Support a current-state snapshot.

When requested:

```text
SYNC_SNAPSHOT
```

should contain all currently relevant open positions.

## 13. POC Sequence

First implementation should be:

```text
Master Source read-only
        ↓
MasterReader.ex5
        ↓
secure connection
        ↓
Go server
        ↓
console log
```

Test:

```text
open
modify
partial close
close
```

## 14. Definition of Done

The Master Reader is accepted when it reliably detects the tested source-account changes and sends normalized events to Go without false duplicate trades/events.