raulcnadal/applivery-esim-manager repository overview

⁠📡 Applivery eSIM Manager

⁠📋 Overview & Architecture

Applivery eSIM Manager is a full-stack UEM companion app bridging Applivery⁠ mobile device management with EMNify⁠ eSIM connectivity.

• Inventory & Fleet Control: View Applivery-managed devices enriched with EID/ICCID data. Track profiles, assignments, and activation codes.
• Provisioning Engine: Deploy eSIM profiles to iOS/Android via MDM commands or Agent push notifications.
• EMNify Sync: Manage Connected Devices (endpoints), toggle states (activate/suspend), and sync device Smart Attributes.
• Secure API Pipeline: All external API calls run server-side; credentials are never exposed to the browser.

Next.js 16 (Server Pages / Actions / API Routes) ──► Prisma 7 ORM ──► PostgreSQL 15+
   ├── Server-side Outbound Only ──► Applivery API v1 (api.applivery.io)
   └── Server-side Outbound Only ──► EMNify API v1 (cdn.emnify.net)

⁠⚙️ Prerequisites & Environment Variables

DATABASE_URL=postgresql://user:password@host:5432/esim_manager
SESSION_SECRET=change_me_to_a_long_random_secret

# Optional Configuration
APPLIVERY_TOKEN=optional_fallback_service_account_token # Used only for SSR passes without active session
EMNIFY_APP_TOKEN=your_emnify_application_token # Can also be configured inside Settings UI

⁠🚀 Deployment

⁠Docker Run

docker run -d --name applivery-esim-manager --restart unless-stopped -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:pass@host:5432/esim_manager" \
  -e SESSION_SECRET="your_long_random_secret" \
  raulcnadal/applivery-esim-manager:latest

Note: Prisma migrations execute automatically on initial container startup.

⁠Docker Compose

