# Component Catalog

All 17 umbrella apps with their plane, primary responsibilities, key modules, and inter-app dependencies.

---

## Summary Table

| App | Plane | Type | Key Responsibility |
|-----|-------|------|-------------------|
| [mw_kernel](#mw_kernel) | Shared | Foundation | Canonical types, behaviour contracts |
| [gateway_api](#gateway_api) | North | Gateway | REST/JSON public API |
| [gateway_ws](#gateway_ws) | North | Gateway | WebSocket real-time channels |
| [gateway_web](#gateway_web) | North | Gateway | LiveView admin dashboard |
| [gateway_mobile](#gateway_mobile) | North | Gateway | Mobile-optimised REST + push |
| [mw_auth](#mw_auth) | Core | Processing | AuthN/AuthZ, JWT, API keys, RBAC |
| [mw_router](#mw_router) | Core | Processing | Pipeline, routing, circuit breaker |
| [mw_transform](#mw_transform) | Core | Processing | Schema mapping, validation |
| [mw_audit](#mw_audit) | Core | Processing | Compliance audit logging |
| [adapter_banking](#adapter_banking) | South | Adapter | Core banking (ISO 8583) |
| [adapter_dw](#adapter_dw) | South | Adapter | Data warehouse ETL/query |
| [adapter_http](#adapter_http) | South | Adapter | Generic internal REST/SOAP |
| [adapter_file](#adapter_file) | South | Adapter | SFTP, CSV, XML file systems |
| [infra_repo](#infra_repo) | Infra | Shared | Ecto repo, migrations |
| [infra_cache](#infra_cache) | Infra | Shared | ETS hot cache, Redis L2 |
| [infra_queue](#infra_queue) | Infra | Shared | Broadway async pipelines |
| [infra_telemetry](#infra_telemetry) | Infra | Shared | OTel tracing, Prometheus metrics |

---

## mw_kernel

**Plane:** Shared Foundation
**Depends on:** Nothing (no internal deps)
**Depended on by:** All apps

The lowest layer — defines the contracts that all other apps use. Must never import any
other internal umbrella app.

| Module | Purpose |
|--------|---------|
| `MwKernel.Message` | Canonical request/response envelope. Flows through entire pipeline. |
| `MwKernel.Context` | Per-request context: trace_id, tenant, user, roles, halted flag |
| `MwKernel.Error` | Unified error struct with code, message, metadata |
| `MwKernel.Adapter` | `@behaviour` — connect/send/health_check/disconnect callbacks |
| `MwKernel.Gateway` | `@behaviour` — ingest/respond callbacks for north-side gateways |
| `MwKernel.StreamingAdapter` | Extended behaviour for streaming south-side adapters |

---

## gateway_api

**Plane:** North — Inbound Gateway
**Depends on:** mw_kernel, mw_router, mw_auth, infra_telemetry
**Port:** 4000 (configurable)

Public-facing REST/JSON API. Handles versioning (`/api/v1/`, `/api/v2/`). Parses HTTP
requests and converts to `MwKernel.Context`, then delegates to `MwRouter.Pipeline`.

| Module | Purpose |
|--------|---------|
| `GatewayApi.Endpoint` | Bandit endpoint, plug stack, SSL termination |
| `GatewayApi.Router` | Phoenix router — version-namespaced scopes |
| `GatewayApi.Plugs.RequestId` | Inject `trace_id` into conn assigns |
| `GatewayApi.Plugs.CORS` | CORS headers for browser clients |
| `GatewayApi.Controllers.TransactionController` | CRUD for transaction resources |
| `GatewayApi.Controllers.AccountController` | Account query endpoints |
| `GatewayApi.Controllers.HealthController` | `GET /health/live` and `GET /health/ready` |

---

## gateway_ws

**Plane:** North — Inbound Gateway
**Depends on:** mw_kernel, mw_auth, infra_telemetry
**Port:** 4001 (or same port as gateway_api, different path)

WebSocket gateway. Clients connect with JWT auth on socket handshake. Channels push
real-time events sourced from PubSub (adapter callbacks, pipeline completion events).

| Module | Purpose |
|--------|---------|
| `GatewayWs.Endpoint` | Bandit endpoint |
| `GatewayWs.UserSocket` | Auth on connect — verifies JWT, assigns user |
| `GatewayWs.TransactionChannel` | Subscribe to `"transactions:<id>"` — get live status |
| `GatewayWs.NotificationChannel` | System-wide broadcast — operational alerts |

---

## gateway_web

**Plane:** North — Admin Gateway
**Depends on:** mw_kernel, mw_auth, mw_audit, mw_router, infra_repo, infra_telemetry
**Port:** 4002 (internal only — not exposed externally)

LiveView admin dashboard. Provides real-time operational visibility and control. Protected
by `admin` role.

| Module | Purpose |
|--------|---------|
| `GatewayWeb.DashboardLive` | Pipeline throughput, error rates, latency charts |
| `GatewayWeb.PipelineMonitorLive` | Live message flow visualisation |
| `GatewayWeb.RouteEditorLive` | Edit routing rules — changes propagate instantly |
| `GatewayWeb.AdapterHealthLive` | Circuit breaker status per adapter |
| `GatewayWeb.AuditLogLive` | Searchable, paginated audit trail |
| `GatewayWeb.DlqLive` | Dead letter queue management — re-queue or discard |

---

## gateway_mobile

**Plane:** North — Inbound Gateway
**Depends on:** mw_kernel, mw_router, mw_auth, mw_transform, infra_telemetry
**Port:** 4000 (path `/m/v1/…`) or dedicated port

Mobile-optimised API. Returns compact JSON (no hypermedia). Handles device-specific
push notifications for async result delivery.

| Module | Purpose |
|--------|---------|
| `GatewayMobile.Router` | `/m/v1/…` routes |
| `GatewayMobile.Push.FCM` | Firebase push (Android) via Pigeon |
| `GatewayMobile.Push.APNS` | Apple push (iOS) via Pigeon |
| `GatewayMobile.DeviceRegistry` | Maps user_id → device tokens |

---

## mw_auth

**Plane:** Core — Processing
**Depends on:** mw_kernel, infra_repo, infra_cache

Authentication and authorization. Exposes a single `MwAuth.Plug` that selects strategy
by `Authorization` header prefix. Downstream pipeline sees only `%MwAuth.Identity{}`.

| Module | Purpose |
|--------|---------|
| `MwAuth.Plug` | Detects Bearer/ApiKey, delegates to strategy |
| `MwAuth.JWT` | Joken-based JWT verify, claims extraction |
| `MwAuth.ApiKey` | Key lookup (ETS prefix index), Argon2 verify |
| `MwAuth.RBAC` | `authorize!/2` — raises on insufficient roles |
| `MwAuth.TokenStore` | JTI revocation list — ETS + DB |
| `MwAuth.Identity` | `%{user_id, tenant_id, roles, auth_method}` |

---

## mw_router

**Plane:** Core — Processing
**Depends on:** mw_kernel, mw_auth, mw_transform, mw_audit, infra_cache, infra_telemetry

The orchestration centre. Runs the Plug pipeline and dispatches to adapters.
Owns the ETS routing table and circuit breaker state.

| Module | Purpose |
|--------|---------|
| `MwRouter.Pipeline` | `Plug.Builder` chain — the main processing sequence |
| `MwRouter.RouteTable` | ETS routing table — CRUD, DB sync, PubSub reload |
| `MwRouter.Dispatcher` | Resolves adapter module from route, calls via behaviour |
| `MwRouter.CircuitBreaker` | `:fuse` wrapper — per-adapter open/closed/half-open |
| `MwRouter.RateLimiter` | `ex_rated` token bucket per API key |
| `MwRouter.RouteRule` | Ecto schema for `route_rules` table |

---

## mw_transform

**Plane:** Core — Processing
**Depends on:** mw_kernel

Stateless data transformation. Maps external field names to canonical `MwKernel.Message`
fields and vice versa. Validates against registered schemas.

| Module | Purpose |
|--------|---------|
| `MwTransform.SchemaRegistry` | Loads/caches JSON Schema definitions from DB |
| `MwTransform.Mapper` | Config-driven field mapping rules |
| `MwTransform.Validator` | Ecto changeset + JSON Schema validation |
| `MwTransform.InboundPlug` | Pipeline stage: external → canonical |
| `MwTransform.OutboundPlug` | Pipeline stage: canonical → client format |

---

## mw_audit

**Plane:** Core — Processing
**Depends on:** mw_kernel, infra_repo, infra_telemetry

Every pipeline completion (success or failure) writes a structured audit event.
Events are persisted to DB and broadcast via PubSub for live dashboard display.

| Module | Purpose |
|--------|---------|
| `MwAudit.Event` | Ecto schema for `audit_events` table |
| `MwAudit.Logger` | Async event writer (Task, non-blocking on critical path) |
| `MwAudit.Store` | Ecto persistence + query helpers |
| `MwAudit.Broadcaster` | PubSub fanout to gateway_web live viewer |
| `MwAudit.Plug` | Pipeline stage: writes event at pipeline end |

---

## adapter_banking

**Plane:** South — Adapter
**Depends on:** mw_kernel, infra_telemetry
**Implements:** `MwKernel.Adapter`

Connects to the core banking system. Handles ISO 8583 encoding/decoding or proprietary
REST API (configurable). Manages a Finch connection pool per banking endpoint.

| Module | Purpose |
|--------|---------|
| `AdapterBanking.Client` | Finch pool — sends encoded requests |
| `AdapterBanking.ISO8583` | ISO 8583 message encode/decode |
| `AdapterBanking.Transformer` | Banking response → `MwKernel.Message` |
| `AdapterBanking.Circuit` | Adapter-specific `:fuse` config |
| `AdapterBanking.CallbackHandler` | Receives async settlement callbacks from CBS |

---

## adapter_dw

**Plane:** South — Adapter
**Depends on:** mw_kernel, infra_queue, infra_telemetry
**Implements:** `MwKernel.Adapter`, `MwKernel.StreamingAdapter`

Batch and streaming access to the data warehouse. Bulk inserts via Broadway batcher.
Large result sets returned as `Stream` via GenStage.

| Module | Purpose |
|--------|---------|
| `AdapterDw.Client` | HTTP/JDBC-style DW client (Finch) |
| `AdapterDw.QueryBuilder` | Parameterised query construction |
| `AdapterDw.BatchLoader` | Broadway batcher — bulk insert to DW |
| `AdapterDw.Stream` | GenStage producer for large result streaming |

---

## adapter_http

**Plane:** South — Adapter
**Depends on:** mw_kernel, infra_telemetry
**Implements:** `MwKernel.Adapter`

Generic adapter for internal REST or SOAP services. Configurable per endpoint: auth type,
timeout, retry strategy, response format.

| Module | Purpose |
|--------|---------|
| `AdapterHttp.Client` | Finch-based generic HTTP client |
| `AdapterHttp.Retry` | Exponential backoff with jitter |
| `AdapterHttp.Transformer` | Response normalisation → `MwKernel.Message` |
| `AdapterHttp.SoapClient` | SOAP envelope wrap/unwrap (optional) |

---

## adapter_file

**Plane:** South — Adapter
**Depends on:** mw_kernel, infra_queue, infra_telemetry
**Implements:** `MwKernel.Adapter`

File-based system integration. Polls SFTP directories and processes files via Broadway.
Supports CSV, XML, and ISO fixed-width formats.

| Module | Purpose |
|--------|---------|
| `AdapterFile.SFTPClient` | `ssh_client_key_api` SFTP connect/download/upload |
| `AdapterFile.CsvParser` | NimbleCSV streaming row parser |
| `AdapterFile.XmlParser` | SweetXml XPath-based extraction |
| `AdapterFile.IsoParser` | Fixed-width ISO flat-file parser |
| `AdapterFile.FileWatcher` | GenServer — polls SFTP, emits to Broadway |

---

## infra_repo

**Plane:** Infra — Shared
**Depends on:** mw_kernel

Single `Ecto.Repo` for the entire umbrella. Owns migrations. All other apps reference
`InfraRepo.Repo` as their repo module.

| Module | Purpose |
|--------|---------|
| `InfraRepo.Repo` | `Ecto.Repo` — MySQL via MyXQL |
| `InfraRepo.Migrations.*` | All schema migrations |
| `InfraRepo.Seeds` | Development seed data |

---

## infra_cache

**Plane:** Infra — Shared
**Depends on:** mw_kernel

Two-tier cache. ETS for in-process hot data (routing table, auth key index, config).
Optional Redis layer for cross-node shared state (distributed sessions, rate limit counters).

| Module | Purpose |
|--------|---------|
| `InfraCache.EtsCache` | Named ETS tables, TTL eviction |
| `InfraCache.RedisCache` | Redix client — optional, for multi-node |
| `InfraCache.CacheSupervisor` | Starts and supervises cache processes |

---

## infra_queue

**Plane:** Infra — Shared
**Depends on:** mw_kernel, infra_repo

Reusable Broadway pipeline building blocks. Adapters plug in their producers and batchers.

| Module | Purpose |
|--------|---------|
| `InfraQueue.FilePipeline` | Broadway pipeline for file row ingestion |
| `InfraQueue.CallbackPipeline` | Broadway pipeline for async adapter callbacks |
| `InfraQueue.DeadLetterStore` | Ecto-backed DLQ persistence |
| `InfraQueue.PipelineSupervisor` | Starts/monitors all Broadway pipelines |

---

## infra_telemetry

**Plane:** Infra — Shared
**Depends on:** mw_kernel

Telemetry metric definitions, OTel span helpers, and Prometheus reporter.
Auto-instrumentation libraries attach here at application start.

| Module | Purpose |
|--------|---------|
| `InfraTelemetry.Metrics` | `Telemetry.Metrics` definitions for all apps |
| `InfraTelemetry.Reporter` | `telemetry_metrics_prometheus` reporter |
| `InfraTelemetry.Tracer` | OTel span helper macros |
| `InfraTelemetry.VMPoller` | `telemetry_poller` — BEAM VM stats |
| `InfraTelemetry.Application` | Starts LiveDashboard, poller, OTel SDK |