# Screenshot Transmission Implementation

## Overview
Clients send screenshots via MQTT during heartbeat intervals. The listener service receives these screenshots and forwards them to the server API for storage.

## Architecture

### MQTT Topic
- **Topic**: `infoscreen/{uuid}/screenshot`
- **Payload Format**: 
  - Raw binary image data (JPEG/PNG), OR
  - JSON with base64-encoded image: `{"image": "<base64-string>"}`

### Components

#### 1. Listener Service (`listener/listener.py`)
- **Subscribes to**: `infoscreen/+/screenshot`
- **Function**: `handle_screenshot(uuid, payload)`
  - Detects payload format (binary or JSON)
  - Converts binary to base64 if needed
  - Forwards to API via HTTP POST

#### 2. Server API (`server/routes/clients.py`)
- **Endpoint**: `POST /api/clients/<uuid>/screenshot`
- **Authentication**: No authentication required (internal service call)
- **Accepts**: 
  - JSON: `{"image": "<base64-encoded-image>"}`
  - Binary: raw image data
- **Storage**: 
  - Saves to `server/screenshots/{uuid}_{timestamp}.jpg` (with timestamp)
  - Saves to `server/screenshots/{uuid}.jpg` (latest, for quick retrieval)

#### 3. Retrieval (`server/wsgi.py`)
- **Endpoint**: `GET /screenshots/<uuid>`
- **Returns**: Latest screenshot for the given client UUID
- **Nginx**: Exposes `/screenshots/{uuid}.jpg` in production

## Unified Identification Method

Screenshots are identified by **client UUID**:
- Each client has a unique UUID stored in the `clients` table
- Screenshots are stored as `{uuid}.jpg` (latest) and `{uuid}_{timestamp}.jpg` (historical)
- The API endpoint requires UUID validation against the database
- Retrieval is done via `GET /screenshots/<uuid>` which returns the latest screenshot

## Data Flow

```
Client → MQTT (infoscreen/{uuid}/screenshot)
    ↓
Listener Service
    ↓ (validates client exists)
    ↓ (converts binary → base64 if needed)
    ↓
API POST /api/clients/{uuid}/screenshot
    ↓ (validates client UUID)
    ↓ (decodes base64 → binary)
    ↓
Filesystem: server/screenshots/{uuid}.jpg
    ↓
Dashboard/Nginx: GET /screenshots/{uuid}
```

## Configuration

### Environment Variables
- **Listener**: `API_BASE_URL` (default: `http://server:8000`)
- **Server**: Screenshots stored in `server/screenshots/` directory

### Dependencies
- Listener: Added `requests>=2.31.0` to `listener/requirements.txt`
- Server: Uses built-in Flask and base64 libraries

## Error Handling

- **Client Not Found**: Returns 404 if UUID doesn't exist in database
- **Invalid Payload**: Returns 400 if image data is missing or invalid
- **API Timeout**: Listener logs error and continues (timeout: 10s)
- **Network Errors**: Listener logs and continues operation

## Security Considerations

- Screenshot endpoint does not require authentication (internal service-to-service)
- Client UUID must exist in database before screenshot is accepted
- Base64 encoding prevents binary data issues in JSON transport
- File size is tracked and logged for monitoring

## Future Enhancements

- Add screenshot retention policy (auto-delete old timestamped files)
- Add compression before transmission
- Add screenshot quality settings
- Add authentication between listener and API
- Add screenshot history API endpoint