version: '3.9'
services:
  esim-manager:
    image: raulcnadal/applivery-esim-manager:latest
    restart: unless-stopped
    ports: ["3000:3000"]
    environment:
      DATABASE_URL: postgresql://esim:esim_pass@db:5432/esim_manager
      SESSION_SECRET: ${SESSION_SECRET}
    depends_on:
      db: { condition: service_healthy }
    networks: [esim-net]
  db:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: esim_manager
      POSTGRES_USER: esim
      POSTGRES_PASSWORD: esim_pass
    volumes: [postgres_data:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U esim -d esim_manager"]
      interval: 10s; timeout: 5s; retries: 5
    networks: [esim-net]
volumes: { postgres_data: }
networks: { esim-net: }

Health Check Endpoint: GET /api/auth/session-check (Returns 200 OK with { authenticated: true/false }).

⁠🛠️ Configuration & Initial Setup

1. First Login: Route to http://localhost:3000 and use your standard Applivery Console credentials. Local cookie sessions expire after a 60-minute idle timeout. Multi-workspace selectors populate in the top right.
2. Smart Attributes Setup: Navigate to Settings → Applivery API and provide your IDs (Applivery Console → Automation → Smart Attributes):

• EID Smart Attribute ID: MongoDB ObjectId storing device eUICC chip identifiers.
• ICCID Smart Attribute ID (Optional): Automatically writes or clears the assigned eSIM ICCID on the device record during lifecycle events.

⁠📈 Platform Lifecycle & Management

⁠Device Fleet & Inventory Status Matrix

• 🟢 Available: Profile is free in local inventory and unassigned.
• 🟡 Assigned: Profile is linked to an EMNify endpoint mapping. (Note: This indicates the mapping exists; actual physical installation tracking must be confirmed out-of-band).
• 🔴 Failed: Provisioning command returned an explicit FAILED or CANCELLED response from the Applivery MDM pipeline.
• ⚫ Removed: Profile has been actively deleted from the target device's physical eUICC chip.

[Import/Add] ──► Available ──► [Assign to Device / Bind EID] ──► Assigned ──► [MDM Payload Pushed] 
                     ▲                                              │
                     └───────── [Release Action Executed] ──────────┴─► (If MDM Fails) ──► Failed

⁠Provisioning Flow Architecture

⁠1. Single Device Flow

• iOS (Supervised): Triggers RefreshCellularPlans MDM command. The device handles cryptographic profile negotiation dynamically using its EID against the target SM-DP+ server address.
• iOS (Non-Supervised): Triggers an Agent Deep Link layout via Applivery push notification containing raw LPA activation codes to the native Applivery Agent (mdmAgent).
• Android: Requires a pre-recorded EID to push explicit LPA activation codes to the device local profile assistant (EuiccManager).

⁠2. Bulk Provisioning (By Group/Tag)

• Administrators select an Applivery device tag (supporting mixed iOS/Android assets) and designate an eSIM provider. The automation engine breaks these out into parallel, native, platform-specific command lines.

⁠📡 EMNify Integration Deep Dive

Configured via Settings → Integrations → EMNify. Tracks credentials inside the local database instead of transient environment properties.

⁠Configuration Reference

• Application Token: Long-lived credential generated from EMNify Portal → Settings → API. Handles internal token rotations automatically.
• Profile Mappings: Requires active numeric IDs for Service Profile, Tariff Profile, and your specific SM-DP+ Server Address.

⁠Sync & Mechanics Mapping Rules

• SIM without Endpoint: Status set to AVAILABLE.
• SIM with Endpoint: Status set to ASSIGNED (Preserved if currently marked FAILED to prevent metadata overwrites).
• SIM Suspended (Status 2): Matches AVAILABLE or ASSIGNED labeled with "EMNify: Suspended".
• Enable Mechanics: Executed via PATCH /api/v1/sim/{id} { status: { id: 1 } }. (Endpoint status configuration id:0 functions as a silent API no-op; activating the underlying SIM resolves endpoint state natively).
• Disable Mechanics: Executed via PATCH /api/v1/endpoint/{id} { status: { id: 1 } }.

⁠Cryptographic EID Binding via API

• Link by SIM (Action 1): Sends POST [https://cdn.emnify.net/api/v1/sim/operation](https://cdn.emnify.net/api/v1/sim/operation) with data structure:

{ "action": { "id": 1 }, "target": [{ "sim": { "id": <simId> }, "eid": "<deviceEid>" }] }

• Unlink by SIM (Action 3): Sends same structure using action id: 3. Critical Rule: The target profile must be in a GSMA "Released" state (physically deleted from the user handset and reported to the SM-DP+ server) or the API command will fail.

⁠EMNify Endpoints & Latency Reference

• Bulk Ops Rate-Limiter: Chunks assignments (5 per batch/500ms delay). Device toggles trigger 200ms delays; SIM state transitions use 300ms windows; orphan cleanups process at 400ms intervals.
• Core Endpoints Mapping:
• Auth: POST /api/v1/authenticate
• SIM Fetch/Update: GET /api/v1/sim?per_page=2500 | PATCH /api/v1/sim/{id}
• Endpoint Configurations: GET /api/v1/endpoint?per_page=2500 | POST /api/v1/endpoint | PATCH /api/v1/endpoint/{id}

⁠⚠️ Known Limitations & Workarounds

• Endpoint SIM Erasure Bug: Executing PATCH /endpoint/{id} { sim: null } returns a false positive HTTP 204 while leaving the SIM attached on EMNify's network backend. Workaround: Administrators should use the Release (local only) feature flag within the database UI, clear assignments manually in the EMNify platform, and run a fresh sync profile command.
• Applivery Agent Prerequisite: Non-supervised iOS push execution will fail with FbToken not found if the application instance has not established target presence on the local device.

⁠🔧 Troubleshooting Matrix

⁠🔐 Security Configuration

• Network Perimeter: Requires outbound HTTPS paths to api.applivery.io and cdn.emnify.net. No exposed inbound ingress tunnels are necessary.
• Token Access Scopes: Session tokens are held strictly within an encrypted, HTTP-only, SameSite=Lax cookie architecture named applivery_esim_session. Rotating the value of SESSION_SECRET instantly flushes and invalidates all active admin sessions globally.