📱 Mobile App Module

📖 Overview

The Mobile App module provides version management and update checking for DashClicks mobile applications (iOS and Android). It enables the backend to notify mobile clients when newer versions are available, supporting both standard releases and variant builds (e.g., beta, production).

File Path: internal/api/v1/mobile-app/

Key Features

Version Checking: Mobile apps query latest available version
Platform Support: Separate versions for iOS and Android
Build Variants: Support for beta, production, staging builds
Update Metadata: Version codes, URLs, release notes, minimum versions
Forced Updates: Flag critical updates as mandatory

� Directory Structure

mobile-app/
├── 📄 index.js           - Module router
├── 📂 controllers/
│   └── updates.js        - Update check controller
├── 📂 services/
│   └── updates.js        - Business logic for version queries
├── 📂 routes/
│   └── updates.js        - Route definitions
└── 📂 validations/
    └── updates.js        - Request validation schemas

�🗄️ Collections Used

`mobile-app.updates`

Purpose: Store mobile app version information
Model: shared/models/mobile-app.updates.js
Key Fields:
- platform (String, enum) - 'ios' or 'android'
- variant (String, enum) - 'dashclicks' or 'whitelabel'
- version_code (Number, required) - Incremental build number for comparison
- is_mandatory (Boolean, default: false) - Force update flag
- message (String) - Update message or release notes
- created (Date) - Creation timestamp
- updated (Date) - Last update timestamp

Unique Index: { platform: 1, variant: 1, version_code: 1 }

🔄 Data Flow

Version Check Flow

sequenceDiagram
    participant MobileApp as Mobile App
    participant API as Mobile App API
    participant DB as MongoDB

    MobileApp->>API: GET /api/v1/mobile-app/updates/latest?platform=android&variant=dashclicks
    API->>DB: Find latest update: sort by version_code DESC

    alt Update Found
        DB-->>API: Latest version document
        API->>API: Compare version_codes

        alt Newer Version Available
            API-->>MobileApp: { version_code, is_mandatory, message }

            alt Is Mandatory
                MobileApp->>MobileApp: Force update dialog
            else Optional Update
                MobileApp->>MobileApp: Show update prompt (optional)
            end
        else Current Version
            API-->>MobileApp: { no update needed }
        end
    else No Update Found
        API-->>MobileApp: { error: no version data }
    end

🔧 Core Functions

Get Latest Update

Endpoint: GET /api/v1/mobile-app/updates/latest

Query Parameters:

platform (String, required) - 'ios' or 'android'
variant (String, required) - Build variant identifier

Service: services/updates.js

exports.getLatest = async ({ platform, variant }) => {
  return await Updates.findOne(
    { platform, variant },
    {},
    { sort: { version_code: -1 } }, // Get highest version code
  );
};

Response:

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "platform": "android",
    "variant": "dashclicks",
    "version_code": 251,
    "is_mandatory": false,
    "message": "Bug fixes and performance improvements",
    "created": "2024-01-15T10:30:00.000Z",
    "updated": "2024-01-15T10:30:00.000Z"
  }
}

Validation (validations/updates.js):

platform: Required, enum ['ios', 'android']
variant: Required, string

🔀 Integration Points

Mobile App Initialization

When Mobile App Launches:

App reads current version_code from build configuration
Makes API call to /updates/latest with platform and variant
Compares server version_code with local version
If server version is higher:
- Check is_mandatory flag
- Show update dialog (forced or optional)
- Redirect to download_url if user accepts

Example Mobile Logic:

const currentVersionCode = 250;
const response = await fetch(
  '/api/v1/mobile-app/updates/latest?platform=android&variant=production',
);
const latestUpdate = response.data;

if (latestUpdate.version_code > currentVersionCode) {
  if (latestUpdate.is_mandatory) {
    // Block app usage, show forced update dialog
    showForceUpdateDialog(latestUpdate);
  } else {
    // Show optional update prompt
    showUpdatePrompt(latestUpdate);
  }
}

Minimum Version Enforcement

Purpose: Ensure compatibility with backend APIs.

Logic:

minimum_version_code specifies oldest supported version
Mobile apps below this threshold are blocked from API access
Prevents outdated apps from causing errors or security issues

Backend Middleware (hypothetical):

// In authentication middleware
if (req.headers['x-app-version-code'] < minimumVersionCode) {
  return res.status(426).json({
    error: 'UPDATE_REQUIRED',
    message: 'Your app version is no longer supported. Please update.',
    download_url: latestUpdate.download_url,
  });
}

⚙️ Configuration

Platform Values

iOS: 'ios' - For Apple App Store versions
Android: 'android' - For Google Play Store versions

Variant Types

Common variants:

production - Stable release for general users
beta - Beta testing builds
staging - Internal testing builds
development - Development/debug builds

Version Numbering

Version Name: Semantic versioning (e.g., 2.5.1)

Major.Minor.Patch format
Human-readable, displayed in UI

Version Code: Incremental integer (e.g., 251)

Auto-incrementing build number
Used for programmatic comparison
Always increases with each build

Example Mapping:

