@ellipsis-dev can you review ?

@coderabbitai can you review ?

#!/bin/bash

# Get PR details
echo "=== PR Details ==="
gh pr view 587 --json title,body,author,labels,additions,deletions,changedFiles,files

# Get the diff
echo -e "\n=== PR Diff ==="
gh pr diff 587

@hiteshshimpi-55, I'll review this PR for you. This is a substantial refactoring of the analytics function. Let me analyze the changes in detail.

🎯 Overview

This PR refactors GetDetailedUsageAnalytics to improve performance and maintainability. The changes look well-structured overall, but I've identified several important issues that need attention.

🔴 Critical Issues

1. Broken Parallel Fetching Logic

Location: internal/service/feature_usage_tracking.go (Lines 982-1032)

The fetchAnalyticsData function has a critical flaw in its parallel execution:

go func() {
    // Wait for customer first
    customer := <-customerChan  // ⚠️ DEADLOCK: reads before customer goroutine completes
    subscriptions, err := s.fetchSubscriptions(ctx, customer.ID)
    // ...
}()

Problem: The subscription goroutine reads from customerChan while the customer goroutine tries to write to it, but the main select loop also tries to read from the same channel. This creates a race condition and potential deadlock.

Fix: Remove the "parallel" approach here since subscriptions depend on customer data:

func (s *featureUsageTrackingService) fetchAnalyticsData(ctx context.Context, req *dto.GetUsageAnalyticsRequest) (*AnalyticsData, error) {
    // 1. Fetch customer first (required for subscriptions)
    customer, err := s.fetchCustomer(ctx, req.ExternalCustomerID)
    if err != nil {
        return nil, err
    }

    // 2. Fetch subscriptions and analytics in parallel
    var wg sync.WaitGroup
    var subscriptions []*subscription.Subscription
    var analytics []*events.DetailedUsageAnalytic
    var subErr, analyticsErr error

    wg.Add(2)
    
    go func() {
        defer wg.Done()
        subscriptions, subErr = s.fetchSubscriptions(ctx, customer.ID)
    }()
    
    go func() {
        defer wg.Done()
        params := s.createAnalyticsParams(ctx, req)
        params.CustomerID = customer.ID
        analytics, analyticsErr = s.fetchAnalytics(ctx, params)
    }()
    
    wg.Wait()
    
    if subErr != nil {
        return nil, subErr
    }
    if analyticsErr != nil {
        return nil, analyticsErr
    }

    // Rest of the function...
}

2. GROUP BY Logic Change May Break Queries

Location: internal/repository/clickhouse/feature_usage.go (Lines 475-478)

// Always include feature_id for cost calculation, then add requested grouping dimensions
groupByColumns := []string{"feature_id"}
groupByColumnAliases := []string{"feature_id"}

Problem: The code now always includes feature_id in GROUP BY, even when users don't request it. This fundamentally changes query behavior:

• When grouping by source alone, users now get (feature_id, source) combinations instead of source-level aggregates
• This breaks backward compatibility

Impact:

• Query results will be more granular than expected
• Aggregate values will be split across features unexpectedly

Recommendation: Either:

1. Remove the forced feature_id grouping and handle cost calculation differently
2. Document this as a breaking change
3. Add the aggregation layer mentioned in aggregateAnalyticsByGrouping (but verify it's actually called)

3. Aggregation Function Not Integrated

Location: internal/service/feature_usage_tracking.go (Lines 1059-1061)

// Aggregate results by requested grouping dimensions
analytics := s.aggregateAnalyticsByGrouping(data.Analytics, data.Params.GroupBy)

This function is meant to fix issue #2 above, but:

• It's only called in buildAnalyticsResponse for standard analytics
• Max bucket analytics bypass this aggregation
• The aggregation is done in-memory after fetching detailed data (inefficient)

Recommendation: Fix the SQL queries instead of post-processing.

⚠️ High Priority Issues

4. Duplicate Functions

Location: internal/service/feature_usage_tracking.go

You have two nearly identical functions:

• enrichAnalyticsWithFeatureMeterAndPriceData (Line 1581)
• enrichAnalyticsWithFeatureMeterAndPriceDataAndMaxBuckets (Line 1581)

The second one appears to be dead code. Clean this up.

5. Missing Error Context

Location: Multiple locations in feature_usage_tracking.go

When errors occur during enrichment or cost calculation, you log warnings but continue:

if err := s.enrichWithMetadata(ctx, data); err != nil {
    s.Logger.Warnw("failed to enrich analytics with metadata",
        "error", err,
        "analytics_count", len(analytics),
    )
    // Continue with partial data rather than failing completely
}

Problem: Users get incomplete data without knowing it. Consider:

• Adding a field to the response indicating partial data
• Or returning errors for critical failures

6. Incorrect Scan Arguments

Location: internal/repository/clickhouse/feature_usage.go (Lines 856-878)

The max bucket totals scanning logic looks fragile:

totalSelectColumns := len(selectColumns) + 2
scanTargets := make([]interface{}, totalSelectColumns)

This assumes a specific order but doesn't validate it. If the SELECT clause changes, scans will fail silently with wrong data in wrong fields.

💡 Suggestions

7. PRD Document in Codebase

The 403-line PRD in docs/prds/ is excellent documentation but might be better suited for:

• Confluence/Notion
• GitHub wiki
• Separate docs repository

This keeps the codebase focused on code.

8. Missing Tests

The PR description mentions "comprehensive unit and integration tests" but I don't see any test file changes. Were tests added in a separate commit?

9. Performance Claims Need Validation

The PRD claims "3x performance improvement" but there's no benchmark data in the PR. Consider adding:

• Benchmark tests
• Performance comparison results

📋 Minor Issues

10. Unused Import

import (
    "strings"  // Added but may not be used everywhere
)

11. Magic Numbers

expectedColumns := totalGroupByColumns + 5 // +5 for sum_usage, max_usage...

Consider using constants for these magic numbers.

✅ What Looks Good

1. Cleaner separation of concerns - Functions have single responsibilities
2. Better error handling - More descriptive errors with context
3. Removed dead code - Cleaned up unused repository methods
4. Comprehensive PRD - Well-documented requirements

🎬 Recommendations

Before merging:

1. ✅ Fix the parallel fetching deadlock (Critical)
2. ✅ Fix or document the GROUP BY behavior change (Critical)
3. ✅ Remove duplicate enrichment function
4. ✅ Add tests demonstrating no regression
5. ✅ Add benchmark tests validating performance claims
6. ✅ Consider moving PRD to external docs

Nice to have:

7. Add response field for partial data indicator
8. Extract magic numbers to constants
9. Add validation for scan target alignment

Would you like me to help generate test cases or create issues for any of these findings?