​
Overview

The AppService (app.service.ts) is the central registry and management system for all third-party applications (TPAs) in MentraOS. It handles app discovery, authentication, webhook interactions, and maintains the app ecosystem.

​
Location

packages/cloud/src/services/core/app.service.ts

​
Key Responsibilities

​
1. App Registry Management

  • Maintains both system apps and user-installed apps
  • Provides app discovery and retrieval
  • Manages app metadata and configurations

​
2. App Authentication

  • Validates API keys for app connections
  • Generates and manages app tokens
  • Handles app-specific security

​
3. Webhook Orchestration

  • Manages webhook endpoints for apps
  • Handles session lifecycle webhooks (start/stop)
  • Implements retry logic for failed webhooks
  • Supports tool call webhooks for app interactions

​
4. App State Management

  • Tracks app states across user sessions
  • Manages app installation and permissions
  • Handles pre-installed app configurations

​
Core Methods

​
getAllApps(userId?: string)

Retrieves all available apps for a user, combining:
  • System apps (hardcoded for reliability)
  • User-installed apps from MongoDB
  • Pre-installed apps based on environment
const apps = await appService.getAllApps('user@example.com');
// Returns array of AppI objects

​
getApp(packageName: string)

Fetches a specific app by its package name. 
const app = await appService.getApp('com.translator.app');

​
validateApiKey(packageName: string, apiKey: string)

Validates an app’s API key for authentication. 
const isValid = await appService.validateApiKey(
  'com.translator.app',
  'app_api_key_here'
);

​
generateAppToken(packageName: string, userId: string, sessionId: string)

Creates a JWT token for app authentication. 
const token = await appService.generateAppToken(
  'com.translator.app',
  'user@example.com',
  'session-123'
);

​
Webhook System

​
Session Webhooks

Apps can register webhooks to be notified of session events:

​
Start Webhook

// Called when app starts
{
  url: 'https://app.example.com/webhook/start',
  headers: { 'X-App-Secret': 'secret' }
}

// Payload sent:
{
  type: 'session.start',
  sessionId: 'session-123',
  userId: 'user@example.com',
  capabilities: { /* device capabilities */ }
}

​
Stop Webhook

// Called when app stops
{
  type: 'session.stop',
  sessionId: 'session-123',
  reason: 'user_requested' | 'session_ended' | 'error'
}

​
Tool Call Webhooks

Apps can expose tools that the system can call: 
// Tool webhook request
{
  type: 'tool.call',
  toolName: 'translate',
  parameters: {
    text: 'Hello',
    targetLanguage: 'es'
  },
  sessionId: 'session-123'
}

// Expected response
{
  success: true,
  result: 'Hola'
}

​
Pre-installed Apps

The service manages different app installation tiers:

​
Production Apps

const PRE_INSTALLED = [
  "com.augmentos.livecaptions",
  "cloud.augmentos.notify", 
  "cloud.augmentos.mira"
];

​
Debug/Development Apps

Additional apps loaded in development mode:
  • Testing apps
  • Developer tools
  • Experimental features

​
App State Tracking

The service maintains in-memory app states: 
// Structure: userId -> packageName -> AppState
private appStates = new Map<string, Map<string, AppState>>();
States include:
  • INITIALIZING: App is starting up
  • CONNECTED: App is ready
  • RESURRECTING: App is reconnecting
  • STOPPED: App has been terminated

​
Integration with Other Services

​
With AppManager

  • AppService provides app metadata
  • AppManager handles runtime lifecycle

​
With SessionService

  • Apps are associated with user sessions
  • Session events trigger app webhooks

​
With MongoDB

  • App definitions stored in apps collection
  • User app installations tracked in users collection

​
Configuration

​
Environment Variables

  • SYSTEM_DASHBOARD_PACKAGE_NAME: Package name for system dashboard
  • NODE_ENV: Determines if debug apps are loaded
  • DEBUG_APPS: Force load debug apps in production

​
System Apps

Currently hardcoded for reliability, includes:
  • Dashboard app
  • System utilities
  • Core functionality apps

​
Security Considerations

  1. API Key Hashing: All API keys are hashed before storage
  2. Webhook Secrets: Optional endpoint secrets for webhook verification
  3. Token Expiration: App tokens have limited lifetime
  4. Permission Validation: Apps must declare required permissions

​
Future Improvements

  1. Database Migration: Move system apps to database
  2. Service Splitting: Separate into:
    • appstore.service.ts: App store functionality
    • developer.service.ts: Developer portal features
    • tools.service.ts: Tool execution system
  3. Caching Layer: Add Redis for app metadata caching
  4. Webhook Queue: Implement proper webhook queue with retries

​
Usage Example

// In AppManager when app connects
const app = await appService.getApp(packageName);
if (!app) {
  throw new Error('App not found');
}

// Validate API key
const valid = await appService.validateApiKey(packageName, apiKey);
if (!valid) {
  throw new Error('Invalid API key');
}

// Generate session token
const token = await appService.generateAppToken(
  packageName,
  userId,
  sessionId
);

// Send start webhook
await appService.sendWebhook(app.webhooks?.start, {
  type: 'session.start',
  sessionId,
  userId
});

​
Best Practices

  1. Always validate app existence before operations
  2. Use try-catch for webhook calls - they can fail
  3. Log webhook failures but don’t crash the session
  4. Cache app metadata when possible
  5. Validate permissions before granting access