# Umbrella Directory Structure Full layout of the `mw_core` Phoenix Umbrella application. ``` mw_core/ ← Umbrella root ├── mix.exs ← Umbrella mix.exs (no :mod, just :apps_path) ├── config/ │ ├── config.exs ← Shared base config │ ├── dev.exs │ ├── test.exs │ ├── prod.exs │ └── runtime.exs ← Runtime secrets (env vars, Vault) │ ├── docs/ ← Architecture docs (this folder) │ └── apps/ │ ├── mw_kernel/ ← [CORE] Shared contracts — no dependencies on other apps │ ├── mix.exs │ └── lib/ │ └── mw_kernel/ │ ├── message.ex # Canonical message struct (request/response envelope) │ ├── context.ex # Request context: trace_id, tenant_id, user, timestamp │ ├── error.ex # Unified error types and codes │ └── behaviours/ │ ├── adapter.ex # @callback connect/send/health_check for south-side │ └── gateway.ex # @callback ingest/respond for north-side │ ├── infra_repo/ ← [INFRA] Database access — depends on: mw_kernel │ ├── mix.exs │ ├── lib/ │ │ └── infra_repo/ │ │ ├── repo.ex # Ecto.Repo (MySQL via MyXQL) │ │ └── schemas/ # Shared Ecto schemas (audit_events, route_rules, api_keys) │ └── priv/ │ └── repo/ │ ├── migrations/ │ └── seeds.exs │ ├── infra_cache/ ← [INFRA] Caching layer — depends on: mw_kernel │ ├── mix.exs │ └── lib/ │ └── infra_cache/ │ ├── ets_cache.ex # ETS-backed hot cache (routing tables, config) │ └── redis_cache.ex # Optional Redix L2 cache (distributed sessions) │ ├── infra_queue/ ← [INFRA] Async pipelines — depends on: mw_kernel, infra_repo │ ├── mix.exs │ └── lib/ │ └── infra_queue/ │ ├── producer.ex # GenStage producer │ ├── consumer.ex # Broadway consumer with DLQ │ ├── pipeline_supervisor.ex │ └── pipelines/ │ ├── file_pipeline.ex # Broadway pipeline for file ingestion │ └── dw_pipeline.ex # Broadway pipeline for DW batch load │ ├── infra_telemetry/ ← [INFRA] Observability — depends on: mw_kernel │ ├── mix.exs │ └── lib/ │ └── infra_telemetry/ │ ├── metrics.ex # Telemetry.Metrics definitions │ ├── reporter.ex # Prometheus/StatsD reporter │ └── tracer.ex # OpenTelemetry span helpers │ ├── mw_auth/ ← [CORE] Authentication & authorization │ ├── mix.exs # depends on: mw_kernel, infra_repo, infra_cache │ └── lib/ │ └── mw_auth/ │ ├── jwt.ex # Joken JWT sign/verify │ ├── api_key.ex # HMAC-signed API key, Argon2 hash storage │ ├── rbac.ex # Role-based access: admin / operator / readonly │ ├── plug.ex # Plug: detects Bearer vs ApiKey, sets context │ └── token_store.ex # Token revocation list (ETS + DB) │ ├── mw_transform/ ← [CORE] Data mapping & validation │ ├── mix.exs # depends on: mw_kernel │ └── lib/ │ └── mw_transform/ │ ├── schema_registry.ex # JSON Schema registry (config-driven) │ ├── mapper.ex # Field mapping rules (DB-stored, ETS-cached) │ └── validator.ex # Ecto-based changeset validation │ ├── mw_audit/ ← [CORE] Compliance audit logging │ ├── mix.exs # depends on: mw_kernel, infra_repo, infra_telemetry │ └── lib/ │ └── mw_audit/ │ ├── event.ex # Audit event schema │ ├── logger.ex # Structured async audit writer │ ├── store.ex # Ecto-backed persistence │ └── broadcaster.ex # PubSub fanout for live audit feed │ ├── mw_router/ ← [CORE] Pipeline orchestration & routing │ ├── mix.exs # depends on: mw_kernel, mw_auth, mw_transform, │ └── lib/ # mw_audit, infra_cache, infra_telemetry │ └── mw_router/ │ ├── pipeline.ex # Plug.Builder chain: auth→rate→transform→route→audit │ ├── route_table.ex # ETS routing table: message_type → adapter module │ ├── dispatcher.ex # Calls the resolved adapter via behaviour │ ├── circuit_breaker.ex # :fuse-based per-adapter circuit breaker │ └── rate_limiter.ex # ex_rated token-bucket per API key / IP │ ├── adapter_banking/ ← [SOUTH] Core banking adapter │ ├── mix.exs # depends on: mw_kernel, infra_telemetry │ └── lib/ │ └── adapter_banking/ │ ├── client.ex # Finch HTTP connection pool to core banking │ ├── iso8583.ex # ISO 8583 message encode / decode │ ├── transformer.ex # Banking response → MwKernel.Message │ └── circuit.ex # Adapter-specific breaker config │ ├── adapter_dw/ ← [SOUTH] Data warehouse adapter │ ├── mix.exs # depends on: mw_kernel, infra_queue, infra_telemetry │ └── lib/ │ └── adapter_dw/ │ ├── client.ex # DW HTTP/JDBC-style client │ ├── query_builder.ex # Parameterised query construction │ ├── batch_loader.ex # Broadway-based bulk insert/export │ └── stream.ex # GenStage streaming for large result sets │ ├── adapter_http/ ← [SOUTH] Generic internal REST / SOAP adapter │ ├── mix.exs # depends on: mw_kernel, infra_telemetry │ └── lib/ │ └── adapter_http/ │ ├── client.ex # Finch-based generic HTTP client │ ├── retry.ex # Exponential backoff with jitter │ └── transformer.ex # Response normalisation to MwKernel.Message │ ├── adapter_file/ ← [SOUTH] File-based adapter │ ├── mix.exs # depends on: mw_kernel, infra_queue, infra_telemetry │ └── lib/ │ └── adapter_file/ │ ├── sftp_client.ex # ssh_client_key_api SFTP connection │ ├── csv_parser.ex # NimbleCSV streaming parse │ ├── xml_parser.ex # SweetXml XPath extraction │ ├── iso_parser.ex # ISO flat-file format (fixed-width) │ └── file_watcher.ex # GenServer: poll SFTP dir or local watch │ ├── gateway_api/ ← [NORTH] Public REST/JSON API │ ├── mix.exs # depends on: mw_kernel, mw_router, mw_auth, │ └── lib/ # infra_telemetry │ ├── gateway_api_web/ │ │ ├── endpoint.ex # Bandit endpoint, plug stack │ │ ├── router.ex # /api/v1/… /api/v2/… │ │ ├── controllers/ │ │ │ ├── transaction_controller.ex │ │ │ ├── account_controller.ex │ │ │ └── health_controller.ex │ │ └── plugs/ │ │ ├── request_id.ex # Inject trace_id into conn │ │ └── cors.ex │ └── gateway_api/ │ └── application.ex │ ├── gateway_ws/ ← [NORTH] WebSocket / Phoenix Channels │ ├── mix.exs # depends on: mw_kernel, mw_auth, infra_telemetry │ └── lib/ │ ├── gateway_ws_web/ │ │ ├── socket.ex # UserSocket, authenticate on connect │ │ ├── endpoint.ex │ │ └── channels/ │ │ ├── transaction_channel.ex # Subscribe to tx status │ │ └── notification_channel.ex # System-wide broadcast │ └── gateway_ws/ │ └── application.ex │ ├── gateway_web/ ← [NORTH] LiveView admin dashboard │ ├── mix.exs # depends on: mw_kernel, mw_auth, mw_audit, │ └── lib/ # mw_router, infra_telemetry, infra_repo │ ├── gateway_web_web/ │ │ ├── endpoint.ex │ │ ├── router.ex # /admin/… │ │ ├── live/ │ │ │ ├── dashboard_live.ex # Pipeline throughput, error rates │ │ │ ├── pipeline_monitor_live.ex # Live message flow │ │ │ ├── route_editor_live.ex # Edit routing rules in real time │ │ │ ├── adapter_health_live.ex # Circuit breaker status per adapter │ │ │ └── audit_log_live.ex # Searchable audit trail │ │ └── components/ │ └── gateway_web/ │ └── application.ex │ └── gateway_mobile/ ← [NORTH] Mobile-optimised REST API ├── mix.exs # depends on: mw_kernel, mw_router, mw_auth, └── lib/ # mw_transform, infra_telemetry ├── gateway_mobile_web/ │ ├── endpoint.ex │ ├── router.ex # /m/v1/… (compact responses) │ ├── controllers/ │ └── push/ │ ├── fcm.ex # Firebase Cloud Messaging (Android) │ └── apns.ex # Apple Push Notification Service (iOS) └── gateway_mobile/ └── application.ex ``` --- ## Dependency Graph ``` mw_kernel ← no internal dependencies (foundation) │ ├── infra_repo ├── infra_cache ├── infra_queue ← infra_repo └── infra_telemetry │ ├── mw_auth ← infra_repo, infra_cache ├── mw_transform ├── mw_audit ← infra_repo, infra_telemetry │ ├── adapter_banking ← infra_telemetry ├── adapter_dw ← infra_queue, infra_telemetry ├── adapter_http ← infra_telemetry ├── adapter_file ← infra_queue, infra_telemetry │ └── mw_router ← mw_auth, mw_transform, mw_audit, infra_cache, infra_telemetry, adapter_* (via behaviour dispatch) │ ├── gateway_api ├── gateway_ws ├── gateway_mobile └── gateway_web ← mw_audit, mw_router, infra_repo ``` ## Rules - `mw_kernel` must never depend on any other internal app. - `infra_*` apps must never depend on `gateway_*`, `mw_*`, or `adapter_*` apps. - `adapter_*` apps must never depend on `gateway_*` or other `adapter_*` apps. - `gateway_*` apps must never call `adapter_*` directly — always via `mw_router`.