# MW-Core Documentation

MercuryPay Transaction Management System — Middleware Core

This documentation covers the full architecture of `mw-core`, a Phoenix Umbrella application
that acts as the middleware layer between external-facing channels and internal banking systems.

---

## Contents

### Architecture
| Document | Description |
|----------|-------------|
| [System Design](architecture/system-design.md) | High-level system context, planes, and component overview |
| [Umbrella Structure](architecture/umbrella-structure.md) | Full directory layout and app boundaries |
| [Request Flow](architecture/request-flow.md) | End-to-end request lifecycle through the pipeline |
| [Technology Stack](architecture/technology-stack.md) | Library choices and rationale |

### Architecture Decision Records
| ADR | Title | Status |
|-----|-------|--------|
| [ADR-001](adr/ADR-001-phoenix-umbrella.md) | Phoenix Umbrella over Single App | Accepted |
| [ADR-002](adr/ADR-002-adapter-behaviour.md) | Adapter Behaviour for South-Side Systems | Accepted |
| [ADR-003](adr/ADR-003-plug-pipeline.md) | Plug-based Pipeline for Request Processing | Accepted |
| [ADR-004](adr/ADR-004-dual-authentication.md) | JWT + API Key Dual Authentication | Accepted |
| [ADR-005](adr/ADR-005-broadway-async.md) | GenStage + Broadway for Async / Batch Processing | Accepted |
| [ADR-006](adr/ADR-006-single-repo.md) | Single Shared Ecto Repo with Schema Ownership | Accepted |
| [ADR-007](adr/ADR-007-opentelemetry.md) | OpenTelemetry for Distributed Tracing | Accepted |
| [ADR-008](adr/ADR-008-dynamic-routing.md) | ETS-Backed Dynamic Routing Table | Accepted |

### Components
| Document | Description |
|----------|-------------|
| [Component Catalog](components/component-catalog.md) | All 17 umbrella apps, their plane, and responsibilities |
| [North Plane Gateways](components/north-plane-gateways.md) | gateway_api, gateway_ws, gateway_web, gateway_mobile |
| [Core Plane](components/core-plane.md) | mw_kernel, mw_auth, mw_router, mw_transform, mw_audit |
| [South Plane Adapters](components/south-plane-adapters.md) | adapter_banking, adapter_dw, adapter_http, adapter_file |
| [Infrastructure Plane](components/infra-plane.md) | infra_repo, infra_cache, infra_queue, infra_telemetry |

### Implementation Phases
| Document | Description |
|----------|-------------|
| [Phase Overview](phases/phase-overview.md) | All 6 phases with timeline and deliverables |
| [Phase 0 — Foundation](phases/phase-0-foundation.md) | Umbrella scaffold, kernel, infra wiring |
| [Phase 1 — API Gateway](phases/phase-1-api-gateway.md) | REST gateway + auth + banking adapter |
| [Phase 2 — Async Adapters](phases/phase-2-async-adapters.md) | File, DW adapters + Broadway queue |
| [Phase 3 — WebSocket](phases/phase-3-websocket.md) | WebSocket gateway + real-time push |
| [Phase 4 — Admin UI](phases/phase-4-admin-ui.md) | LiveView dashboard + dynamic routing |
| [Phase 5 — Mobile](phases/phase-5-mobile.md) | Mobile gateway + transform engine |
| [Phase 6 — Hardening](phases/phase-6-hardening.md) | Production hardening, observability, clustering |
| [Phase 7 — Composite Aggregation](phases/phase-7-composite-aggregation.md) | Fan-out dispatch, response merging, partial failure semantics |
| [Phase 8 — Visual Flow Builder](phases/phase-8-visual-flow-builder.md) | jsPlumb canvas designer, node palette, execution overlay, undo/redo |

### Delivery Governance
| Document | Description |
|----------|-------------|
| [Development Readiness Gate](governance/development-readiness-gate.md) | Go/No-Go checklist before assigning implementation teams |

### Contracts
| Document | Description |
|----------|-------------|
| [REST API Contract Baseline](contracts/rest-api-contracts.md) | OpenAPI scope, required endpoints, and contract lifecycle |
| [Event Contract Baseline](contracts/event-contracts.md) | Async topic and payload contract baseline for PubSub/WebSocket/Broadway |

### Security
| Document | Description |
|----------|-------------|
| [Security Baseline (Phase 0-2)](security/security-baseline-phase-0-2.md) | Shift-left controls required before production hardening |

### Testing & Operations
| Document | Description |
|----------|-------------|
| [Testing Strategy](testing/testing-strategy.md) | Test pyramid, gates, and phase-aligned quality checks |
| [Operations Runbooks](operations/runbooks.md) | Deploy, rollback, incident, key rotation, and DLQ procedures |

---

## Quick Reference

### Naming Conventions
- North apps: `gateway_*`
- Core apps: `mw_*`
- South apps: `adapter_*`
- Infra apps: `infra_*`

### Module Naming
```
GatewayApi.Web.Router
MwAuth.JWT
MwRouter.Pipeline
AdapterBanking.Client
InfraRepo.Repo
```

### Request Pipeline Order
```
Auth → RateLimit → Transform → Route → CircuitBreaker → Adapter → Transform → Audit → Response
```