## Admin Settings Design Document

### Overview

Based on the provided wallet reference architecture and existing implementation, the Admin Settings should manage configuration across three perspectives aligned with the **Management UI** layer:

| Perspective | Scope | Key Configuration Areas |
|------------|-------|------------------------|
| **System** | Platform-wide | Security, Integrations, Storage, Network Services |
| **Customer** | Customer-facing | Enrollment, Limits, Notifications, Privacy, Channels |
| **Merchant** | Merchant-facing | Onboarding, Fees, Settlement, Acceptance Channels |

---

### Proposed Admin Settings Structure

```
/admin/settings
├── /system                 # Platform Configuration
│   ├── /general           # Tenant branding, currency, timezone
│   ├── /security          # Auth policies, MFA, session rules, key rotation
│   ├── /integrations      # Provider adapters, connectors, endpoints
│   ├── /storage           # Data retention, encryption, backup policies
│   ├── /notifications     # Templates, delivery channels, webhooks
│   └── /api               # Rate limits, API keys, SDK config
│
├── /customer              # Customer Policies
│   ├── /enrollment        # Registration, KYC/AML rules, tier requirements
│   ├── /limits            # Transaction limits by tier/type/corridor
│   ├── /fees              # Fee policies, schedules, waivers
│   ├── /channels          # Enabled channels (mobile, web, USSD)
│   ├── /products          # Cards, Loans, Insurance, Rewards config
│   └── /consent           # Privacy policies, data consent requirements
│
└── /merchant              # Merchant Policies
    ├── /onboarding        # Registration rules, KYB requirements
    ├── /fees              # Merchant fees, MDR, settlement charges
    ├── /settlement        # Settlement schedules, cutoff times
    ├── /acceptance        # POS/QR/SoftPOS channel configuration
    ├── /risk              # Merchant risk scoring rules, limits
    └── /compliance        # Merchant compliance requirements
```

---

### Admin Settings Menu Module Design

```elixir
defmodule WalletWeb.Navigation.AdminSettingsMenu do
  @moduledoc """
  Admin settings navigation organized by management perspective.
  """

  @system_settings [
    %{label: "General", path: "/admin/settings/system/general", icon: "hero-cog-6-tooth", action: :manage_system_settings},
    %{label: "Security", path: "/admin/settings/system/security", icon: "hero-shield-check", action: :manage_security_config},
    %{label: "Integrations", path: "/admin/settings/system/integrations", icon: "hero-puzzle-piece", action: :manage_integrations},
    %{label: "Storage & Data", path: "/admin/settings/system/storage", icon: "hero-circle-stack", action: :manage_storage_config},
    %{label: "Notifications", path: "/admin/settings/system/notifications", icon: "hero-bell", action: :manage_notification_templates},
    %{label: "API & SDK", path: "/admin/settings/system/api", icon: "hero-code-bracket", action: :manage_api_config}
  ]

  @customer_settings [
    %{label: "Enrollment", path: "/admin/settings/customer/enrollment", icon: "hero-user-plus", action: :manage_enrollment_config},
    %{label: "Limits", path: "/admin/settings/customer/limits", icon: "hero-adjustments-horizontal", action: :manage_limit_policies},
    %{label: "Fees", path: "/admin/settings/customer/fees", icon: "hero-calculator", action: :manage_fee_policies},
    %{label: "Channels", path: "/admin/settings/customer/channels", icon: "hero-device-phone-mobile", action: :manage_channel_config},
    %{label: "Products", path: "/admin/settings/customer/products", icon: "hero-rectangle-stack", action: :manage_product_config},
    %{label: "Consent & Privacy", path: "/admin/settings/customer/consent", icon: "hero-document-check", action: :manage_consent_config}
  ]

  @merchant_settings [
    %{label: "Onboarding", path: "/admin/settings/merchant/onboarding", icon: "hero-building-storefront", action: :manage_merchant_onboarding_config},
    %{label: "Fees & MDR", path: "/admin/settings/merchant/fees", icon: "hero-banknotes", action: :manage_merchant_fees},
    %{label: "Settlement", path: "/admin/settings/merchant/settlement", icon: "hero-clock", action: :manage_settlement_config},
    %{label: "Acceptance", path: "/admin/settings/merchant/acceptance", icon: "hero-qr-code", action: :manage_acceptance_config},
    %{label: "Risk Rules", path: "/admin/settings/merchant/risk", icon: "hero-exclamation-triangle", action: :manage_merchant_risk_rules},
    %{label: "Compliance", path: "/admin/settings/merchant/compliance", icon: "hero-clipboard-document-check", action: :manage_merchant_compliance}
  ]

  @groups [
    %{id: :system, label: "System Configuration", items: @system_settings},
    %{id: :customer, label: "Customer Policies", items: @customer_settings},
    %{id: :merchant, label: "Merchant Policies", items: @merchant_settings}
  ]

  def groups, do: @groups
  def system_settings, do: @system_settings
  def customer_settings, do: @customer_settings
  def merchant_settings, do: @merchant_settings
end
```

