Start Session

A user begins a new capture session from the wearable or mobile app; the server allocates a session record and returns a session ID that is used for all subsequent frame and audio uploads.

Flow

1. User presses record — The mobile app (or wearable SDK) sends a POST request to /sessions/start with an optional JSON body { "captureMode": "audio_video" | "audio_only" }. The request is authenticated via a Cognito JWT.

2. Authentication — The Lambda extracts user_id from the Cognito JWT claims (sub). Missing or empty user_id returns HTTP 401.

3. Capture mode resolution — The captureMode field from the request body is validated. Any unrecognized value falls back to "audio_video".

4. Session record creation — A new UUID is generated and a DynamoDB item is written to the sessions table with:

5. sessionId, userId, captureMode
6. frameCount: 0, currentFrameWindow: 0
7. status: "active"

8. createdAt (ISO 8601 UTC)

9. Response — Returns HTTP 200 with { "sessionId": "<uuid>" }. The client stores this ID and attaches it to every subsequent frame/audio upload request.

Entry Point

• Lambda: main/server/api/sessions/start/app.py → lambda_handler
• HTTP method: POST /sessions/start (API Gateway, Cognito-authenticated)

Dependencies

• DynamoDB table: SESSIONS_TABLE_NAME (default encache-sessions)
• AWS Cognito JWT authorizer (via API Gateway)

Error Cases