# System Design

## Overview

MW-Core is a Phoenix Umbrella application serving as the middleware layer for the MercuryPay
Transaction Management System (TMS). It decouples external-facing communication channels from
internal banking and data systems through a four-plane architecture.

---

## System Context Diagram

```
┌──────────────────────────────────────────────────────────────────────────────────┐
│                           EXTERNAL CLIENTS                                       │
│                                                                                  │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐   │
│   │  REST/JSON  │  │  WebSocket  │  │  Browser    │  │  Mobile App         │   │
│   │  Clients    │  │  Clients    │  │  (Admin)    │  │  iOS / Android      │   │
│   └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘   │
└──────────┼────────────────┼────────────────┼─────────────────────┼──────────────┘
           │                │                │                     │
           ▼                ▼                ▼                     ▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│                         NORTH PLANE  —  Gateways                                 │
│                                                                                  │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────────────────────┐   │
│   │ gateway_api │  │ gateway_ws  │  │ gateway_web │  │  gateway_mobile      │   │
│   │ REST/JSON   │  │ WebSocket   │  │ LiveView    │  │  Versioned REST      │   │
│   │ Bandit/HTTP │  │ Channels    │  │ Admin UI    │  │  + Push Notif.       │   │
│   └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────────┬───────────┘   │
└──────────┼────────────────┼────────────────┼─────────────────────┼───────────────┘
           └────────────────┴────────────────┴─────────────────────┘
                                         │
                                         ▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│                          CORE PLANE  —  Processing                               │
│                                                                                  │
│    ┌──────────┐     ┌───────────┐     ┌──────────────┐     ┌──────────────┐      │
│    │ mw_auth  │────►│ mw_router │────►│ mw_transform │────►│  mw_audit    │      │
│    │ JWT/RBAC │     │ Pipeline  │     │ Map/Validate │     │  Compliance  │      │
│    └──────────┘     └─────┬─────┘     └──────────────┘     └──────────────┘      │
│                           │                                                      │
│    ┌──────────────────────────────────────────────────┐                         │
│    │              mw_kernel (shared contracts)        │                         │
│    │   Message · Context · Adapter behaviour · Error  │                         │
│    └──────────────────────────────────────────────────┘                         │
└───────────────────────────────────┬──────────────────────────────────────────────┘
                                    │
                                    ▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│                         SOUTH PLANE  —  Adapters                                 │
│                                                                                  │
│   ┌────────────────┐  ┌────────────┐  ┌──────────────┐  ┌──────────────────┐    │
│   │ adapter_banking│  │ adapter_dw │  │ adapter_http │  │  adapter_file    │    │
│   │ Core Banking   │  │ Data Wareh.│  │ Internal REST│  │  SFTP/CSV/XML    │    │
│   │ ISO 8583       │  │ ETL/Batch  │  │ SOAP/HTTP    │  │  File Watcher    │    │
│   └───────┬────────┘  └──────┬─────┘  └──────┬───────┘  └──────────┬───────┘    │
└───────────┼───────────────────┼───────────────┼──────────────────── ┼────────────┘
            │                   │               │                     │
            ▼                   ▼               ▼                     ▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│                        INFRA PLANE  —  Shared Services                           │
│                                                                                  │
│   ┌────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────────────────────┐    │
│   │ infra_repo │  │ infra_cache │  │ infra_queue │  │  infra_telemetry     │    │
│   │ Ecto/MySQL │  │ ETS/Redis   │  │ Broadway    │  │  OTel/Prometheus     │    │
│   └────────────┘  └─────────────┘  └─────────────┘  └──────────────────────┘    │
└──────────────────────────────────────────────────────────────────────────────────┘
            │                   │               │                     │
    ┌───────▼──────┐   ┌────────▼──────┐  ┌────▼──────────┐  ┌──────▼──────────┐
    │ Core Banking │   │  Data         │  │  Internal     │  │  File-Based     │
    │ System       │   │  Warehouse    │  │  REST/SOAP APIs│  │  Systems (SFTP) │
    └──────────────┘   └───────────────┘  └───────────────┘  └─────────────────┘
```

---

## Four-Plane Model

### North Plane — Inbound Gateways
Handles all external-facing communication. Each gateway speaks the client's protocol and
converts incoming requests into the canonical `MwKernel.Message` format before passing
to the core plane.

| Gateway | Protocol | Use Case |
|---------|----------|----------|
| `gateway_api` | HTTP/REST (JSON) | Third-party integrations, machine-to-machine |
| `gateway_ws` | WebSocket (Channels) | Real-time event push to web clients |
| `gateway_web` | HTTP/LiveView | Internal admin, monitoring, configuration |
| `gateway_mobile` | HTTP/REST (compact JSON) | iOS/Android native apps |

### Core Plane — Processing
Stateless processing stages. Every request flows through this plane in a defined order.
No core plane app speaks directly to any external system.

| App | Role |
|-----|------|
| `mw_kernel` | Shared canonical types and behaviour contracts |
| `mw_auth` | Identity verification and access control |
| `mw_router` | Route resolution and pipeline orchestration |
| `mw_transform` | Schema mapping and data validation |
| `mw_audit` | Structured compliance logging |

### South Plane — Adapters
Each adapter implements the `MwKernel.Adapter` behaviour. The core plane never knows
which protocol the downstream system uses — only the adapter knows.

| Adapter | System Type | Protocol |
|---------|-------------|----------|
| `adapter_banking` | Core banking | ISO 8583, proprietary REST |
| `adapter_dw` | Data warehouse | JDBC-style queries, bulk API |
| `adapter_http` | Internal REST/SOAP | HTTP, XML/JSON |
| `adapter_file` | File-based systems | SFTP, CSV, XML, flat files |

### Infra Plane — Shared Services
Cross-cutting concerns consumed by all planes. No business logic lives here.

| App | Provides |
|-----|---------|
| `infra_repo` | Ecto repo, migrations, schema persistence |
| `infra_cache` | ETS hot cache, optional Redis L2 |
| `infra_queue` | Broadway back-pressure pipelines, DLQ |
| `infra_telemetry` | Telemetry metrics, OTel tracing, LiveDashboard |

---

## Key Design Principles

1. **Protocol isolation** — Gateways absorb all protocol complexity. Core logic sees only `MwKernel.Message`.
2. **Adapter uniformity** — All south-side systems implement the same `MwKernel.Adapter` behaviour. Adding a new backend = new adapter app, zero changes to core.
3. **Pipeline immutability** — The processing pipeline is a pure Plug chain. Each stage receives a context and returns a (possibly modified) context. No side effects except audit writes.
4. **Failure containment** — Each adapter runs under its own supervisor. Circuit breakers prevent cascading failures. Async work (Broadway) is fully decoupled from the request path.
5. **Operator control** — Routing rules are stored in ETS (hot) and DB (durable). Operators can change routing behaviour via the admin UI without redeployment.
6. **Observability first** — Every message carries a `trace_id`. All telemetry events are emitted at every stage boundary. OTel spans span the full request lifecycle.