feat: Production-ready outbound remittance platform — DB wiring, lifecycle worker, Go/Rust bridges

.agents/skills/testing-navigation/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: testing-payment-switch-navigation
+description: Test PWA sidebar, search, breadcrumbs, admin dashboard navigation, and sidebar collapse/expand. Use when verifying navigation UI changes across client and admin apps.
+---
+
+# Testing Payment Switch Navigation
+
+## Prerequisites
+
+- Node.js installed
+- Repo cloned at the working directory
+
+## Devin Secrets Needed
+
+None — the admin dashboard uses demo/demo credentials in development mode.
+
+## Starting Dev Servers
+
+### PWA Client (Vite)
+```bash
+cd <repo-root>
+npx vite
+```
+- Default port: 5173 (may shift to 5174+ if port is in use)
+- Check terminal output for actual port
+
+### Admin Dashboard (Next.js)
+```bash
+cd <repo-root>/admin-dashboard
+npx next dev -p 3002
+```
+- Use port 3002 to avoid conflicts with other services on 3000/3001
+- If port is in use, kill old processes: `fuser -k 3002/tcp`
+
+## What Can Be Tested in Browser
+
+| Component | URL | Notes |
+|-----------|-----|-------|
+| PWA AppShell sidebar | `http://localhost:5173/dashboard` | Global sidebar on non-module pages |
+| PWA module pages | `http://localhost:5173/domestic-payments` | Should show own ModuleLayout, NOT AppShell |
+| PWA breadcrumbs | `http://localhost:5173/settings/2fa` | Shows Home > Settings > 2fa |
+| PWA search | Search input in sidebar | Type to filter nav items |
+| PWA collapse | Collapse button or Ctrl+B | Icon-only rail mode |
+| Admin sidebar | `http://localhost:3002` | Login: demo/demo |
+| Admin search | Search input above nav | Filters 47+ items |
+
+## What CANNOT Be Runtime Tested
+
+- **React Native mobile app** — requires Expo/simulator (not available on standard VMs)
+- **Flutter mobile app** — requires Flutter SDK/emulator (not available on standard VMs)
+- These should be code-reviewed only
+
+## Test Procedure
+
+### 1. PWA AppShell Sidebar
+- Navigate to `/dashboard`
+- Verify sidebar visible with "Payment Switch" logo, 25+ nav items in 6 sections
+- Verify "Dashboard" is highlighted (blue background)
+- Verify footer shows keyboard shortcut hints
+
+### 2. Module Page Isolation
+- Navigate to `/domestic-payments` (or any module route)
+- Verify AppShell sidebar is NOT shown
+- Verify page's own ModuleLayout sidebar is shown instead
+- Verify breadcrumbs still appear above content
+
+### 3. Sidebar Search
+- On `/dashboard`, click the search input (or try Ctrl+K)
+- Type "settlement" — should filter to 1 item
+- Verify X clear button appears
+- Clear and verify all items return
+
+### 4. Breadcrumbs
+- Navigate to `/settings/2fa`
+- Verify breadcrumb: Home > Settings > 2fa
+- Verify "Home" links to `/`, "Settings" links to `/settings`
+
+### 5. Admin Sidebar Search
+- Navigate to admin dashboard, log in with demo/demo
+- Search "fraud" — should show "Fraud & Risk"
+- Search nonsense text — should show "No items match" message
+
+### 6. Sidebar Collapse/Expand
+- On `/dashboard`, click the collapse button (or Ctrl+B)
+- Verify sidebar collapses to icon-only rail
+- Verify tooltip titles appear on each icon
+- Click expand (or Ctrl+B again) — verify full sidebar returns
+
+## Known Issues & Workarounds
+
+- **Browser automation `press_key` for Ctrl+B/Ctrl+K** might be intermittent. Use the button/input click as fallback — they wire to the same handlers.
+- **Port conflicts**: Vite may shift ports if 5173 is busy. Always check terminal output for actual port.
+- **Admin port**: Use explicit `-p 3002` flag to avoid conflicts with other Next.js or Node processes.
+- **Demo login**: Only works when `NODE_ENV !== 'production'`. The admin page auto-generates demo credentials in dev mode.
+- **Module routes** that have their own sidebar: `/outbound-remittance`, `/inbound-remittance`, `/domestic-payments`, `/card-processing`, `/government-payments`, `/trade-payments`, `/open-banking`, `/middleware`. AppShell correctly excludes these.
+
+## Tips
+
+- Maximize browser window before recording for clearer screenshots
+- Save screenshots to a dedicated directory (e.g., `~/screenshots/`) with descriptive names
+- When testing search, verify both positive matches AND the "no results" empty state
+- The sidebar has ~25 items in PWA and 47+ in admin — scrolling may be needed to see all sections

