Mobile Management Service (zv-mobile-management-service)

Centralized service for managing mobile app lifecycle: version releases, forced updates, maintenance windows, remote feature toggles, and usage analytics. The primary management layer for mobile apps (Forsa).

Service Info

|| Property | Value | ||----------|-------| || Framework | NestJS (TypeScript) | || Database | PostgreSQL (TypeORM) | || Lambda (dev) | zv-mobile-management-service-dev | || AWS Region | eu-central-1 (Frankfurt) |

Base URLs

|| Environment | URL | ||-------------|-----| || Test (dev) | https://test.zonevast.com/mobile/api/v1 | || Local | http://localhost:3010/api/v1 |

Concept

The service manages mobile apps through 5 modules, all scoped to an App entity identified by a unique slug (e.g., forsa):

graph LR
    subgraph app [App - slug: forsa]
        V[Versions]
        M[Maintenance]
        F[Feature Flags]
        E[Analytics]
    end
    
    subgraph admin_endpoints [Admin API - X-Api-Key]
        A1[CRUD Apps]
        A2[Publish Versions]
        A3[Toggle Maintenance]
        A4[Manage Flags]
        A5[View Dashboard]
    end
    
    subgraph public_endpoints [Public API - No Auth]
        P1[Check Version]
        P2[Check Maintenance]
        P3[Get Feature Flags]
        P4[Track Events]
    end

1. Apps -- Register mobile apps with slug, platform, and store info
2. Versions -- Publish version releases with force-update support
3. Maintenance -- Toggle maintenance mode with bilingual messages (AR/EN)
4. Feature Flags -- Remote feature toggling with optional config JSON
5. Analytics -- Event tracking from mobile clients

Authentication

• Admin endpoints require X-Api-Key header
• Public endpoints need no authentication (designed for mobile client use)

# Admin request example
curl https://test.zonevast.com/mobile/api/v1/admin/apps \
  -H "X-Api-Key: your-api-key"

---

Admin API Reference

All admin endpoints are prefixed with /admin.

1. Apps

List All Apps

curl https://test.zonevast.com/mobile/api/v1/admin/apps \
  -H "X-Api-Key: YOUR_KEY"

Response:

[
  {
    "id": 1,
    "slug": "forsa",
    "name": "فرصة - Forsa",
    "platform": "android",
    "packageName": "com.zonevast.forsa",
    "currentVersion": "1.0.1",
    "currentVersionCode": 2,
    "storeUrl": "https://play.google.com/store/apps/details?id=com.zonevast.forsa",
    "isActive": true,
    "createdAt": "2026-04-27T14:04:45.968Z",
    "updatedAt": "2026-04-27T14:04:45.968Z"
  }
]

Create App

curl -X POST https://test.zonevast.com/mobile/api/v1/admin/apps \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{
    "slug": "forsa",
    "name": "Forsa",
    "platform": "android",
    "packageName": "com.zonevast.forsa",
    "storeUrl": "https://play.google.com/store/apps/details?id=com.zonevast.forsa"
  }'

Update App

curl -X PUT https://test.zonevast.com/mobile/api/v1/admin/apps/forsa \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{
    "currentVersion": "1.0.2",
    "currentVersionCode": 3
  }'

2. Versions

List Versions

curl https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/versions \
  -H "X-Api-Key: YOUR_KEY"

Publish New Version

curl -X POST https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/versions \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{
    "versionName": "1.0.2",
    "versionCode": 3,
    "minVersion": "1.0.0",
    "isForce": false,
    "storeUrl": "https://play.google.com/store/apps/details?id=com.zonevast.forsa",
    "changelog": "- Bug fixes\n- Performance improvements"
  }'

Field	Type	Required	Description
versionName	string	Yes	Semantic version (e.g., 1.0.2)
versionCode	number	Yes	Numeric version code (must increment)
minVersion	string	No	Minimum supported version
isForce	boolean	No	Force users to update (default: false)
storeUrl	string	No	Link to store listing
changelog	string	No	Release notes

3. Maintenance

Enable / Update Maintenance Mode

curl -X PUT https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/maintenance \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{
    "isActive": true,
    "messageEn": "Scheduled maintenance in progress",
    "messageAr": "صيانة مجدولة جارية",
    "estimatedEnd": "2026-04-28T20:00:00Z"
  }'

