tercul-backend/internal/app/analytics/README.md

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

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

Example: Updating Work Analysis

// 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.