---

### LiveView Components by Perspective

#### System Settings (6 LiveViews)

| LiveView | Route | Description |
|----------|-------|-------------|
| `SystemGeneralSettingsLive` | `/system/general` | Tenant name, logo, default currency, timezone, localization |
| `SystemSecuritySettingsLive` | `/system/security` | Password policies, MFA requirements, session timeout, IP allowlists, key rotation schedules |
| `SystemIntegrationsLive` | `/system/integrations` | Provider configurations (AANI, AFEX, CBS), adapter credentials, connection health |
| `SystemStorageLive` | `/system/storage` | Data retention policies, encryption config, backup schedules, purge controls |
| `SystemNotificationsLive` | `/system/notifications` | Notification templates (email/SMS/push), delivery configurations, webhook management |
| `SystemApiLive` | `/system/api` | API rate limits, SDK configurations, partner API keys, sandbox/production toggle |

#### Customer Policy Settings (6 LiveViews)

| LiveView | Route | Description |
|----------|-------|-------------|
| `CustomerEnrollmentSettingsLive` | `/customer/enrollment` | Registration requirements, KYC tiers, document types, verification rules |
| `CustomerLimitsSettingsLive` | `/customer/limits` | Tier-based limits, corridor limits, velocity rules, dynamic limit adjustments |
| `CustomerFeesSettingsLive` | `/customer/fees` | Fee schedules by transaction type, tier-based discounts, waiver rules |
| `CustomerChannelsSettingsLive` | `/customer/channels` | Enable/disable channels (web, mobile, USSD), channel-specific limits |
| `CustomerProductsSettingsLive` | `/customer/products` | Card products, loan products, insurance products, rewards program config |
| `CustomerConsentSettingsLive` | `/customer/consent` | Privacy policy versions, consent types, GDPR/data rights configuration |

#### Merchant Policy Settings (6 LiveViews)

| LiveView | Route | Description |
|----------|-------|-------------|
| `MerchantOnboardingSettingsLive` | `/merchant/onboarding` | Registration requirements, KYB documents, approval workflows, tier criteria |
| `MerchantFeesSettingsLive` | `/merchant/fees` | MDR rates, settlement fees, chargeback fees, fee tiers |
| `MerchantSettlementSettingsLive` | `/merchant/settlement` | Settlement cycles (T+0/T+1/T+2), cutoff times, holiday handling, auto-settlement triggers |
| `MerchantAcceptanceSettingsLive` | `/merchant/acceptance` | POS/SoftPOS configuration, QR code format, static vs dynamic QR, acceptance limits |
| `MerchantRiskSettingsLive` | `/merchant/risk` | Merchant risk scoring rules, transaction velocity limits, fraud thresholds |
| `MerchantComplianceSettingsLive` | `/merchant/compliance` | Compliance requirements, periodic review cycles, document expiry rules |

---

### Policy Permissions (New Actions)