Field	Type	Required	Description
isActive	boolean	Yes	true to enable, false to disable
messageEn	string	No	English message shown to users
messageAr	string	No	Arabic message shown to users
estimatedEnd	string	No	ISO 8601 datetime for expected end

Behavior: Setting isActive: true deactivates any existing active maintenance event and creates a new one. Setting isActive: false simply turns off maintenance.

Turn Off Maintenance

curl -X PUT https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/maintenance \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{"isActive": false}'

View Maintenance History

curl https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/maintenance/history \
  -H "X-Api-Key: YOUR_KEY"

Returns last 20 maintenance events ordered by most recent.

4. Feature Flags

List All Flags (Admin View)

curl https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/features/admin \
  -H "X-Api-Key: YOUR_KEY"

Create Feature Flag

curl -X POST https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/features \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{
    "flagKey": "new_checkout_flow",
    "isEnabled": true,
    "description": "Enable new checkout UI"
  }'

Field	Type	Required	Description
flagKey	string	Yes	Unique key identifier (e.g., new_checkout_flow)
isEnabled	boolean	No	Default state (default: false)
description	string	No	Human-readable description
config	object	No	JSON config passed to the client

Update Feature Flag

curl -X PUT https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/features/new_checkout_flow \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{
    "isEnabled": false,
    "description": "Disabled for testing"
  }'

Note: The flag is identified by its flagKey (string), not by numeric ID.

Delete Feature Flag

curl -X DELETE https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/features/new_checkout_flow \
  -H "X-Api-Key: YOUR_KEY"

5. Analytics

Get Analytics Dashboard

curl "https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/analytics?days=7" \
  -H "X-Api-Key: YOUR_KEY"

Response:

{
  "period": "7 days",
  "totalEvents": 1234,
  "topEventTypes": [
    { "type": "app_open", "count": "800" },
    { "type": "bid_placed", "count": "300" }
  ],
  "recentEvents": [
    {
      "id": 50,
      "eventType": "app_open",
      "userId": "user-uuid",
      "platform": "android",
      "appVersion": "1.0.1",
      "createdAt": "2026-04-28T10:00:00Z"
    }
  ]
}

---

Public API Reference

These endpoints are designed for mobile client consumption. No authentication required.

Check App Info

curl https://test.zonevast.com/mobile/api/v1/apps/forsa

Check for Version Update

Mobile clients call this to check if an update is available.

curl "https://test.zonevast.com/mobile/api/v1/apps/forsa/version?platform=android&currentVersion=1.0.0"

Check Maintenance Status

Mobile clients call this on startup to check if the app is under maintenance.

curl https://test.zonevast.com/mobile/api/v1/apps/forsa/maintenance

Response (maintenance active):

{
  "maintenance": true,
  "messageEn": "Scheduled maintenance in progress",
  "messageAr": "صيانة مجدولة جارية",
  "estimatedEnd": "2026-04-28T20:00:00Z"
}

Response (no maintenance):

{
  "maintenance": false,
  "messageAr": null,
  "messageEn": null,
  "estimatedEnd": null
}

Get Feature Flags

Returns flags as a key-value map for easy consumption by mobile clients.

curl https://test.zonevast.com/mobile/api/v1/apps/forsa/features

Response:

{
  "new_checkout_flow": {
    "enabled": true,
    "config": null
  },
  "dark_mode_v2": {
    "enabled": false,
    "config": { "theme": "dark" }
  }
}

Track Analytics Event

curl -X POST https://test.zonevast.com/mobile/api/v1/apps/forsa/analytics \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "app_open",
    "userId": "user-uuid-here",
    "platform": "android",
    "appVersion": "1.0.1",
    "eventData": { "screen": "home" }
  }'

Field	Type	Required	Description
eventType	string	Yes	Event name (e.g., app_open, bid_placed)
userId	string	No	User identifier
platform	string	No	android, ios
appVersion	string	No	App version string
eventData	object	No	Arbitrary JSON payload

---

Data Models

App

Field	Type	Description
id	number	Primary key
slug	string	Unique identifier (e.g., forsa)
name	string	Display name
platform	string	android, ios, or both
packageName	string	Package identifier (e.g., com.zonevast.forsa)
currentVersion	string	Current semantic version
currentVersionCode	number	Current numeric version code
storeUrl	string	Link to store listing
isActive	boolean	Whether the app is active
createdAt	datetime	Creation timestamp
updatedAt	datetime	Last update timestamp

AppVersion

