> ## Documentation Index
> Fetch the complete documentation index at: https://cloud-docs.mentra.glass/llms.txt
> Use this file to discover all available pages before exploring further.

# User Model

> Core user data model for MentraOS Cloud

## Overview

The User model is the central data structure representing MentraOS users. It stores authentication data, preferences, installed apps, and system settings.

## Location

`packages/cloud/src/models/user.model.ts`

## Schema Structure

### Core Fields

```typescript theme={null}
{
  email: string,                    // Primary identifier
  runningApps: string[],           // Currently active app package names
  appSettings: Map<string, AppSetting[]>, // Per-app user settings
  augmentosSettings: {...},        // System-wide settings
  location?: Location,             // Last known location
  installedApps?: InstalledApp[],  // User's installed apps
  organizations?: ObjectId[],      // Organization memberships
  defaultOrg?: ObjectId,           // Primary organization
  onboardingStatus?: Record<string, boolean>, // App onboarding tracking
  glassesModels?: string[]         // Connected glasses history
}
```

### MentraOS Settings

System-wide user preferences:

```typescript theme={null}
augmentosSettings: {
  // Audio Settings
  useOnboardMic: boolean,          // Use glasses microphone
  bypassVad: boolean,              // Bypass voice activity detection
  bypassAudioEncoding: boolean,    // Skip audio encoding
  enforceLocalTranscription: boolean, // Force on-device transcription

  // Display Settings  
  brightness: number,              // Display brightness (0-100)
  autoBrightness: boolean,         // Automatic brightness adjustment
  dashboardHeight: number,         // Dashboard UI height
  dashboardDepth: number,          // Dashboard UI depth
  alwaysOnStatusBar: boolean,      // Persistent status bar

  // System Settings
  contextualDashboard: boolean,    // Context-aware dashboard
  headUpAngle: number,            // Head-up detection angle
  sensingEnabled: boolean,         // Environmental sensing
  metricSystemEnabled: boolean     // System metrics collection
}
```

### Location Data

```typescript theme={null}
location: {
  lat: number,                     // Latitude
  lng: number,                     // Longitude  
  accuracy?: number,               // Accuracy in meters
  timestamp?: Date                 // Last update time
}
```

### Installed Apps

```typescript theme={null}
installedApps: [{
  packageName: string,             // App identifier
  installedDate: Date,             // Installation timestamp
  lastActiveAt?: Date              // Last usage timestamp
}]
```

## Instance Methods

### App Management

#### `installApp(packageName: string)`

Installs an app for the user.

```typescript theme={null}
await user.installApp('com.translator.app');
```

#### `uninstallApp(packageName: string)`

Removes an app from user's installed apps.

```typescript theme={null}
await user.uninstallApp('com.translator.app');
```

#### `isAppInstalled(packageName: string)`

Checks if an app is installed.

```typescript theme={null}
const installed = user.isAppInstalled('com.translator.app');
```

### Running Apps

#### `addRunningApp(appName: string)`

Marks an app as currently running.

```typescript theme={null}
await user.addRunningApp('com.translator.app');
```

#### `removeRunningApp(appName: string)`

Removes app from running list.

```typescript theme={null}
await user.removeRunningApp('com.translator.app');
```

#### `isAppRunning(appName: string)`

Checks if an app is currently active.

```typescript theme={null}
const running = user.isAppRunning('com.translator.app');
```

### Settings Management

#### `updateAppSettings(appName: string, settings: Array)`

Updates user's settings for a specific app.

```typescript theme={null}
await user.updateAppSettings('com.translator.app', [
  { key: 'targetLanguage', value: 'es' },
  { key: 'autoDetect', value: true }
]);
```

#### `getAppSettings(appName: string)`

Retrieves user's settings for an app.

```typescript theme={null}
const settings = user.getAppSettings('com.translator.app');
```

### Location

#### `setLocation(location: Location)`

Updates user's location.

```typescript theme={null}
await user.setLocation({
  lat: 37.7749,
  lng: -122.4194,
  accuracy: 10,
  timestamp: new Date()
});
```

## Static Methods

### `findOrCreateUser(email: string)`

Finds existing user or creates new one.

```typescript theme={null}
const user = await User.findOrCreateUser('user@example.com');
```

### `findByEmail(email: string)`

Finds user by email address.

```typescript theme={null}
const user = await User.findByEmail('user@example.com');
```

## Indexes

* **email**: Unique index for authentication
* **organizations**: For organization queries
* **installedApps.packageName**: For app usage analytics

## Relationships

### Organizations

Users can belong to multiple organizations:

* Personal organization (default)
* Company organizations
* Shared app organizations

### Apps

Two types of app relationships:

* **Installed Apps**: Apps the user has added
* **Running Apps**: Apps currently active in session

### Gallery Photos

Referenced by GalleryPhoto model using userId.

## Security Features

### Data Sanitization

All user input is sanitized using MongoSanitizer:

* Prevents NoSQL injection
* Validates data types
* Strips dangerous operators

### Field Protection

Sensitive fields are never exposed:

* Password hashes
* API tokens
* Internal IDs

## Migration Support

The model supports gradual migration from legacy fields:

### Legacy Fields (Deprecated)

```typescript theme={null}
profile?: {
  company?: string,
  website?: string,
  contactEmail?: string,
  description?: string,
  logo?: string
}
```

These are being migrated to the Organization model.

## Default Values

### MentraOS Settings Defaults

```typescript theme={null}
{
  useOnboardMic: true,
  contextualDashboard: true,
  headUpAngle: 20,
  dashboardHeight: 90,
  dashboardDepth: 100,
  brightness: 50,
  autoBrightness: true,
  sensingEnabled: true,
  alwaysOnStatusBar: false,
  bypassVad: false,
  bypassAudioEncoding: false,
  metricSystemEnabled: true,
  enforceLocalTranscription: false
}
```

## Best Practices

1. **Always use `findOrCreateUser`** for user creation
2. **Sanitize all inputs** before database operations
3. **Use lean()** for read-only operations
4. **Update arrays atomically** using MongoDB operators
5. **Log all setting changes** for audit trail

## Example Usage

```typescript theme={null}
// Find or create user
const user = await User.findOrCreateUser('alex@example.com');

// Install and run an app
await user.installApp('com.translator.app');
await user.addRunningApp('com.translator.app');

// Update app settings
await user.updateAppSettings('com.translator.app', [
  { key: 'language', value: 'spanish' }
]);

// Update system settings
user.augmentosSettings.brightness = 75;
user.augmentosSettings.useOnboardMic = false;
await user.save();

// Track glasses model
if (!user.glassesModels?.includes('Even Realities G1')) {
  user.glassesModels = [...(user.glassesModels || []), 'Even Realities G1'];
  await user.save();
}
```