```elixir
# Add to Policy module

# System Settings
:manage_system_settings
:manage_security_config
:manage_integrations
:manage_storage_config
:manage_notification_templates
:manage_api_config

# Customer Policy Settings  
:manage_enrollment_config
:manage_limit_policies       # Already exists for limits, extend scope
:manage_fee_policies         # Already exists for fees, extend scope
:manage_channel_config
:manage_product_config
:manage_consent_config

# Merchant Policy Settings
:manage_merchant_onboarding_config
:manage_merchant_fees
:manage_settlement_config
:manage_acceptance_config
:manage_merchant_risk_rules
:manage_merchant_compliance
```

**Role Mappings:**
| Role | System | Customer | Merchant |
|------|--------|----------|----------|
| `admin` | All | All | All |
| `ops_supervisor` | View only | Limits/Fees | Fees/Settlement |
| `compliance_officer` | View security | Enrollment/Consent | Onboarding/Compliance |
| `sre` | Security/Storage/API | - | - |

---

### Database Schema Additions

For versioned configuration changes:

```sql
CREATE TABLE admin_configurations (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    namespace VARCHAR(50) NOT NULL,      -- 'system', 'customer', 'merchant'
    category VARCHAR(50) NOT NULL,       -- 'security', 'limits', 'fees', etc.
    config_key VARCHAR(100) NOT NULL,
    config_value JSON NOT NULL,
    version INT NOT NULL DEFAULT 1,
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    effective_from DATETIME NOT NULL,
    effective_to DATETIME,
    created_by VARCHAR(50) NOT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY unique_active_config (namespace, category, config_key, is_active, effective_from),
    INDEX idx_namespace_category (namespace, category),
    INDEX idx_effective_dates (effective_from, effective_to)
);

CREATE TABLE admin_configuration_audit (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    configuration_id BIGINT NOT NULL,
    action ENUM('create', 'update', 'activate', 'deactivate') NOT NULL,
    previous_value JSON,
    new_value JSON,
    changed_by VARCHAR(50) NOT NULL,
    change_reason TEXT,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (configuration_id) REFERENCES admin_configurations(id),
    INDEX idx_config_id (configuration_id),
    INDEX idx_changed_by (changed_by)
);
```

---

### Alignment with Reference Architecture

Your diagrams show several layers that map to admin settings:

| Architecture Layer | Admin Settings Mapping |
|-------------------|----------------------|
| **Admin UI → Enrollment** | Customer Enrollment Settings |
| **Admin UI → Management UI** | All Settings dashboards |
| **Wallet Services → Consents/Profiles** | Customer Consent Settings |
| **Wallet Services → Notifications** | System Notifications Settings |
| **Wallet Services → Keys Management** | System Security Settings (key rotation) |
| **Policy Engine → Wallet Owner Rules** | Customer Limits/Fees Settings |
| **Policy Engine → Relying Party Rules** | Merchant Acceptance Settings |
| **Policy Engine → Trust Framework Rules** | Merchant Compliance Settings |
| **Network Services → Connectors** | System Integrations Settings |
| **Secure Storage → Key Storage** | System Storage Settings |

---

### Implementation Priority

**Sprint 1 (High Priority):**
1. `AdminSettingsMenu` module
2. Admin Settings Dashboard (`/admin/settings`)
3. `SystemSecuritySettingsLive` (aligns with Phase 14 Track E)
4. `CustomerLimitsSettingsLive` (dynamic rules - Phase 14 Track A)
5. `MerchantOnboardingSettingsLive` (Phase 14 Track B)

**Sprint 2 (Medium Priority):**
6. `SystemIntegrationsLive`
7. `CustomerFeesSettingsLive` / `MerchantFeesSettingsLive`
8. `MerchantSettlementSettingsLive`
9. `SystemNotificationsLive`

**Sprint 3 (Lower Priority):**
10. Remaining LiveViews
11. Configuration versioning and audit UI
12. Bulk import/export functionality

---