# Hooks Profile View Signal Service

A PyFlink application that processes real-time profile view events from Kinesis streams and stores profile view engagement signals in Redis for recommendation systems and analytics.

## Overview

This service processes `ProfileView` events to track when users view other users' profiles, particularly useful for:
- Profile recommendation systems
- Social discovery features
- User engagement analytics
- Creator insights (who viewed their profile)

## Event Processing

### Input Events
- **Event Name**: `ProfileView`
- **Source**: Kinesis stream containing profile view events
- **Schema**: 
```json
{
  "name": "ProfileView",
  "timestamp": "2024-01-01T12:00:00Z",
  "source": "web",
  "user_id": "viewer_user_id",
  "session_id": "session_123",
  "properties": {
    "viewed_user_id": "profile_owner_id",
    "viewed_user_handle": "profile_owner_handle"
  }
}
```

### Data Storage

The service stores profile view signals in Redis using sorted sets:

#### Profile Views by User
- **Key**: `hooks_positive_signal_profile_view:{viewing_user_id}`
- **Value**: Sorted set of viewed user IDs
- **Score**: Timestamp of the view
- **Purpose**: Track which profiles a user has viewed
- **Size Limit**: Automatically trimmed to keep only the most recent 200 entries

### Redis Data Structure

```redis
# Example: User 123 viewed profiles 456 and 789
ZADD hooks_positive_signal_profile_view:123 1704067200 456
ZADD hooks_positive_signal_profile_view:123 1704070800 789

# Query recent profile views for user 123
ZREVRANGE hooks_positive_signal_profile_view:123 0 -1 WITHSCORES
```

## Configuration

The service uses the following configuration sources:

### Runtime Properties (Production/Staging)
- `rec.config.stream.arn` - Kinesis stream ARN
- `rec.config.redis.host` - Redis host
- `rec.config.redis.port` - Redis port
- `rec.config.env.stage` - Environment stage

### Default Values (Local Development)
- Stream ARN: `arn:aws:kinesis:us-east-2:590183763515:stream/rec-events-stream`
- Redis Host: `localhost`
- Redis Port: `6379`
- Environment: `dev`

## Running the Service

### Local Development
```bash
cd suno-cdk/flink-app
python hooks-profile-view-signal/main.py
```

### Production Deployment
The service is deployed via AWS CDK as a Kinesis Analytics application:
- Runtime: PyFlink
- Checkpointing: Exactly-once processing
- State TTL: 24 hours
- Mini-batch processing: Enabled for performance

## Performance Features

- **Exactly-once processing**: Ensures no duplicate profile view signals
- **State TTL**: Automatic cleanup of old state after 24 hours
- **Mini-batch processing**: Improved throughput with 5-second latency tolerance
- **Error handling**: Graceful handling of malformed events

## Use Cases

### Profile Recommendations
```python
# Get users who viewed similar profiles
viewer_profiles = redis_client.zrange("hooks_positive_signal_profile_view:user_123", 0, -1)
# Use for "People who viewed this profile also viewed..." recommendations
```

### User Engagement Analytics
```python
# Count profile views by a user in the last 7 days
week_ago = time.time() - (7 * 24 * 3600)
recent_views = redis_client.zcount("hooks_positive_signal_profile_view:user_123", week_ago, "+inf")
```

### Creator Insights
- Track which users are viewing specific creator profiles
- Identify trending creators based on profile view volume
- Recommend creators to users based on view patterns

## Dependencies

- **PyFlink**: Stream processing framework
- **Redis**: Data storage for profile view signals
- **AWS Kinesis**: Event stream source
- **Java 17**: Required for Flink runtime

## Error Handling

The service includes comprehensive error handling:
- Redis connection failures are logged and events are dropped
- Malformed events are filtered out
- UDF exceptions are caught and logged
- Service continues processing despite individual event failures

## Monitoring

The service outputs processed events to the console with the identifier `PROFILE-VIEW-EVENTS` for monitoring and debugging purposes.

## Future Enhancements

- Add profile view frequency analysis
- Implement profile view clustering for recommendation improvements
- Add support for profile view duration tracking
- Include profile view source (search, recommendation, direct) context