.env.example

@@ -0,0 +1,184 @@
+# Payment Switch Platform - Environment Configuration
+# Copy this file to .env and update the values for your environment
+
+# =============================================================================
+# DATABASE CONFIGURATION (PostgreSQL)
+# =============================================================================
+DATABASE_URL=postgresql://payment_user:payment_pass_2024@localhost:5432/payment_switch_portal
+
+# =============================================================================
+# REDIS CONFIGURATION
+# =============================================================================
+REDIS_URL=redis://localhost:6379
+
+# =============================================================================
+# APPLICATION CONFIGURATION
+# =============================================================================
+NODE_ENV=development
+PORT=3000
+VITE_APP_ID=payment-switch
+VITE_APP_TITLE=Payment Switch
+
+# Security: Dev auth bypass (MUST be false/unset in production)
+ENABLE_DEV_AUTH=true
+# Graceful shutdown timeout in ms (default: 15000)
+SHUTDOWN_TIMEOUT_MS=15000
+# Infrastructure client timeout and retry config
+INFRA_TIMEOUT_MS=3000
+INFRA_MAX_RETRIES=2
+# Trust proxy setting for reverse proxy (nginx, APISIX, etc.)
+TRUST_PROXY=1
+
+# =============================================================================
+# KEYCLOAK AUTHENTICATION (OIDC)
+# =============================================================================
+# Keycloak server URL (internal Docker network or external URL)
+KEYCLOAK_URL=http://keycloak:8080
+# Keycloak realm name
+KEYCLOAK_REALM=payment-switch
+# Client ID for the portal application (public client)
+KEYCLOAK_CLIENT_ID=payment-switch-portal
+# Client secret (for confidential clients only)
+KEYCLOAK_CLIENT_SECRET=
+# Admin credentials for Keycloak management
+KEYCLOAK_ADMIN=admin
+KEYCLOAK_ADMIN_PASSWORD=admin_change_me
+
+# =============================================================================
+# APISIX API GATEWAY
+# =============================================================================
+# APISIX Admin API URL
+APISIX_ADMIN_URL=http://apisix:9180
+# APISIX Admin API Key (change in production)
+APISIX_ADMIN_KEY=edd1c9f034335f136f87ad84b625c8f1
+# APISIX client credentials for Keycloak
+KEYCLOAK_APISIX_CLIENT_SECRET=
+
+# =============================================================================
+# PERMIFY AUTHORIZATION (RBAC/ABAC)
+# =============================================================================
+# Permify gRPC endpoint
+PERMIFY_URL=http://permify:3476
+# Permify HTTP endpoint
+PERMIFY_HTTP_URL=http://permify:3478
+# Permify tenant ID (default: t1)
+PERMIFY_TENANT_ID=t1
+
+# =============================================================================
+# OPENAPPSEC WAF
+# =============================================================================
+# OpenAppSec WAF proxy URL
+OPENAPPSEC_URL=http://openappsec:8080
+# Enable learning mode (set to false in production after initial learning)
+OPENAPPSEC_LEARNING_MODE=true
+
+# =============================================================================
+# JWT CONFIGURATION
+# =============================================================================
+# Secret for signing JWT tokens (generate with: openssl rand -base64 32)
+JWT_SECRET=your-super-secret-jwt-key-change-in-production
+
+# =============================================================================
+# EXTERNAL SERVICES (Optional)
+# =============================================================================
+# SendGrid for email notifications
+SENDGRID_API_KEY=
+
+# Twilio for SMS notifications
+TWILIO_ACCOUNT_SID=
+TWILIO_AUTH_TOKEN=
+TWILIO_PHONE_NUMBER=
+
+# Smile Identity for KYC verification
+SMILE_IDENTITY_API_KEY=
+SMILE_IDENTITY_PARTNER_ID=
+
+# NIBSS for Nigerian banking integration
+NIBSS_API_KEY=
+NIBSS_SECRET_KEY=
+
+# =============================================================================
+# MOJALOOP INTEGRATION
+# =============================================================================
+MOJALOOP_HUB_URL=http://mojaloop-hub:4000
+MOJALOOP_PARTICIPANT_ID=payment-switch
+MOJALOOP_CENTRAL_LEDGER_URL=http://central-ledger:3001
+MOJALOOP_ALS_URL=http://account-lookup-service:4002
+MOJALOOP_QUOTING_URL=http://quoting-service:3002
+MOJALOOP_TRANSFER_URL=http://ml-api-adapter:3000
+
+# =============================================================================
+# TIGERBEETLE LEDGER
+# =============================================================================
+TIGERBEETLE_ADDRESSES=tigerbeetle:3000
+TIGERBEETLE_CLUSTER_ID=0
+TIGERBEETLE_HTTP_URL=http://tigerbeetle-gateway:3000
+
+# =============================================================================
+# KAFKA EVENT STREAMING
+# =============================================================================
+KAFKA_BROKERS=kafka:9092
+KAFKA_CLIENT_ID=payment-switch
+KAFKA_REST_URL=http://kafka-rest:8082
+SCHEMA_REGISTRY_URL=http://schema-registry:8081
+
+# =============================================================================
+# OPENSEARCH
+# =============================================================================
+OPENSEARCH_URL=http://opensearch:9200
+OPENSEARCH_USERNAME=admin
+OPENSEARCH_PASSWORD=
+
+# =============================================================================
+# FLUVIO STREAMING
+# =============================================================================
+FLUVIO_URL=http://fluvio:9003
+
+# =============================================================================
+# DAPR SIDECAR
+# =============================================================================
+DAPR_HTTP_PORT=3500
+DAPR_GRPC_PORT=50001
+
+# =============================================================================
+# OBJECT STORAGE (RustFS/MinIO compatible)
+# =============================================================================
+S3_ENDPOINT=http://rustfs:9000
+S3_ACCESS_KEY=minioadmin
+S3_SECRET_KEY=minioadmin
+S3_BUCKET=payment-switch
+
+# =============================================================================
+# OBSERVABILITY
+# =============================================================================
+# Prometheus metrics endpoint
+PROMETHEUS_ENABLED=true
+PROMETHEUS_PORT=9090
+
+# Grafana dashboard
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=admin_change_me
+
+# OpenTelemetry tracing
+OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318
+OTEL_SERVICE_NAME=payment-switch
+
+# =============================================================================
+# OLLAMA (Local LLM for VLM/OCR)
+# =============================================================================
+OLLAMA_URL=http://ollama:11434
+OLLAMA_MODEL=llava
+
+# =============================================================================
+# SECURITY
+# =============================================================================
+# Enable CORS (comma-separated origins)
+CORS_ORIGINS=http://localhost:3000,http://localhost:3001
+
+# Rate limiting
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_MAX_REQUESTS=100
+
+# Session configuration
+SESSION_COOKIE_SECURE=false
+SESSION_COOKIE_SAME_SITE=lax