elixir-architect

## Architecture Overview for `OrderFlow` (Elixir/Phoenix)

### High-Level Architecture
```mermaid
graph TD
    A[Client] -->|HTTP/GraphQL| B[Phoenix Load Balancer]
    B --> C[Phoenix App 1]
    B --> D[Phoenix App 2]
    C --> E[PostgreSQL Primary]
    D --> F[PostgreSQL Replica]
    C --> G[Redis Cluster]
    D --> G
    G --> H[RabbitMQ]
    H --> I[Order Processing Workers]
    I --> J[S3 Media Storage]
```

### ADRs
**ADR-001: Database Layer**
- Decision: Use Ash Framework with PostgreSQL for domain modeling.
- Rationale: Ash provides domain-driven design patterns and reduces boilerplate. PostgreSQL offers ACID compliance and horizontal scaling via read replicas.
- Trade-offs: Higher operational overhead than DynamoDB for simple CRUD. Mitigation: Use AshPostgres for schema management.

**ADR-002: Caching Strategy**
- Decision: Redis Cluster with write-through caching for hot paths (e.g., product catalog).
- Rationale: Redis offers low-latency reads and pub/sub for real-time updates. Cluster mode ensures high availability.
- Trade-offs: Cache invalidation complexity. Mitigation: Use Ash’s `cache_ttl` and event-driven invalidation via Phoenix PubSub.

### Deployment Runbook
**Docker Setup**
```dockerfile
FROM elixir:1.16-alpine AS builder
WORKDIR /app
RUN mix local.hex --force && mix local.rebar --force
COPY . .
RUN mix deps.get && mix release --overwrite

FROM alpine:latest
RUN apk add --no-cache libstdc++ postgresql-client
COPY --from=builder /app/_build/prod/rel/order_flow .
COPY config/prod.secret.exs .
CMD ["./bin/order_flow", "start"]
```

**Kubernetes Manifest (excerpt)**
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-flow-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: order-flow
  template:
    spec:
      containers:
      - name: app
        image: ghcr.io/yourorg/order_flow:1.0.0
        ports:
        - containerPort: 4000
        envFrom:
        - secretRef:
            name: order-flow-secrets
        resources:
          requests:
            cpu: "500m"
            memory: "1Gi"
          limits:
            cpu: "1"
            memory: "2Gi"
```

### Monitoring & Observability
- **Metrics**: Track Phoenix endpoint latency, Ecto query performance, and Ash domain event throughput via Prometheus exporter.
- **Alerts**: Configure Grafana dashboards for:
  - 95th percentile API latency > 500ms
  - Database connection pool exhaustion
  - Redis memory usage > 80% of cluster capacity
- **Logs**: Structured logging with `logger_json` and Loki for aggregation.

### Failure Mode Analysis
1. **PostgreSQL Primary Failure**: Failover to replica via Patroni (handled by Kubernetes operator). Expected RTO: < 30s.
2. **Redis Cluster Split-Brain**: Use Redis Sentinel for automatic failover. Monitor with `redis-cli --cluster check`.
3. **Phoenix App OOM**: Kubernetes HPA scales pods based on memory usage. Pods restart automatically.

**Next Steps**:
1. Review ADRs with the team and adjust based on feedback.
2. Implement CI/CD pipeline in GitHub Actions (see `.github/workflows/deploy.yml`).
3. Set up staging environment with synthetic load testing (e.g., `benchee` for GraphQL queries).

---