@trafficgroup/knex-rel 0.1.6 → 0.1.8

package/plan.md

@@ -1,871 +1,684 @@
-# Total Vehicle Class Implementation Plan
+# Plan: Add Study-Level Minute Result Aggregation
 
-## Executive Summary
+## Overview
 
-This plan details the implementation of a "Total" vehicle class that aggregates all custom vehicle classes for both TMC and ATR minute results. The "Total" class will be added during transformation in the knex-rel module and will always appear as the LAST class in the vehicles object.
-
-**Key Requirements**:
-
-- Add "Total" class AFTER all custom classes
-- For ATR: "Total" reuses existing `lane_counts` (all classes per lane)
-- For TMC: "Total" sums all vehicle classes across all directions and turns
-- NO database schema changes required
-- Transformation happens in `ReportConfigurationDAO.applyConfigurationToNestedStructure()`
+Add `getGroupedMinuteResultsByStudyUuid()` method to `VideoMinuteResultDAO` to aggregate minute results across all COMPLETED videos in a study, with time normalization using `recordingStartedAt`.
 
 ---
 
-## Current Architecture Analysis
+## Schema Analysis (Existing)
 
-### Data Flow
+### Table Relationships
 
 ```
-1. Python Processor → Database (JSONB results with detection labels)
-   ↓
-2. VideoMinuteResultDAO → Retrieve raw minute results
-   ↓
-3. API Controller → Apply report configuration
-   ↓
-4. ReportConfigurationService.transformVideoResults()
-   ↓
-5. ReportConfigurationDAO.applyConfigurationToNestedStructure()
-   ↓
-6. Frontend → Display custom classes + Total
-```
-
-### Current Structure Patterns
-
-**ATR Format (Lane-based)**:
-
-```json
-{
-  "vehicles": {
-    "car": { "0": 45, "1": 50 },
-    "truck": { "0": 10, "1": 8 }
-  },
-  "lane_counts": { "0": 55, "1": 58 }, // Already has totals per lane!
-  "total_count": 113,
-  "study_type": "ATR"
-}
-```
-
-**TMC Format (Direction/Turn-based)**:
-
-```json
-{
-  "vehicles": {
-    "car": {
-      "NORTH": { "straight": 10, "left": 5, "right": 3, "u-turn": 0 },
-      "SOUTH": { "straight": 8, "left": 2, "right": 4, "u-turn": 1 }
-    },
-    "truck": {
-      "NORTH": { "straight": 5, "left": 1, "right": 0, "u-turn": 0 }
-    }
-  },
-  "counts": {
-    "total_vehicles": 39,
-    "entry_vehicles": 39
-  },
-  "study_type": "TMC"
-}
+study (id, uuid, name, type, status)
+  ↓ (1:N)
+folders (id, uuid, studyId)
+  ↓ (1:N)
+video (id, uuid, folderId, recordingStartedAt, status, videoType)
+  ↓ (1:N)
+video_minute_results (id, uuid, video_id, minute_number, results)
 ```
 
-**After Custom Class Transformation** (2 custom classes: "Light" and "Heavy"):
+### Key Fields
 
-```json
-{
-  "vehicles": {
-    "Light": { "NORTH": { "straight": 10, "left": 5 }, ... },
-    "Heavy": { "NORTH": { "straight": 5, "left": 1 }, ... }
-  }
-}
-```
+- `video.recordingStartedAt`: TIMESTAMPTZ in UTC (nullable for backward compatibility)
+- `video.status`: 'QUEUED' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'PENDING'
+- `video_minute_results.minute_number`: Integer offset from video start (0-based)
+- `video_minute_results.results`: JSONB containing TMC or ATR data
 
-**After Total Addition** (desired output):
+### Existing Indexes
 
-```json
-{
-  "vehicles": {
-    "Light": { "NORTH": { "straight": 10, "left": 5 }, ... },
-    "Heavy": { "NORTH": { "straight": 5, "left": 1 }, ... },
-    "Total": { "NORTH": { "straight": 15, "left": 6 }, ... }  // Sum of all classes
-  }
-}
-```
+- `idx_videos_folder_recording` on (folderId, recordingStartedAt) WHERE recordingStartedAt IS NOT NULL
 
 ---
 
-## Implementation Location
+## Interface Definitions
 
-### File: `knex-rel/src/dao/report-configuration/report-configuration.dao.ts`
+### New Response Interface
 
-**Method to Modify**: `applyConfigurationToNestedStructure()` (Lines 273-315)
+**File**: `knex-rel/src/dao/VideoMinuteResultDAO.ts` (add at top with existing interfaces)
 
-**Current Implementation**:
-
-1. Builds reverse mapping: detection label → custom class name (Lines 278-290)
-2. Initializes empty structure for each custom class (Lines 293-296)
-3. Iterates through detection labels and merges into custom classes (Lines 299-312)
-4. Returns transformed structure (Line 314)
+```typescript
+interface IStudyTimeGroupResult {
+  absoluteTime: string; // ISO 8601 datetime for bucket start (e.g., "2024-10-26T14:30:00Z")
+  groupIndex: number; // Sequential index for UI ordering
+  label: string; // Human-readable label (e.g., "2:30 PM - 2:44 PM")
+  results: ITMCResult | IATRResult; // Aggregated results (reuse existing types)
+  minuteCount: number; // Total individual minutes aggregated
+  videoCount: number; // Number of distinct videos contributing
+  contributingVideos: string[]; // Array of video UUIDs for traceability
+}
 
-**Where to Add "Total"**: AFTER line 312, BEFORE return statement (Line 314)
+interface IGroupedStudyResponse {
+  success: boolean;
+  data: IStudyTimeGroupResult[];
+  groupingMinutes: number; // Grouping interval (1, 5, 10, 15, 30, 60)
+  study: {
+    uuid: string;
+    name: string;
+    type: "TMC" | "ATR";
+    status: string;
+  };
+  videoCount: number; // Total videos included in aggregation
+  dateRange: {
+    earliest: string; // ISO 8601 of earliest recording start
+    latest: string; // ISO 8601 of latest recording end
+  };
+}
+```
 
 ---
 
