# Technology Stack

## Runtime

| Layer | Technology | Version | Notes |
|-------|-----------|---------|-------|
| Language | Elixir | ~> 1.17 | Pattern matching, OTP supervision |
| Runtime | Erlang/OTP | ~> 27 | BEAM VM, actor model |
| Framework | Phoenix | ~> 1.7 | Umbrella, LiveView, Channels |
| HTTP Server | Bandit | ~> 1.5 | Already in base; pure Elixir |

---

## Library Choices by Concern

### HTTP & Networking
| Library | Use | Rationale |
|---------|-----|-----------|
| `bandit` | HTTP server (all gateways) | Pure Elixir, excellent HTTP/2, built-in telemetry |
| `finch` | HTTP client (adapters) | Connection pools, native telemetry, used by Phoenix |
| `websock_adapter` | WebSocket (via Bandit) | Handles protocol upgrade |

### Authentication
| Library | Use | Rationale |
|---------|-----|-----------|
| `joken` | JWT sign/verify | Pluggable signers (HS256, RS256, EdDSA), Elixir-native |
| `argon2_elixir` | API key hashing | Memory-hard, recommended for stored secrets |
| `plug` | Auth middleware | Standard Phoenix plug chain |

### Data & Persistence
| Library | Use | Rationale |
|---------|-----|-----------|
| `ecto_sql` | ORM / query builder | Standard Phoenix, composable queries |
| `myxql` | MySQL driver | Native Elixir, maintained by Plataformatec |
| `nimble_csv` | CSV streaming parse | Zero-copy, NimbleParsec-based |
| `sweet_xml` | XML / XPath parsing | Streaming, low memory for large XML files |
| `jason` | JSON encode/decode | Fast, standard in Phoenix stack |

### Rate Limiting & Circuit Breaking
| Library | Use | Rationale |
|---------|-----|-----------|
| `ex_rated` | Token-bucket rate limiter | ETS-backed, per-key, no external dependency |
| `:fuse` | Circuit breaker | Erlang library, battle-tested at Erlang ecosystem scale |

### Async & Back-pressure
| Library | Use | Rationale |
|---------|-----|-----------|
| `broadway` | Producer-consumer pipelines | Back-pressure, DLQ, metrics, Ack built in |
| `gen_stage` | Streaming source | Used by Broadway producers; fine-grained flow control |

### Observability
| Library | Use | Rationale |
|---------|-----|-----------|
| `telemetry` | Event emission (built-in) | Zero-overhead, hooks for all Phoenix/Ecto events |
| `telemetry_metrics` | Metric definitions | Standard Phoenix instrumentation |
| `telemetry_poller` | VM metrics polling | Memory, GC, scheduler stats |
| `opentelemetry_api` | OTel span API | CNCF standard; vendor-neutral |
| `opentelemetry_exporter` | OTel OTLP export | Export to Jaeger, Tempo, Honeycomb |
| `opentelemetry_phoenix` | Auto-instrument Phoenix | Automatic span per request |
| `opentelemetry_ecto` | Auto-instrument Ecto | Automatic span per DB query |
| `telemetry_metrics_prometheus` | Prometheus scrape endpoint | `/metrics` for Prometheus |
| `phoenix_live_dashboard` | Dev/ops dashboard | Already in base; free admin overview |

### Clustering
| Library | Use | Rationale |
|---------|-----|-----------|
| `libcluster` | Node discovery | Kubernetes DNS, gossip, epmd strategies |
| `horde` | Distributed process registry | ETS replication across cluster nodes |
| `dns_cluster` | K8s DNS cluster | Already in base Phoenix app |

### Email (operational alerts)
| Library | Use | Rationale |
|---------|-----|-----------|
| `swoosh` | Email delivery | Already in base; multi-adapter |
| `finch` | HTTP backend for Swoosh | Shared with adapter HTTP client |

### Validation & Schemas
| Library | Use | Rationale |
|---------|-----|-----------|
| `ecto` | Changeset validation | Consistent with DB layer |
| `ex_json_schema` | JSON Schema validation | Standards-based, schema registry |

### Push Notifications (Mobile)
| Library | Use | Rationale |
|---------|-----|-----------|
| `pigeon` | FCM + APNS push | Erlang/Elixir native, well-maintained |

### Utilities
| Library | Use | Rationale |
|---------|-----|-----------|
| `gettext` | Internationalisation | Already in base |
| `credo` | Static analysis | Style enforcement, CI gate |
| `dialyxir` | Type checking | Dialyzer wrapper, catches contract violations |
| `excoveralls` | Test coverage | Coverage report in CI |

---

## Infrastructure Dependencies

| Service | Purpose | Notes |
|---------|---------|-------|
| MySQL 8.x | Primary datastore | Audit events, routing rules, API keys, DLQ |
| Redis (optional) | L2 cache / distributed sessions | Only needed for multi-node; ETS sufficient for single node |
| SFTP Server | File ingestion source | External; `adapter_file` connects outbound |
| Jaeger / Grafana Tempo | OTel trace storage | Receive OTLP from `infra_telemetry` |
| Prometheus + Grafana | Metrics & dashboards | Scrape `/metrics` from `infra_telemetry` |
| FCM / APNS | Mobile push | Called from `gateway_mobile` via `pigeon` |

---

## Configuration Strategy

### Compile-time config (`config/*.exs`)
- Endpoint ports, plugs, router modules
- Telemetry metric definitions
- Ecto pool sizes

### Runtime config (`config/runtime.exs`)
- Database credentials (env vars)
- JWT signing keys
- Adapter endpoints and API keys
- Feature flags

### Dynamic config (DB → ETS)
- Routing rules (editable via admin UI without restart)
- Rate limit thresholds per tenant
- Adapter timeout overrides
- Schema mapping rules

---

## mix.exs Umbrella Dependencies Matrix

```
              kernel repo cache queue telemetry auth transform audit router banking dw http file
gateway_api      ✓          ✓                    ✓✓             ✓      ✓
gateway_ws       ✓          ✓          ✓          ✓                     ✓
gateway_web      ✓    ✓     ✓          ✓          ✓             ✓      ✓       ✓
gateway_mobile   ✓          ✓          ✓          ✓      ✓              ✓
mw_auth          ✓    ✓     ✓          ✓
mw_transform     ✓
mw_audit         ✓    ✓                           ✓
mw_router        ✓          ✓          ✓          ✓      ✓   ✓    ✓           (adapters via behaviour)
adapter_banking  ✓                                ✓
adapter_dw       ✓                     ✓          ✓
adapter_http     ✓                                ✓
adapter_file     ✓                     ✓          ✓
infra_repo       ✓
infra_cache      ✓
infra_queue      ✓    ✓
infra_telemetry  ✓
```