v2.5.0 → version_code: 250
v2.5.1 → version_code: 251
v2.6.0 → version_code: 260

⚠️ Important Notes

🔢 Simple Version Comparison: Only version_code is used (no version names/strings)
🚫 Mandatory Updates: Use is_mandatory: true for critical security/compatibility fixes
🔐 No Authentication: Update check endpoint typically doesn't require auth (pre-login)
📦 Unique Versions: Each platform/variant/version_code combination is unique (enforced by index)
📱 Two Variants: System supports dashclicks and whitelabel apps separately
� Message Field: Use for release notes or update prompts shown to users

🧪 Edge Cases & Special Handling

Case: No Version Record Found

Condition: Query for platform/variant that doesn't exist in database

Handling:

Service returns null
Mobile app treats as "no update available"
Logs warning for monitoring

Case: Corrupt Version Data

Condition: version_code or version_name missing/invalid

Handling:

Schema validation enforces required fields
Unique index prevents duplicate entries
Backend validation ensures data integrity

Case: Downgrade Attempt

Condition: Server version_code is lower than mobile app version

Handling:

Mobile app should ignore (don't show downgrade prompt)
Indicates beta user checking production variant
Or pre-release build checking stable channel

Case: Multiple Variants on Same Device

Condition: User switches between beta and production builds

Handling:

Each build queries its own variant
Separate update checking per variant
No cross-contamination of version data

📈 Performance Considerations

Indexing

Unique Index:

{ platform: 1, variant: 1, version_code: 1 }

Query Optimization:

Index supports: findOne({ platform, variant }) with sort by version_code
Very fast lookup (indexed fields + sort)
Minimal collection size (few documents per platform/variant)

Caching Strategy

Client-Side:

Cache update check response for 6-24 hours
Only re-check on app restart or manual refresh
Reduces API load

Server-Side:

Update data changes infrequently (days/weeks)
Consider in-memory cache with 1-hour TTL
Preload all variants into cache on service startup

Collection Size

Expected Size: Small (< 100 documents)

~10 versions per variant (keep history)
2-3 variants per platform
2 platforms
Total: ~60-80 documents maximum

📊 Usage Examples

Creating New Version Record

// Admin panel or deployment script
await MobileAppUpdate.create({
  platform: 'android',
  variant: 'production',
  version_name: '2.5.1',
  version_code: 251,
  download_url: 'https://play.google.com/store/apps/details?id=com.dashclicks',
  release_notes: 'Fixed crash on conversation view\nImproved notification handling',
  minimum_version_code: 240,
  is_mandatory: false,
});

Forcing Critical Update

// Security patch - force all users to update
await MobileAppUpdate.create({
  platform: 'ios',
  variant: 'production',
  version_name: '2.5.2',
  version_code: 252,
  download_url: 'https://apps.apple.com/app/dashclicks/id123456789',
  release_notes: 'Critical security update - please install immediately',
  minimum_version_code: 252, // Force update by raising minimum
  is_mandatory: true,
});

Beta Channel Release

// Beta version ahead of production
await MobileAppUpdate.create({
  platform: 'android',
  variant: 'beta',
  version_name: '2.6.0-beta.1',
  version_code: 260,
  download_url: 'https://play.google.com/apps/testing/com.dashclicks',
  release_notes: 'Testing new conversation features',
  minimum_version_code: 240,
  is_mandatory: false,
});

Last Updated: 2025-01-08
Module Path: internal/api/v1/mobile-app/
Main Route: GET /api/v1/mobile-app/updates/latest
Collection: mobile-app.updates

📖 Overview​

Key Features​

� Directory Structure​

�🗄️ Collections Used​

mobile-app.updates​

🔄 Data Flow​

Version Check Flow​

🔧 Core Functions​

Get Latest Update​

🔀 Integration Points​

Mobile App Initialization​

Minimum Version Enforcement​

⚙️ Configuration​

Platform Values​

Variant Types​

Version Numbering​

⚠️ Important Notes​

🧪 Edge Cases & Special Handling​

Case: No Version Record Found​

Case: Corrupt Version Data​

Case: Downgrade Attempt​

Case: Multiple Variants on Same Device​

📈 Performance Considerations​

Indexing​

Caching Strategy​

Collection Size​

📊 Usage Examples​

Creating New Version Record​

Forcing Critical Update​

Beta Channel Release​

Documentation Assistant

📖 Overview

Key Features

� Directory Structure

�🗄️ Collections Used

`mobile-app.updates`

🔄 Data Flow

Version Check Flow

🔧 Core Functions

Get Latest Update

🔀 Integration Points

Mobile App Initialization

Minimum Version Enforcement

⚙️ Configuration

Platform Values

Variant Types

Version Numbering

⚠️ Important Notes

🧪 Edge Cases & Special Handling

Case: No Version Record Found

Case: Corrupt Version Data

Case: Downgrade Attempt

Case: Multiple Variants on Same Device

📈 Performance Considerations

Indexing

Caching Strategy

Collection Size

📊 Usage Examples

Creating New Version Record

Forcing Critical Update

Beta Channel Release