-## Detailed Implementation Plan
-
-### Step 1: Add "Total" Class After Custom Class Transformation
-
-**Location**: `ReportConfigurationDAO.applyConfigurationToNestedStructure()` (After line 312)
-
-**Logic**:
-
-```typescript
-// After line 312 (end of detection label iteration)
-// Add "Total" class that aggregates all custom classes
-
-result["Total"] = this._createTotalClass(result);
+## SQL Query Strategy
+
+### Phase 1: Get Study Videos with Metadata
+
+**Purpose**: Fetch all COMPLETED videos with recordingStartedAt, validate study exists
+
+```sql
+SELECT
+  s.id as study_id,
+  s.uuid as study_uuid,
+  s.name as study_name,
+  s.type as study_type,
+  s.status as study_status,
+  v.id as video_id,
+  v.uuid as video_uuid,
+  v.name as video_name,
+  v.recording_started_at,
+  v.duration_seconds
+FROM study s
+INNER JOIN folders f ON f.study_id = s.id
+INNER JOIN video v ON v.folder_id = f.id
+WHERE s.uuid = ?
+  AND v.status = 'COMPLETED'
+  AND v.recording_started_at IS NOT NULL
+ORDER BY v.recording_started_at ASC;
+```
 
-return result;
+**Error Handling**:
+
+- If study not found → throw Error("Study with UUID {uuid} not found")
+- If no videos found → return empty data array with study metadata
+- If videos missing recordingStartedAt → log warning, exclude from aggregation
+
+### Phase 2: Get All Minute Results with Time Normalization
+
+**Purpose**: Fetch minute results with absolute timestamps calculated in SQL
+
+```sql
+SELECT
+  vmr.id,
+  vmr.video_id,
+  vmr.minute_number,
+  vmr.results,
+  v.uuid as video_uuid,
+  v.recording_started_at,
+  -- Calculate absolute wall-clock time for this minute
+  (v.recording_started_at + (vmr.minute_number || ' minutes')::INTERVAL) as absolute_time,
+  -- Calculate time bucket index (floor division by grouping interval)
+  FLOOR(
+    EXTRACT(EPOCH FROM (v.recording_started_at + (vmr.minute_number || ' minutes')::INTERVAL)) / (? * 60)
+  ) as time_bucket
+FROM video_minute_results vmr
+INNER JOIN video v ON vmr.video_id = v.id
+WHERE v.id IN (?)  -- Array of video IDs from Phase 1
+ORDER BY time_bucket, vmr.minute_number;
 ```
 
-### Step 2: Implement `_createTotalClass()` Helper Method
+**Parameters**:
 
-**Location**: Add new private method in `ReportConfigurationDAO` class (After line 350)
+- `?` (first): groupingMinutes (e.g., 15)
+- `?` (second): Array of video IDs from Phase 1
 
-**Method Signature**:
+**Output**: Rows with absolute timestamps and time bucket assignments
 
-```typescript
-private _createTotalClass(customClassesData: Record<string, any>): any
-```
+### Phase 3: Aggregate by Time Bucket (TypeScript)
 
-**Implementation**:
+**Reason for TypeScript aggregation**:
 
-```typescript
-/**
- * Create "Total" class by aggregating all custom vehicle classes
- *
- * Handles both ATR and TMC formats:
- * - ATR: Aggregates counts per lane across all vehicle classes
- * - TMC: Aggregates counts per direction and turn across all vehicle classes
- *
- * @param customClassesData - Transformed custom classes structure
- * @returns Aggregated totals matching the same nested structure
- */
-private _createTotalClass(customClassesData: Record<string, any>): any {
-    const total: any = {};
+- Reuse existing `aggregateTMCResults()` and `aggregateATRResults()` methods
+- Complex nested JSON aggregation is easier in TypeScript than SQL
+- Study type determines aggregation logic (not individual video types)
 
-    // Iterate through all custom classes and merge their data
-    for (const [className, nestedData] of Object.entries(customClassesData)) {
-        // Use existing _deepMergeNumericData to sum all nested values
-        Object.assign(total, this._deepMergeNumericData(total, nestedData));
-    }
+**Pseudo-SQL for Grouping** (illustrative, actual grouping in TS):
 
-    return total;
-}
+```sql
+SELECT
+  time_bucket,
+  MIN(absolute_time) as bucket_start_time,
+  MAX(absolute_time) as bucket_end_time,
+  COUNT(*) as minute_count,
+  COUNT(DISTINCT video_id) as video_count,
+  array_agg(DISTINCT video_uuid) as contributing_videos,
+  array_agg(results ORDER BY absolute_time) as all_results
+FROM [results_from_phase_2]
+GROUP BY time_bucket
+ORDER BY time_bucket;
 ```
 
-**Explanation**:
-
-- Reuses existing `_deepMergeNumericData()` helper (Lines 328-350)
-- Works for both ATR (2-level: vehicle → lane → count) and TMC (3-level: vehicle → direction → turn → count)
-- No need to detect study type - structure-agnostic aggregation
-- Handles empty data (returns empty object `{}`)
-
 ---
 
-## Key Ordering Strategy
+## TypeScript Implementation Logic
 
-### Ensuring "Total" Appears Last
-
-JavaScript object key ordering is preserved in modern engines (ES2015+) when:
-
-1. String keys are added in insertion order
-2. Keys are enumerated via `Object.entries()`, `Object.keys()`, `for...in`
-
-**Our Implementation**:
+### Method Signature
 
 ```typescript
-// Lines 293-296: Initialize custom classes FIRST (insertion order)
-for (const customClass of config.configuration.customClasses) {
-  result[customClass.name] = {};
-}
-
-// Lines 299-312: Populate custom classes (preserves order)
-for (const [detectionLabel, nestedData] of Object.entries(vehiclesStructure)) {
-  // ... merge logic
-}
-
-// NEW: Add "Total" LAST (after all custom classes)
-result["Total"] = this._createTotalClass(result);
-
-// Line 314: Return result (Total is last key)
-return result;
+async getGroupedMinuteResultsByStudyUuid(
+  studyUuid: string,
+  groupingMinutes: number = 15
+): Promise<IGroupedStudyResponse>
 ```
 
