> ## 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.

# Data Models Overview

> MongoDB schemas and data structures in MentraOS Cloud

## Overview

MentraOS Cloud uses MongoDB for persistent storage of users, apps, photos, and system data. All models are defined using Mongoose schemas and follow consistent patterns for timestamps, references, and data validation.

## Location

`packages/cloud/src/models/`

## Core Models

### User Model

The central model representing MentraOS users with their preferences, installed apps, and system settings.

**Key Features:**

* Authentication data (email, hashed passwords, tokens)
* Installed apps and permissions
* User preferences and settings
* Organization associations
* Gallery photos references

### App Model

Represents third-party applications available in the MentraOS ecosystem.

**Key Features:**

* App metadata (name, description, version)
* API authentication (hashed keys)
* Webhook configurations
* Permission declarations
* Tool schemas for AI interactions
* App store status and review workflow

### Gallery Photo Model

Stores metadata for photos captured by users' smart glasses.

**Key Features:**

* S3 storage references
* User associations
* Capture metadata (timestamp, device info)
* Tags and descriptions
* Privacy settings

### Organization Model

Manages organizational accounts for enterprise deployments.

**Key Features:**

* Organization profiles
* Member management
* App sharing within organizations
* Billing and subscription data

### App Uptime Model

Tracks app availability and performance metrics.

**Key Features:**

* Uptime monitoring data
* Response time metrics
* Error tracking
* Historical performance data

### Temp Token Model

Manages temporary authentication tokens for various flows.

**Key Features:**

* Short-lived tokens for authentication
* Password reset tokens
* Email verification tokens
* Token expiration management

## Common Patterns

### Timestamps

All models include Mongoose timestamps:

```typescript theme={null}
{
  timestamps: true // Adds createdAt and updatedAt
}
```

### Soft Deletes

Critical models use soft deletes for data recovery:

```typescript theme={null}
{
  deletedAt: Date,
  isDeleted: { type: Boolean, default: false }
}
```

### References

Models use MongoDB ObjectId references:

```typescript theme={null}
{
  userId: { type: Schema.Types.ObjectId, ref: 'User' },
  organizationId: { type: Schema.Types.ObjectId, ref: 'Organization' }
}
```

### Indexing Strategy

* Email fields indexed for authentication
* Package names indexed for app lookups
* User IDs indexed for session queries
* Compound indexes for complex queries

## Data Relationships

```mermaid theme={null}
graph TD
    User -->|has many| InstalledApp
    User -->|has many| GalleryPhoto
    User -->|belongs to| Organization
    App -->|belongs to| Organization
    App -->|has many| Permission
    App -->|has many| Tool
    InstalledApp -->|references| App
    GalleryPhoto -->|belongs to| User
```

## Migration Strategy

The models support gradual migration from legacy fields:

* `developerId` → `organizationId` (App model)
* Individual org fields → Organization reference (User model)
* Legacy permission strings → Permission objects

## Security Considerations

1. **Password Hashing**: Bcrypt with salt rounds
2. **API Key Hashing**: SHA-256 for app API keys
3. **Token Security**: Crypto-random token generation
4. **Data Encryption**: Sensitive fields encrypted at rest
5. **Access Control**: Field-level security in schemas

## Best Practices

1. **Always use lean()** for read-only queries
2. **Validate data** before database operations
3. **Use transactions** for multi-document updates
4. **Index frequently** queried fields
5. **Avoid deep nesting** in embedded documents
6. **Use references** for large or frequently updated data

## Schema Validation

Models include built-in validation:

* Email format validation
* URL format validation
* Enum constraints for status fields
* Required field enforcement
* Custom validators for business logic

## Performance Optimization

1. **Projection**: Only fetch needed fields
2. **Pagination**: Use skip/limit for large datasets
3. **Aggregation**: Use MongoDB aggregation pipeline
4. **Caching**: Cache frequently accessed data
5. **Batch Operations**: Use bulkWrite for multiple updates