# Analytics Service

This package is responsible for collecting, processing, and retrieving all analytical data for the Tercul platform. It handles statistics for works, translations, and user engagement.

## Architecture Overview

The analytics service provides a central point for all statistical operations. It is designed to be called by other application services (e.g., after a user likes a work) to increment or decrement counters. It also provides methods for more complex analytical tasks, such as calculating reading time and sentiment scores.

### Key Components

- **`service.go`**: The main entry point for the analytics service. It implements the `Service` interface and contains the core business logic for all analytical operations.
- **`interfaces.go`**: Defines the `Service` and `Repository` interfaces, establishing a clear contract for the service's capabilities and its data persistence requirements.
- **Repository (external)**: The service relies on an `AnalyticsRepository`, implemented in the `internal/data/sql` package, to interact with the database.

## Features

- **Counter Management**: Provides methods to increment and decrement statistics like views, likes, comments, and bookmarks for works and translations.
- **Content Analysis**: Calculates and updates metrics such as:
    - Reading time
    - Complexity (via readability scores)
    - Sentiment analysis
- **User Engagement Tracking**: Monitors user activities like works read, comments made, and likes given.
- **Trending System**: Calculates and stores trending works based on a scoring algorithm that considers views, likes, and comments.

## Usage

The `analytics.Service` is intended to be injected into other application services that need to record analytical events.

### Example: Incrementing Work Likes

```go
// In another application service (e.g., the 'like' service)
err := analyticsService.IncrementWorkLikes(ctx, workID)
```

### Example: Updating Work Analysis

```go
// In a command handler (e.g., work.AnalyzeWork)
err := analyticsService.UpdateWorkReadingTime(ctx, workID)
if err != nil {
    // handle error
}

err = analyticsService.UpdateWorkComplexity(ctx, workID)
if err != nil {
    // handle error
}
```

## Dependencies

- **`internal/domain`**: Uses the core domain entities (e.g., `WorkStats`, `TranslationStats`, `Trending`).
- **`internal/jobs/linguistics`**: Relies on the `linguistics` package for analysis data like readability scores and sentiment.
- **Database**: Persists all statistical data to the main application database via the `AnalyticsRepository`.
- **Logging**: Uses the centralized logger from `internal/platform/log`.
- **OpenTelemetry**: All service methods are instrumented for distributed tracing.