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

# Gallery Photo Model

> Photo metadata storage for user galleries

## Overview

The GalleryPhoto model stores metadata for photos captured by smart glasses. It tracks ownership, storage locations, and photo attributes while the actual image files are stored in S3.

## Schema Structure

### Core Fields

```typescript theme={null}
{
  userId: string,          // User who owns the photo
  filename: string,        // Storage filename (S3 key)
  photoUrl: string,        // Public URL for access
  requestId: string,       // Original capture request ID
  appId: string,          // App that triggered capture
  uploadDate: Date,       // Upload timestamp
  metadata?: {            // Optional photo details
    originalFilename?: string,
    size?: number,
    mimeType?: string,
    width?: number,
    height?: number,
    deviceInfo?: string
  }
}
```

## Field Purposes

### userId (string)

Links the photo to its owner. Used for:

* Access control and permissions
* Gallery filtering by user
* Storage quota management

### filename (string)

The S3 object key where the photo is stored. Typically follows pattern:

* `photos/{userId}/{timestamp}-{random}.jpg`
* Ensures unique storage paths
* Enables efficient S3 organization

### photoUrl (string)

Pre-signed S3 URL or CDN link for accessing the photo:

* Time-limited access for security
* Direct browser/app access without API calls
* CDN distribution for performance

### requestId (string)

Tracks the original photo request:

* Links to app's photo request
* Enables request/response correlation
* Used for debugging capture issues

### appId (string)

Identifies which app triggered the photo:

* Analytics on app photo usage
* Per-app photo galleries
* Permission verification

### metadata (object)

Optional technical details about the photo:

* **originalFilename**: User-friendly name
* **size**: File size in bytes for quota tracking
* **mimeType**: Usually "image/jpeg" or "image/png"
* **width/height**: Dimensions for UI rendering
* **deviceInfo**: Glasses model that captured it

## Usage Patterns

### Photo Capture Flow

1. App requests photo via PhotoManager
2. Glasses capture and upload to S3
3. GalleryPhoto record created with metadata
4. Photo URL returned to requesting app

### Gallery Display

```typescript theme={null}
// Get user's photo gallery
const photos = await GalleryPhoto.findByUserId('user@example.com');
// Returns photos sorted by uploadDate (newest first)
```

### Photo Deletion

```typescript theme={null}
// Delete photo if user owns it
const deleted = await GalleryPhoto.findAndDeleteById(photoId, userId);
// Also triggers S3 deletion
```

## Indexes

* **userId**: Primary index for user queries
* **uploadDate**: For chronological sorting
* **appId**: For app-specific galleries

## Data Lifecycle

1. **Creation**: When photo uploaded from glasses
2. **Access**: Via pre-signed URLs with expiration
3. **Deletion**: User-initiated or quota management
4. **Archival**: Old photos may move to glacier storage