# Copier Server — Implementation Plan

## 1. Scope

Build the central Go Copier Server on Debian 13.

Responsibilities:

- Master connections
- Follower connections
- authentication
- event validation
- routing
- persistence
- sequencing
- ACK
- replay
- mapping
- synchronization
- reconciliation coordination
- heartbeat
- operational metrics

The Go server never executes broker trades.

## 2. Runtime

Production:

```text
Debian 13
└── Go native Linux binary
    └── systemd
```

Recommended:

```text
/opt/copier/server/
/etc/systemd/system/copier.service
```

Go should listen on a private/local port such as:

```text
127.0.0.1:8080
```

Apache exposes the public HTTPS/WSS endpoint.

## 3. Development

Mac:

```text
Go native
MySQL native
```

Run locally during development:

```bash
go run ./cmd/server
```

## 4. Project Structure

```text
server/
├── cmd/server/main.go
├── internal/
│   ├── auth/
│   ├── websocket/
│   ├── master/
│   ├── follower/
│   ├── events/
│   ├── routing/
│   ├── mapping/
│   ├── synchronization/
│   ├── reconciliation/
│   ├── repository/
│   ├── service/
│   └── telemetry/
├── migrations/
└── README.md
```

## 5. Phase 1 — Minimal WSS Server

Implement:

- server startup
- WSS endpoint
- health endpoint
- Master authentication
- Follower authentication
- heartbeat
- connection registry
- structured logging

No database dependency is required for the first connectivity POC if an in-memory registry is sufficient.

Success:

```text
Master Reader connects
Follower connects
Both are authenticated
Heartbeat works
```

## 6. Phase 2 — Master Event Intake

Implement:

- normalized event schema
- event validation
- Master identity
- event ID
- per-Master sequence
- durable event storage
- ACK to Master Reader

Success:

```text
Master Reader
→ Go
→ validated event
→ stored
→ ACK
```

## 7. Phase 3 — Routing

Implement:

```text
master_follower_links
```

For every Master event:

1. identify Master
2. find active linked Followers
3. create delivery records
4. send to target Followers

Never broadcast globally.

## 8. Phase 4 — Follower Delivery

Implement:

- delivery status
- follower authentication
- event ACK
- failed delivery tracking
- retry policy
- connection status

## 9. Phase 5 — Position Mapping

Implement:

```text
master_id
master_position_id
follower_id
follower_position_id
```

Support lifecycle:

```text
open → map
modify → update mapped follower
partial close → update mapping/state
close → close mapped follower
```

## 10. Phase 6 — Replay and Idempotency

Use:

```text
event_id
master_id + sequence
```

Follower reconnect sends:

```text
last_processed_sequence
```

Server replays missing events.

Duplicate event:

```text
already processed
→ do not send duplicate execution
→ ACK safely
```

## 11. Phase 7 — Synchronization

Support:

```text
SYNC_REQUEST
SYNC_SNAPSHOT
SYNC_COMPLETE
```

New Followers can synchronize existing Master positions.

## 12. Phase 8 — Reconciliation

Provide APIs/services to compare:

```text
expected state
vs
reported Follower state
```

Initial release reports discrepancies rather than making destructive automatic repairs.

## 13. Phase 9 — Multi-Master / Multi-Follower

Validate:

```text
Master A → A1,A2
Master B → B1,B2,B3
Master C → C1
```

Strict routing isolation is mandatory.

## 14. Phase 10 — Risk/Configuration Support

The server should expose configuration used by Followers:

- lot mode
- multiplier
- max lot
- max positions
- allowed symbols
- allowed direction
- symbol mappings
- copy enabled

## 15. API

Initial:

```text
GET /health
GET /ready

POST /api/v1/auth/master
POST /api/v1/auth/follower

GET /api/v1/events
GET /api/v1/events/{event_id}

GET /api/v1/positions
GET /api/v1/executions
```

Management APIs may be exposed through CodeIgniter and/or an internal Go API.

## 16. Apache Integration

Public:

```text
https://copier.example.com
wss://copier.example.com/ws
```

Apache proxies WSS to:

```text
127.0.0.1:8080
```

MySQL is never public.

## 17. MySQL Tables Used by Server

```text
master_sources
followers
master_follower_links
trade_events
event_deliveries
position_mappings
execution_logs
heartbeats
```

## 18. Testing

Test:

- connection
- authentication
- event validation
- routing
- duplicate event
- missing sequence
- reconnect
- replay
- server restart
- database failure
- follower execution ACK
- cross-master isolation

## 19. Definition of Done

```text
Master Reader
→ Go
→ correct target Followers
→ Follower ACK
→ mapping stored
→ reconnect/replay works
→ duplicate does not duplicate
```