# Hooks Remix Signal Service

A real-time stream processing service built on Apache Flink that tracks user engagement signals related to hook remix actions.

## Overview

This service processes remix-related events from hooks (short video clips) and stores engagement signals in Redis. The signals are used by recommendation systems to understand user preferences for remix-worthy content and remix engagement patterns.

## Features

### Event Processing
- **Hook Remix Tap Events**: Tracks when users tap the remix button on hooks via `HooksTapRemix` events
- **Hook Remix Events**: Tracks actual remix creation events via `HookRemix` events  
- **Remix Signals**: Stores user engagement signals based on remix interaction behavior

### Data Storage
The service stores the following data in Redis:

#### User Remix Signals
- `hooks_positive_signal_remix:{user_id}` - Sorted set of hooks the user has tapped remix on (timestamp as score)
  - **Size Limit**: Automatically trimmed to keep only the most recent 200 entries

## Event Schema

The service expects events with the following structure:

### HooksTapRemix Event
```json
{
  "name": "HooksTapRemix",
  "timestamp": "2024-01-01T00:00:00Z",
  "source": "hooks_app",
  "user_id": "12345",
  "session_id": "session_abc",
  "properties": {
    "hook_id": "hook_123"
  },
  "request_id": "req_789"
}
```

### HookRemix Event
```json
{
  "name": "HookRemix",
  "timestamp": "2024-01-01T00:00:00Z",
  "source": "hooks_app",
  "user_id": "12345",
  "session_id": "session_abc",
  "properties": {
    "hook_id": "hook_123"
  },
  "request_id": "req_789"
}
```

## Configuration

The service supports both local development and cloud deployment configurations:

### Local Development
- Stream ARN: Points to development Kinesis stream
- Redis: localhost:6379
- Environment: dev
- Kinesis Reader: POLLING mode (simpler setup)

### Production/Staging
- Stream ARN: Retrieved from CDK runtime properties
- Redis: Retrieved from CDK runtime properties
- Environment: prod/staging
- Kinesis Reader: Enhanced Fan-Out (EFO) with dedicated consumer
- EFO Consumer: `hooks-remix-signal-consumer-{env}`

## Running the Service

### Local Development
```bash
python main.py
```

### Production Deployment
The service is deployed via AWS CDK as a Kinesis Analytics application.

## Dependencies

- Apache Flink (PyFlink)
- Redis Python client
- AWS Kinesis connector for Flink

## Monitoring

The service outputs processing logs with the identifier `HOOK-REMIX-EVENTS` for monitoring and debugging.

## Signal Usage

The remix signals stored by this service can be used for:

1. **Remix Recommendation**: Identify hooks that are likely to be remix-worthy based on user engagement
2. **User Interest Profiling**: Understand which types of content users are interested in remixing
3. **Content Discovery**: Surface content that similar users have shown remix interest in
4. **Remix Trend Analysis**: Track which hooks are generating the most remix interest

## Redis Key Patterns

- `hooks_positive_signal_remix:{user_id}` - User's remix engagement history