# Hooks Omniplay Signal Service

## Overview

The Hooks Omniplay Signal Service is a real-time data processing application built with Apache Flink that processes user engagement signals related to opening the omni player for hooks. It consumes events from a Kinesis stream and stores positive engagement signals in Redis for use by recommendation algorithms.

## Event Schema

The service processes `HooksOpenOmniPlayer` events with the following structure:

```json
{
  "name": "HooksOpenOmniPlayer",
  "source": "mobile",
  "user_id": "123",
  "timestamp": "{ISO-timestamp}",
  "properties": {
    "hook_id": "abc-def-123-456"
  }
}
```

## Data Storage

- **Redis Key**: `hooks_positive_signal_omniplay:{user_id}`
- **Data Structure**: Sorted set with hook IDs as members and timestamps as scores
- **Retention**: Only the most recent 200 omniplay events per user are kept
- **Purpose**: Used by recommendation algorithms to identify user preferences

## Architecture

### Components
- **Kinesis Stream**: Consumes events from `rec-events-stream`
- **Flink Application**: Processes events in real-time
- **Redis**: Stores user engagement signals
- **CloudWatch**: Logging and monitoring

### Processing Flow
1. Consumes `HooksOpenOmniPlayer` events from Kinesis
2. Validates event structure (requires `user_id` and `hook_id`)
3. Stores engagement signal in Redis sorted set
4. Maintains sliding window of 200 most recent events per user
5. Logs processing results for monitoring

## Configuration

### Environment Variables
- `stream.arn`: Kinesis stream ARN
- `redis.host`: Redis cluster endpoint
- `redis.port`: Redis port (default: 6379)
- `env.stage`: Environment stage (dev/staging/prod)

### Flink Configuration
- **Parallelism**: 4
- **Checkpointing**: Enabled (1-minute intervals)
- **Processing Mode**: Exactly-once
- **State TTL**: 24 hours

## Deployment

The service is deployed as a Kinesis Data Analytics application using AWS CDK:

- **Application Name**: `hooks-omniplay-signal-app-{stage}`
- **Consumer Name**: `hooks-omniplay-signal-consumer-{stage}`
- **Log Group**: `/aws/kinesis-analytics/hooks-omniplay-signal-app-{stage}`

## Monitoring

### CloudWatch Logs
- Application logs are sent to CloudWatch
- Processing results logged with identifier: `HOOK-OPEN-OMNI-PLAYER-EVENTS`

### Metrics
- Flink application metrics available in CloudWatch
- Custom metrics for processing success/failure rates

## Local Development

For local development, ensure you have:
1. Python environment with PyFlink dependencies
2. Local Redis instance running on port 6379
3. Kinesis connector JAR file in the `jar/` directory

## Related Services

This service is part of the recommendation infrastructure alongside:
- `hooks-comment-view-signal`: Tracks comment viewing engagement
- `hooks-profile-view-signal`: Tracks profile viewing engagement
- Other signal processing services for collaborative filtering