-**Why This Works**:
+### Step-by-Step Logic
 
-- Custom classes initialized in config order (Lines 293-296)
-- "Total" added AFTER all custom classes (new code)
-- JavaScript guarantees insertion order preservation
-- Frontend will render "Total" as last tab
+#### Step 1: Fetch Study and Videos
 
----
-
-## ATR vs TMC Behavior
-
-### ATR (Lane-Based Totals)
-
-**Input Structure**:
-
-```json
-{
-  "Light": { "0": 45, "1": 50 },
-  "Heavy": { "0": 10, "1": 8 }
+```typescript
+// Get study metadata
+const study = await this.knex("study").where("uuid", studyUuid).first();
+if (!study) {
+  throw new Error(`Study with UUID ${studyUuid} not found`);
 }
-```
-
-**Total Output**:
 
-```json
-{
-  "Total": { "0": 55, "1": 58 } // Sum per lane
+// Get all COMPLETED videos with recordingStartedAt
+const videos = await this.knex("video as v")
+  .innerJoin("folders as f", "v.folderId", "f.id")
+  .select(
+    "v.id",
+    "v.uuid",
+    "v.name",
+    "v.recordingStartedAt",
+    "v.durationSeconds",
+  )
+  .where("f.studyId", study.id)
+  .where("v.status", "COMPLETED")
+  .whereNotNull("v.recordingStartedAt")
+  .orderBy("v.recordingStartedAt", "asc");
+
+// Early return if no valid videos
+if (videos.length === 0) {
+  return {
+    success: true,
+    data: [],
+    groupingMinutes,
+    study: {
+      uuid: study.uuid,
+      name: study.name,
+      type: study.type,
+      status: study.status,
+    },
+    videoCount: 0,
+    dateRange: {
+      earliest: null,
+      latest: null,
+    },
+  };
 }
 ```
 
-**Calculation**:
+#### Step 2: Fetch and Transform Minute Results
 
-- Lane "0": 45 (Light) + 10 (Heavy) = 55
-- Lane "1": 50 (Light) + 8 (Heavy) = 58
+```typescript
+const videoIds = videos.map((v) => v.id);
+const videoMap = new Map(videos.map((v) => [v.id, v]));
+
+// Fetch minute results with absolute time calculation
+const minuteResults = await this.knex("video_minute_results as vmr")
+  .innerJoin("video as v", "vmr.video_id", "v.id")
+  .select(
+    "vmr.video_id",
+    "vmr.minute_number",
+    "vmr.results",
+    "v.uuid as video_uuid",
+    this.knex.raw(`
+      v.recording_started_at + (vmr.minute_number || ' minutes')::INTERVAL
+      as absolute_time
+    `),
+    this.knex.raw(
+      `
+      FLOOR(
+        EXTRACT(EPOCH FROM (v.recording_started_at + (vmr.minute_number || ' minutes')::INTERVAL))
+        / (? * 60)
+      ) as time_bucket
+    `,
+      [groupingMinutes],
+    ),
+  )
+  .whereIn("v.id", videoIds)
+  .orderBy("time_bucket")
+  .orderBy("vmr.minute_number");
+```
 
-**Alternative (Use existing `lane_counts`)**:
+#### Step 3: Group by Time Buckets
 
-The ATR structure ALREADY has `lane_counts` at the top level:
+```typescript
+// Group results by time bucket
+const bucketMap = new Map<
+  number,
+  {
+    absoluteTime: Date;
+    results: any[];
+    videoUuids: Set<string>;
+    minuteCount: number;
+  }
+>();
+
+for (const row of minuteResults) {
+  const bucket = row.time_bucket;
+
+  if (!bucketMap.has(bucket)) {
+    bucketMap.set(bucket, {
+      absoluteTime: new Date(row.absolute_time),
+      results: [],
+      videoUuids: new Set(),
+      minuteCount: 0,
+    });
+  }
 
-```json
-{
-  "vehicles": { "Light": {...}, "Heavy": {...} },
-  "lane_counts": { "0": 55, "1": 58 }  // Already calculated!
+  const bucketData = bucketMap.get(bucket)!;
+  bucketData.results.push(row.results);
+  bucketData.videoUuids.add(row.video_uuid);
+  bucketData.minuteCount++;
 }
 ```
 
-**Decision**: For ATR, we can EITHER:
+#### Step 4: Aggregate Each Bucket
 
-1. ✅ **Option A (Recommended)**: Calculate "Total" by summing custom classes (consistent with TMC)
-2. ⚠️ **Option B**: Copy `lane_counts` directly into `vehicles["Total"]` (reuses existing data)
-
-**Recommendation**: Use Option A (sum custom classes) for consistency with TMC, even though Option B is technically available.
-
-### TMC (Direction/Turn-Based Totals)
-
-**Input Structure**:
+```typescript
+// Sort buckets by time
+const sortedBuckets = Array.from(bucketMap.entries()).sort(
+  (a, b) => a[0] - b[0],
+);
+
+const aggregatedGroups: IStudyTimeGroupResult[] = sortedBuckets.map(
+  ([bucketIndex, bucketData], idx) => {
+    // Determine aggregation type based on study type
+    let aggregatedResult;
+    if (study.type === "TMC") {
+      aggregatedResult = this.aggregateTMCResults(bucketData.results);
+    } else {
+      aggregatedResult = this.aggregateATRResults(bucketData.results);
+    }
 
-```json
-{
-  "Light": {
-    "NORTH": { "straight": 10, "left": 5, "right": 3 },
-    "SOUTH": { "straight": 8, "left": 2, "right": 4 }
+    // Calculate bucket end time
+    const bucketStartTime = bucketData.absoluteTime;
+    const bucketEndTime = new Date(
+      bucketStartTime.getTime() + groupingMinutes * 60 * 1000 - 1000,
+    );
+
+    return {
+      absoluteTime: bucketStartTime.toISOString(),
+      groupIndex: idx,
+      label: this.formatAbsoluteTimeLabel(bucketStartTime, bucketEndTime),
+      results: aggregatedResult,
+      minuteCount: bucketData.minuteCount,
+      videoCount: bucketData.videoUuids.size,
+      contributingVideos: Array.from(bucketData.videoUuids),
+    };
   },
-  "Heavy": {
-    "NORTH": { "straight": 5, "left": 1, "right": 0 },
-    "SOUTH": { "straight": 2, "left": 0, "right": 1 }
-  }
-}
+);
 ```
 
-**Total Output**:
+#### Step 5: Calculate Date Range
 
-```json
-{
-  "Total": {
-    "NORTH": { "straight": 15, "left": 6, "right": 3 },
-    "SOUTH": { "straight": 10, "left": 2, "right": 5 }
-  }
-}
+```typescript
+const earliestVideo = videos[0]; // Already sorted by recordingStartedAt
+const latestVideo = videos[videos.length - 1];
+
+// Calculate actual end time of last video
+const latestEndTime = latestVideo.durationSeconds
+  ? new Date(
+      new Date(latestVideo.recordingStartedAt).getTime() +
+        latestVideo.durationSeconds * 1000,
+    )
+  : new Date(latestVideo.recordingStartedAt);
+
+return {
+  success: true,
+  data: aggregatedGroups,
+  groupingMinutes,
+  study: {
+    uuid: study.uuid,
+    name: study.name,
+    type: study.type,
+    status: study.status,
+  },
+  videoCount: videos.length,
+  dateRange: {
+    earliest: earliestVideo.recordingStartedAt.toISOString(),
+    latest: latestEndTime.toISOString(),
+  },
+};
 ```
 
-**Calculation**:
-
-- NORTH/straight: 10 (Light) + 5 (Heavy) = 15
-- NORTH/left: 5 (Light) + 1 (Heavy) = 6
-- SOUTH/straight: 8 (Light) + 2 (Heavy) = 10
-- etc.
-
 ---
 
-## Edge Cases & Validation
+## Code Reuse Strategy
 
-### Edge Case 1: Empty Data (No Vehicles)
+### Existing Methods to Reuse
 
-**Input**:
+1. **`aggregateTMCResults(minutes: any[]): ITMCResult`** (lines 508-585)
+   - No changes needed
+   - Accepts array of raw results objects
+   - Returns aggregated TMC structure
 
-```json
-{
-  "vehicles": {}
-}
-```
-
-**After Transformation**:
-
-```json
-{
-  "vehicles": {
-    "Light": {},
-    "Heavy": {},
-    "Total": {} // Empty object
-  }
-}
-```
-
-**Behavior**: `_createTotalClass()` returns empty object `{}`
+2. **`aggregateATRResults(minutes: any[]): IATRResult`** (lines 590-643)
+   - No changes needed
+   - Accepts array of raw results objects
+   - Returns aggregated ATR structure
 
-### Edge Case 2: Single Custom Class
+3. **`formatTimeLabel(startMinute: number, endMinute: number): string`** (lines 703-715)
+   - DO NOT reuse - this formats video-relative time (HH:MM format from minute offset)
+   - Need NEW method for absolute time formatting
 
-**Input**:
+### New Helper Method Required
 
-```json
-{
-  "vehicles": {
-    "AllVehicles": { "0": 100, "1": 95 }
+```typescript
+/**
+ * Format absolute time label for display (12-hour clock)
+ */
+private formatAbsoluteTimeLabel(startTime: Date, endTime: Date): string {
+  const formatTime = (date: Date): string => {
+    const hours = date.getHours();
+    const minutes = date.getMinutes();
+    const ampm = hours >= 12 ? 'PM' : 'AM';
+    const displayHours = hours % 12 || 12;
+    return `${displayHours}:${minutes.toString().padStart(2, '0')} ${ampm}`;
+  };
+
+  const formatDate = (date: Date): string => {
+    return date.toLocaleDateString('en-US', {
+      month: 'short',
+      day: 'numeric',
+      year: 'numeric'
+    });
+  };
+
+  // If same day, show: "Oct 26: 2:30 PM - 2:44 PM"
+  if (startTime.toDateString() === endTime.toDateString()) {
+    return `${formatDate(startTime)}: ${formatTime(startTime)} - ${formatTime(endTime)}`;
   }
-}
-```
-
-**Output**:
 
-```json
-{
-  "vehicles": {
-    "AllVehicles": { "0": 100, "1": 95 },
-    "Total": { "0": 100, "1": 95 } // Same as single class
-  }
+  // If different days, show full timestamps
+  return `${formatDate(startTime)} ${formatTime(startTime)} - ${formatDate(endTime)} ${formatTime(endTime)}`;
 }
 ```
 
-**Behavior**: "Total" equals the single custom class (valid)
-
-### Edge Case 3: Missing Directions/Turns
-
-**Input** (TMC - Light has NORTH, Heavy only has SOUTH):
+---
 
-```json
-{
-  "Light": { "NORTH": { "straight": 10 } },
-  "Heavy": { "SOUTH": { "straight": 5 } }
-}
-```
+## Error Handling Strategy
 
-**Output**:
+### Input Validation
 
-```json
-{
-  "Total": {
-    "NORTH": { "straight": 10 },
-    "SOUTH": { "straight": 5 }
-  }
+```typescript
+// Validate groupingMinutes
+const validIntervals = [1, 5, 10, 15, 30, 60];
+if (!validIntervals.includes(groupingMinutes)) {
+  throw new Error(
+    `Invalid grouping interval: ${groupingMinutes}. Must be one of: ${validIntervals.join(", ")}`,
+  );
 }
 ```
 
-**Behavior**: `_deepMergeNumericData()` handles missing keys gracefully (Lines 339-347)
+### Edge Cases
 
-### Edge Case 4: Null/Undefined Values
+| Scenario                                     | Handling                                           |
+| -------------------------------------------- | -------------------------------------------------- |
+| Study not found                              | Throw error immediately                            |
+| No folders in study                          | Return empty data array with study metadata        |
+| No COMPLETED videos                          | Return empty data array, videoCount = 0            |
+| Videos missing recordingStartedAt            | Exclude from aggregation, log warning              |
+| No minute results                            | Return empty data array                            |
+| Type mismatch (video.videoType ≠ study.type) | Use study.type for aggregation (trust study level) |
+| Missing duration_seconds                     | Use last minute_number to estimate end time        |
+| Empty results in minute                      | Include in count but don't affect aggregation      |
 
-**Input**:
+### Logging Strategy
 
-```json
-{
-  "Light": { "0": 10, "1": null },
-  "Heavy": { "0": 5 }
+```typescript
+// At start of method
+console.log(
+  `[VideoMinuteResultDAO] Aggregating study ${studyUuid} with ${groupingMinutes}min intervals`,
+);
+
+// After video fetch
+console.log(
+  `[VideoMinuteResultDAO] Found ${videos.length} COMPLETED videos with recording times`,
+);
+const videosWithoutTime = await this.knex("video as v")
+  .innerJoin("folders as f", "v.folderId", "f.id")
+  .where("f.studyId", study.id)
+  .where("v.status", "COMPLETED")
+  .whereNull("v.recordingStartedAt")
+  .count("* as count");
+if (+videosWithoutTime[0].count > 0) {
+  console.warn(
+    `[VideoMinuteResultDAO] Excluding ${videosWithoutTime[0].count} videos without recordingStartedAt`,
+  );
 }
-```
-
-**Output**:
 
-```json
-{
-  "Total": { "0": 15, "1": 0 } // null treated as 0
-}
+// After aggregation
+console.log(
+  `[VideoMinuteResultDAO] Generated ${aggregatedGroups.length} time buckets`,
+);
 ```
 
-**Behavior**: `_deepMergeNumericData()` checks `typeof source === 'number'` (Line 330)
-
----
-
-## Testing Strategy
-
-### Unit Tests (to be created)
-
-**File**: `knex-rel/src/dao/report-configuration/report-configuration.dao.test.ts`
-
-**Test Cases**:
-
-1. **ATR: Total Class Aggregation**
-   - Input: 2 custom classes with lane counts
-   - Verify: Total sums all lanes correctly
-   - Verify: Total appears as last key
-
-2. **TMC: Total Class Aggregation**
-   - Input: 2 custom classes with direction/turn structure
-   - Verify: Total sums all directions and turns
-   - Verify: Total appears as last key
-
-3. **Edge Case: Empty Vehicles**
-   - Input: No vehicle data
-   - Verify: Total is empty object `{}`
-
-4. **Edge Case: Single Custom Class**
-   - Input: 1 custom class
-   - Verify: Total equals the single class
-
-5. **Edge Case: Missing Directions**
-   - Input: Asymmetric direction/turn data
-   - Verify: Total includes all unique keys
-
-6. **Key Ordering Test**
-   - Input: 5 custom classes
-   - Verify: Total is the 6th key (last)
-   - Verify: `Object.keys(result)` ends with "Total"
-
-### Integration Tests
-
-**Test in api-rel controller**:
-
-1. Create video with ATR results
-2. Apply configuration with 3 custom classes
-3. Call `GET /videos/:uuid/results?configUuid=...`
-4. Verify response includes "Total" as last class
-5. Verify Total values equal sum of custom classes
-
-**Test in traffic-webapp**:
-
-1. Display video results with custom classes
-2. Verify "Total" tab appears last
-3. Verify Total chart shows aggregated data
-4. Test with both ATR and TMC videos
-
 ---
 
 ## Performance Considerations
 
-### Computational Complexity
+### Query Optimization
 
-**Current**: O(n × m) where:
+1. **Single Query for Minute Results**: Fetch all data in one query with JOINs (eliminates N+1)
+2. **Index Usage**: Existing `idx_videos_folder_recording` covers video filtering
+3. **In-Memory Aggregation**: TypeScript grouping is faster than SQL for complex JSON aggregation
+4. **Early Returns**: Skip processing if no videos/results found
 
-- n = number of detection labels
-- m = average nesting depth (2 for ATR, 3 for TMC)
+### Memory Management
 
-**After Adding Total**: O(n × m + c × m) where:
+- **Batch Size Estimate**:
+  - 10 videos × 60 minutes × 2KB/result = ~1.2MB
+  - 100 videos × 1440 minutes × 2KB/result = ~288MB
+  - Safe for typical studies (<50 videos)
+- **Future Optimization**: If studies exceed 100 videos, consider streaming or pagination
 
-- c = number of custom classes (2-7 per validation)
+### Database Load
 
-**Impact**: Minimal - additional O(c × m) is negligible
-
-- c ≤ 7 (max custom classes)
-- m ≤ 3 (max nesting depth)
-- Total iteration: ~21 operations per minute result
-
-### Memory Impact
-
-**Additional Memory**: One new key per transformed result
-
-- ATR Total: ~100 bytes (lanes object)
-- TMC Total: ~500 bytes (directions/turns object)
-- Per minute result: negligible
-- For 60 minutes: ~6-30 KB additional
-
-**Conclusion**: No performance concerns
+- **Single study query**: O(1)
+- **Single video query**: O(folders) - typically small
+- **Single minute results query**: O(total_minutes) - most expensive
+- **Total queries**: 3 (no N+1 problems)
 
 ---
 
-## Backward Compatibility
+## Testing Strategy (Recommendations Only - Not Implemented)
 
-### Changes Are Additive Only
+### Unit Test Cases
 
-✅ **No Breaking Changes**:
+1. **Basic Functionality**
+   - Single video, 1-minute grouping
+   - Multiple videos, 15-minute grouping
+   - TMC vs ATR aggregation
 
-- Existing custom classes remain unchanged
-- Existing API response structure preserved
-- "Total" is a NEW key (optional to consume)
+2. **Time Normalization**
+   - Videos with different recordingStartedAt align correctly
+   - Verify bucket boundaries (e.g., 2:00 PM, 2:15 PM, 2:30 PM)
+   - Handle midnight boundary crossing
 
-✅ **Frontend Compatibility**:
+3. **Edge Cases**
+   - Study not found (expect error)
+   - No COMPLETED videos (expect empty array)
+   - Mix of videos with/without recordingStartedAt
+   - Single minute spanning multiple buckets (shouldn't happen)
 
-- Old frontend: Ignores "Total" key (no errors)
-- New frontend: Displays "Total" as last tab
+4. **Aggregation Accuracy**
+   - Verify TMC turning movements sum correctly
+   - Verify ATR lane counts sum correctly
+   - Check contributingVideos array accuracy
 
-✅ **Database Compatibility**:
+### Integration Test
 
-- No schema changes required
-- Raw results in database unchanged
-- Transformation happens at runtime
+```typescript
+// Example test structure (not implemented)
+describe("getGroupedMinuteResultsByStudyUuid", () => {
+  it("should aggregate TMC results across multiple videos", async () => {
+    // Setup: Create study with 3 videos at different times
+    // Insert minute results with known values
+    // Call method with 15-minute grouping
+    // Assert: Verify bucket times, aggregated counts, video attribution
+  });
+});
+```
 
 ---
 
-## Implementation Checklist
-
-### Pre-Implementation
+## Migration Requirements
 
-- [x] Analyze current transformation logic
-- [x] Identify exact insertion point (line 312)
-- [x] Verify `_deepMergeNumericData()` handles both ATR/TMC
-- [x] Confirm JavaScript key ordering guarantees
+**No database migrations needed** - all existing schema supports this feature:
 
-### Implementation Phase
+- `video.recordingStartedAt` exists (migration 20251020225758)
+- `video.status` exists
+- Indexes on folder/recording relationships exist
+- Study → Folder → Video relationships exist
 
-- [ ] Add `_createTotalClass()` helper method after line 350
-- [ ] Add "Total" class insertion after line 312 in `applyConfigurationToNestedStructure()`
-- [ ] Add JSDoc comments for new method
-- [ ] Verify TypeScript compilation: `npm run build`
+---
 
-### Testing Phase
+## Implementation Order
 
-- [ ] Write unit tests for `_createTotalClass()`
-- [ ] Test ATR format (lane-based totals)
-- [ ] Test TMC format (direction/turn totals)
-- [ ] Test edge cases (empty, single class, missing keys)
-- [ ] Test key ordering (Total is last)
-- [ ] Run all tests: `npm test`
+1. **Add Interfaces** (lines 10-69 in VideoMinuteResultDAO.ts)
+   - `IStudyTimeGroupResult`
+   - `IGroupedStudyResponse`
 
-### Integration Phase
+2. **Add Helper Method** (before existing private methods)
+   - `formatAbsoluteTimeLabel(startTime: Date, endTime: Date): string`
 
-- [ ] Build knex-rel: `npm run build`
-- [ ] Test in api-rel: `npm run start:dev`
-- [ ] Call `/videos/:uuid/results` endpoint with ATR video
-- [ ] Call `/videos/:uuid/results` endpoint with TMC video
-- [ ] Verify "Total" appears in response as last class
-- [ ] Verify Total values are correct sums
+3. **Add Main Method** (after `getGroupedMinuteResultsByVideoUuid`, around line 479)
+   - `getGroupedMinuteResultsByStudyUuid(studyUuid, groupingMinutes)`
+   - Follow 5-step logic outlined above
 
-### Frontend Integration (Separate Task)
+4. **Export Interfaces** (at end of file)
+   - Export new interfaces for use in API layer
 
-- [ ] Update traffic-webapp to display "Total" tab
-- [ ] Position "Total" tab as last tab
-- [ ] Render Total data in charts/tables
-- [ ] Test with both ATR and TMC videos
+5. **Update Package**
+   - `npm run build` to verify TypeScript compilation
+   - No DAO export changes needed (class already exported)
 
 ---
 
-## Code Changes Summary
-
-### File 1: `knex-rel/src/dao/report-configuration/report-configuration.dao.ts`
+## API Integration Notes (For Future Work)
 
-**Location 1: After Line 312 (Inside `applyConfigurationToNestedStructure()`)**
+### Suggested API Endpoint
 
-```typescript
-// Lines 299-312: Existing iteration through detection labels
-for (const [detectionLabel, nestedData] of Object.entries(vehiclesStructure)) {
-  const customClassName = detectionToCustomClass[detectionLabel];
-  if (!customClassName) {
-    continue;
-  }
-  result[customClassName] = this._deepMergeNumericData(
-    result[customClassName],
-    nestedData,
-  );
-}
-
-// NEW CODE: Add "Total" class that aggregates all custom classes
-result["Total"] = this._createTotalClass(result);
-
-return result;
+```
+GET /api/studies/:studyUuid/minute-results?grouping=15
 ```
 
-**Location 2: After Line 350 (New Private Method)**
-
-```typescript
-/**
- * Create "Total" class by aggregating all custom vehicle classes
- *
- * Sums all custom class counts across their nested structures.
- * Works for both ATR (lane-based) and TMC (direction/turn-based) formats.
- *
- * @param customClassesData - Transformed custom classes structure
- *                            Example ATR: { "Light": { "0": 45, "1": 50 }, "Heavy": { "0": 10 } }
- *                            Example TMC: { "Light": { "NORTH": { "straight": 10 } }, ... }
- * @returns Aggregated totals matching the same nested structure
- *          Example ATR: { "0": 55, "1": 50 }
- *          Example TMC: { "NORTH": { "straight": 10 }, ... }
- */
-private _createTotalClass(customClassesData: Record<string, any>): any {
-    let total: any = {};
+### Response Format
 
-    // Iterate through all custom classes and merge their data
-    for (const [className, nestedData] of Object.entries(customClassesData)) {
-        total = this._deepMergeNumericData(total, nestedData);
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "absoluteTime": "2024-10-26T14:30:00.000Z",
+      "groupIndex": 0,
+      "label": "Oct 26, 2024: 2:30 PM - 2:44 PM",
+      "results": {
+        /* aggregated TMC/ATR data */
+      },
+      "minuteCount": 45,
+      "videoCount": 3,
+      "contributingVideos": ["uuid1", "uuid2", "uuid3"]
     }
-
-    return total;
+  ],
+  "groupingMinutes": 15,
+  "study": {
+    "uuid": "study-uuid",
+    "name": "Downtown Intersection Study",
+    "type": "TMC",
+    "status": "COMPLETE"
+  },
+  "videoCount": 3,
+  "dateRange": {
+    "earliest": "2024-10-26T14:00:00.000Z",
+    "latest": "2024-10-26T16:30:00.000Z"
+  }
 }
 ```
 
 ---
 
-## Validation Plan
-
-### Manual Testing Checklist
-
-**Test 1: ATR Video (2 Custom Classes)**
-
-- [ ] Create configuration: "Light" (FHWA 1-3), "Heavy" (FHWA 4-13)
-- [ ] Upload ATR video with mixed vehicle types
-- [ ] Process video and get results
-- [ ] Verify "Light" shows cars/motorcycles per lane
-- [ ] Verify "Heavy" shows trucks/buses per lane
-- [ ] Verify "Total" shows sum of Light + Heavy per lane
-- [ ] Verify "Total" is last key in vehicles object
-
-**Test 2: TMC Video (3 Custom Classes)**
-
-- [ ] Create configuration: "Cars", "Trucks", "Buses"
-- [ ] Upload TMC video with turning movements
-- [ ] Process video and get results
-- [ ] Verify each class shows direction/turn breakdown
-- [ ] Verify "Total" shows sum across all classes
-- [ ] Verify NORTH/straight in Total = sum of all classes' NORTH/straight
-- [ ] Verify "Total" is last key in vehicles object
-
-**Test 3: Edge Cases**
-
-- [ ] Video with no vehicles detected (empty Total)
-- [ ] Video with single custom class (Total equals that class)
-- [ ] Video with asymmetric turns (Light has left, Heavy doesn't)
-- [ ] Configuration with 7 custom classes (max allowed)
+## Risks & Mitigation
 
-**Test 4: Grouped Results (Multiple Minutes)**
-
-- [ ] Get grouped results with grouping=15
-- [ ] Verify each timeGroup has "Total" class
-- [ ] Verify "Total" sums correctly across aggregated minutes
-- [ ] Verify ordering preserved in all timeGroups
+| Risk                                | Impact                      | Mitigation                                           |
+| ----------------------------------- | --------------------------- | ---------------------------------------------------- |
+| Videos without recordingStartedAt   | Cannot normalize time       | Exclude from aggregation, log warning                |
+| Large studies (100+ videos)         | Memory/performance issues   | Document limit, add pagination in future             |
+| Type inconsistency (video vs study) | Wrong aggregation logic     | Use study.type as source of truth                    |
+| Missing duration_seconds            | Inaccurate dateRange.latest | Calculate from last minute_number                    |
+| Timezone confusion                  | Incorrect time labels       | Use UTC internally, format in user timezone (future) |
+| Concurrent video processing         | Incomplete aggregation      | Document that method shows COMPLETED videos only     |
 
 ---
 
-## Risks & Mitigations
-
-### Risk 1: Key Ordering Not Guaranteed
-
-**Risk**: JavaScript object keys might not preserve insertion order
-
-**Likelihood**: Very Low (ES2015+ guarantees string key order)
-
-**Mitigation**:
-
-- Add unit test to verify `Object.keys(result)` ends with "Total"
-- If ordering fails, use explicit ordering array in frontend
-
-### Risk 2: Performance Degradation
-
-**Risk**: Additional aggregation adds processing time
+## Pattern Compliance Checklist
 
-**Likelihood**: Very Low (O(c × m) is negligible)
-
-**Mitigation**:
-
-- Benchmark transformation time before/after
-- If impact > 10ms, consider caching Total class
-
-### Risk 3: Frontend Breaks on Unknown Class
-
-**Risk**: Old frontend version throws error on "Total" key
-
-**Likelihood**: Very Low (key is additive, not breaking)
-
-**Mitigation**:
-
-- "Total" is just another custom class name
-- Frontend already iterates dynamic class names
-- No special handling needed
-
-### Risk 4: Incorrect Aggregation Logic
-
-**Risk**: `_deepMergeNumericData()` doesn't handle all cases
-
-**Likelihood**: Low (method already tested for custom class merging)
-
-**Mitigation**:
-
-- Comprehensive unit tests for edge cases
-- Manual validation with real ATR/TMC videos
-- Use existing, battle-tested `_deepMergeNumericData()`
-
----
-
-## Alternative Approaches Considered
-
-### Alternative 1: Add "Total" in Frontend
-
-**Approach**: Calculate "Total" in traffic-webapp instead of backend
-
-**Pros**:
-
-- No backend changes required
-- Frontend controls display logic
-
-**Cons**:
-
-- Duplicates logic across frontend
-- Inconsistent if API consumed elsewhere
-- Cannot use "Total" in backend reports/exports
-
-**Decision**: ❌ Rejected - Backend is single source of truth
-
-### Alternative 2: Add "Total" as Separate Field
-
-**Approach**: Add `results.totalClass` instead of `results.vehicles["Total"]`
-
-**Pros**:
-
-- Clearer separation of concerns
-- No risk of key ordering issues
-
-**Cons**:
-
-- Inconsistent with custom class structure
-- Frontend needs special handling
-- Breaks uniform class iteration logic
-
-**Decision**: ❌ Rejected - Keep "Total" as vehicle class for uniformity
-
-### Alternative 3: Make "Total" Configurable
-
-**Approach**: Add `includeTotalClass: boolean` to report configuration
-
-**Pros**:
-
-- User control over Total display
-- Backward compatible (default false)
-
-**Cons**:
-
-- Adds complexity to configuration
-- Not needed (Total is always useful)
-- Extra validation logic
-
-**Decision**: ❌ Rejected - Always include "Total" (KISS principle)
+- ✅ **DAO Pattern**: Method follows existing DAO patterns (async, returns typed response)
+- ✅ **Interface Naming**: `IGroupedStudyResponse`, `IStudyTimeGroupResult` (PascalCase with I prefix)
+- ✅ **UUID Usage**: Uses study.uuid for external API, study.id internally
+- ✅ **Performance**: Single query for minute results (eliminates N+1)
+- ✅ **Error Handling**: Throws errors for missing study, returns empty for no data
+- ✅ **Type Safety**: All interfaces properly typed, no `any` in return types
+- ✅ **Code Reuse**: Leverages existing aggregation methods
+- ✅ **Naming**: `getGroupedMinuteResultsByStudyUuid` follows existing conventions
 
 ---
 
-## Success Criteria
-
-### Implementation Success
-
-✅ TypeScript compiles without errors
-✅ `npm run build` succeeds in knex-rel
-✅ All existing unit tests pass
-✅ New unit tests pass (Total class logic)
+## Files Modified
 
-### Functional Success
+### knex-rel/src/dao/VideoMinuteResultDAO.ts
 
-✅ ATR videos show "Total" with correct lane sums
-✅ TMC videos show "Total" with correct direction/turn sums
-✅ "Total" appears as LAST class in all responses
-✅ Edge cases handled (empty, single class, missing keys)
+**Changes**:
 
-### Integration Success
+- Add `IStudyTimeGroupResult` interface (after line 48)
+- Add `IGroupedStudyResponse` interface (after `IStudyTimeGroupResult`)
+- Add `formatAbsoluteTimeLabel()` private method (before line 703)
+- Add `getGroupedMinuteResultsByStudyUuid()` public method (after line 479)
+- Export new interfaces at end of file
 
-✅ API endpoint returns "Total" in response
-✅ Grouped results include "Total" in each timeGroup
-✅ No breaking changes to existing API consumers
-✅ Frontend displays "Total" tab correctly (separate task)
+**Lines Added**: ~200 lines
+**Pattern Compliance**: 100%
 
 ---
 
-## Timeline Estimate
+## Validation Checklist
 
-### Backend Implementation (knex-rel)
+Before implementation:
 
-- Code changes: 30 minutes
-- Unit tests: 1 hour
-- Build & test: 15 minutes
-- **Total: ~2 hours**
+- [ ] Confirm study.type values match video.videoType enum ('TMC' | 'ATR')
+- [ ] Verify recordingStartedAt is stored in UTC (migration confirms TIMESTAMPTZ)
+- [ ] Check if duration_seconds is reliably populated
+- [ ] Review existing aggregation methods for edge cases
 
-### Integration Testing (api-rel)
+After implementation:
 
-- Manual testing with ATR video: 30 minutes
-- Manual testing with TMC video: 30 minutes
-- Edge case validation: 30 minutes
-- **Total: ~1.5 hours**
-
-### Frontend Integration (traffic-webapp - Separate)
-
-- Display "Total" tab: 1 hour
-- Chart/table rendering: 1 hour
-- Testing both video types: 1 hour
-- **Total: ~3 hours**
-
-**Overall Estimate: ~6.5 hours** (Backend: 3.5 hours, Frontend: 3 hours)
+- [ ] Test with TMC study (multiple videos, 15-minute grouping)
+- [ ] Test with ATR study (multiple videos, 60-minute grouping)
+- [ ] Test with study containing no COMPLETED videos
+- [ ] Test with study where some videos lack recordingStartedAt
+- [ ] Verify time bucket boundaries align to grouping interval
+- [ ] Check memory usage with 50-video study
+- [ ] Run `npm run build` - confirm no TypeScript errors
+- [ ] Run `npm test` - confirm existing tests still pass
 
 ---
 
 ## Summary
 
-### What Changes
-
-✅ **ADD**: `_createTotalClass()` private method in ReportConfigurationDAO
-✅ **ADD**: `result["Total"] = ...` line after custom class transformation
-✅ **ADD**: Unit tests for Total class aggregation
-
-### What Stays the Same
-
-✅ Database schema (no migrations)
-✅ Existing custom classes (no modifications)
-✅ API response structure (additive only)
-✅ `_deepMergeNumericData()` helper (reused, not changed)
-
-### Key Benefits
-
-✅ Unified "Total" view across all custom classes
-✅ Consistent with existing transformation architecture
-✅ No breaking changes (backward compatible)
-✅ Minimal performance impact (< 1ms per minute result)
-✅ Reuses existing, tested aggregation logic
-
-**Ready for Implementation** - Plan is complete with exact code locations, logic, edge cases, and validation strategy.
-
----
-
-## Files to Modify
-
-### knex-rel/src/dao/report-configuration/report-configuration.dao.ts
-
-- **Line 312**: Add `result["Total"] = this._createTotalClass(result);`
-- **After Line 350**: Add `_createTotalClass()` private method
-
-### knex-rel/src/dao/report-configuration/report-configuration.dao.test.ts (New File)
-
-- Create unit tests for Total class aggregation
-- Test ATR format, TMC format, edge cases, key ordering
-
----
-
-## Pattern Compliance Summary
-
-### Database Patterns ✅
-
-- No database changes required (transformation only)
-- Follows DAO pattern (logic in ReportConfigurationDAO)
-- No new migrations needed
-
-### Code Patterns ✅
-
-- Reuses existing `_deepMergeNumericData()` helper
-- Follows private method naming convention (`_methodName`)
-- Maintains nested structure consistency
-- Preserves key ordering via insertion order
-
-### Performance Patterns ✅
-
-- O(c × m) additional complexity (negligible)
-- No N+1 queries (transformation in memory)
-- No database roundtrips
-- Minimal memory overhead (~500 bytes per result)
-
----
-
-## Next Steps
+This plan adds study-level aggregation with **zero database changes**, reusing 100% of existing schema and aggregation logic. Key innovation is SQL-based time normalization using `recordingStartedAt` to convert video-relative minute offsets to absolute wall-clock times, then grouping in TypeScript for flexibility.
 
-1. **Implement** `_createTotalClass()` method in ReportConfigurationDAO
-2. **Add** Total class insertion after line 312
-3. **Write** unit tests for all edge cases
-4. **Build** knex-rel package and verify compilation
-5. **Test** with real ATR and TMC videos in api-rel
-6. **Validate** key ordering and correct aggregation
-7. **Document** changes (if needed)
-8. **Coordinate** with frontend team for Total tab display
+**Implementation Effort**: ~200 lines of TypeScript, ~3-4 hours
+**Risk Level**: Low (no schema changes, proven aggregation logic)
+**Performance**: Good (single query, in-memory aggregation, indexed lookups)