Field	Type	Description
id	number	Primary key
versionName	string	Semantic version (e.g., 1.0.2)
versionCode	number	Numeric version code
minVersion	string	Minimum supported version (nullable)
isForce	boolean	Whether update is forced
storeUrl	string	Store download URL (nullable)
changelog	string	Release notes (nullable)
isActive	boolean	Whether version is active
createdAt	datetime	Creation timestamp

MaintenanceEvent

Field	Type	Description
id	number	Primary key
isActive	boolean	Whether maintenance is currently active
messageEn	string	English message shown to users (nullable)
messageAr	string	Arabic message shown to users (nullable)
estimatedEnd	datetime	Expected end time (nullable)
createdAt	datetime	Creation timestamp
updatedAt	datetime	Last update timestamp

FeatureFlag

Field	Type	Description
id	number	Primary key
flagKey	string	Unique key identifier (e.g., new_checkout_flow)
isEnabled	boolean	Whether the flag is active
description	string	Human-readable description (nullable)
config	JSON	Arbitrary config object (nullable)
createdAt	datetime	Creation timestamp
updatedAt	datetime	Last update timestamp

AnalyticsEvent

Field	Type	Description
id	number	Primary key
eventType	string	Event name (e.g., app_open, bid_placed)
userId	string	User identifier (nullable)
eventData	JSON	Arbitrary event payload (nullable)
platform	string	Client platform (nullable)
appVersion	string	Client app version (nullable)
createdAt	datetime	Creation timestamp

---

Common Workflows

Workflow 1: Enable Maintenance Mode

Use case: You need to take the app offline for scheduled maintenance.

# 1. Enable maintenance with bilingual message
curl -X PUT https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/maintenance \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{
    "isActive": true,
    "messageEn": "Back in 30 minutes",
    "messageAr": "نعود خلال 30 دقيقة",
    "estimatedEnd": "2026-04-28T20:00:00Z"
  }'

# 2. Mobile clients will see maintenance on next launch:
# GET /apps/forsa/maintenance -> { "maintenance": true, ... }

# 3. When done, turn off maintenance:
curl -X PUT https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/maintenance \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{"isActive": false}'

Workflow 2: Create and Toggle Feature Flag

Use case: Gradually roll out a new feature.

# 1. Create the flag (disabled by default)
curl -X POST https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/features \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{"flagKey": "new_bidding_ui", "isEnabled": false, "description": "New bidding experience"}'

# 2. Enable it when ready
curl -X PUT https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/features/new_bidding_ui \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{"isEnabled": true}'

# 3. Mobile clients check flags on startup:
# GET /apps/forsa/features -> { "new_bidding_ui": { "enabled": true, "config": null } }

Workflow 3: Publish a New App Version

Use case: Release a new version with optional force update.

# 1. Publish the version
curl -X POST https://test.zonevast.com/mobile/api/v1/admin/apps/forsa/versions \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{
    "versionName": "1.1.0",
    "versionCode": 5,
    "isForce": false,
    "minVersion": "1.0.0",
    "changelog": "- New bidding experience\n- Bug fixes"
  }'

# 2. Mobile clients check for updates:
# GET /apps/forsa/version?platform=android&currentVersion=1.0.0

# 3. Update the app's current version metadata
curl -X PUT https://test.zonevast.com/mobile/api/v1/admin/apps/forsa \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{"currentVersion": "1.1.0", "currentVersionCode": 5}'

Workflow 4: Track Events from Mobile Client

Use case: Mobile app tracks user behavior.

# Called directly from mobile app (no API key needed)
curl -X POST https://test.zonevast.com/mobile/api/v1/apps/forsa/analytics \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "bid_placed",
    "userId": "abc-123-def",
    "platform": "android",
    "appVersion": "1.0.1",
    "eventData": { "auctionId": 42, "amount": 150 }
  }'

# View aggregated data in admin dashboard:
# GET /admin/apps/forsa/analytics?days=7

---

Deployment

cd /home/yousef/Documents/workspace/zonevast/services/zv-mobile-management-service/

# Deploy to dev
npm run deploy:dev

# Deploy to prod
npm run deploy:prod

Source Code Location

Path	Purpose
src/modules/app/	App CRUD and management
src/modules/version/	Version publishing and checking
src/modules/maintenance/	Maintenance mode toggle
src/modules/feature/	Feature flag CRUD
src/modules/analytics/	Event tracking and dashboard
src/database/	TypeORM database configuration