@trafficgroup/knex-rel 0.1.5 → 0.1.6

package/plan.md

@@ -1,806 +1,837 @@
-# Missing DAO Methods Implementation Plan
+# Total Vehicle Class Implementation Plan
 
 ## Executive Summary
 
-This plan details the implementation of 5 missing DAO methods across CameraDAO and VideoDAO that are currently being called from api-rel services. All methods have been analyzed for call patterns, data flow, and database requirements.
+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**:
 
-## Schema Analysis
+- 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()`
 
-### Tables Involved
+---
 
-**cameras**
+## Current Architecture Analysis
 
-```sql
-id: SERIAL PRIMARY KEY
-uuid: UUID NOT NULL UNIQUE (indexed)
-name: VARCHAR(100) NOT NULL
-longitude: DECIMAL(10,7) NOT NULL
-latitude: DECIMAL(10,7) NOT NULL
-created_at: TIMESTAMP
-updated_at: TIMESTAMP
-INDEX: (uuid)
-INDEX: (longitude, latitude)
-```
+### Data Flow
 
-**video**
-
-```sql
-id: SERIAL PRIMARY KEY
-uuid: UUID NOT NULL UNIQUE
-folderId: INTEGER NOT NULL REFERENCES folders(id)
-cameraId: INTEGER NULL REFERENCES cameras(id) ON DELETE SET NULL
-name: VARCHAR
-videoLocation: VARCHAR
-status: VARCHAR (QUEUED|PROCESSING|COMPLETED|FAILED|PENDING)
-... (additional fields)
-INDEX: (cameraId)
 ```
+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
 
-**folders**
+**ATR Format (Lane-based)**:
 
-```sql
-id: SERIAL PRIMARY KEY
-uuid: UUID NOT NULL UNIQUE
-name: VARCHAR
-cameraId: INTEGER NULL REFERENCES cameras(id) ON DELETE SET NULL
-INDEX: (cameraId)
+```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)**:
 
-## Method 1: CameraDAO.getAllWithSearch()
+```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"
+}
+```
 
-### Call Analysis
+**After Custom Class Transformation** (2 custom classes: "Light" and "Heavy"):
 
-**Location**: `api-rel/src/service/camera/camera.service.ts:274`
+```json
+{
+  "vehicles": {
+    "Light": { "NORTH": { "straight": 10, "left": 5 }, ... },
+    "Heavy": { "NORTH": { "straight": 5, "left": 1 }, ... }
+  }
+}
+```
 
-**Method Signature**:
+**After Total Addition** (desired output):
 
-```typescript
-async getAllWithSearch(page: number, limit: number, name?: string): Promise<IDataPaginator<ICamera>>
+```json
+{
+  "vehicles": {
+    "Light": { "NORTH": { "straight": 10, "left": 5 }, ... },
+    "Heavy": { "NORTH": { "straight": 5, "left": 1 }, ... },
+    "Total": { "NORTH": { "straight": 15, "left": 6 }, ... }  // Sum of all classes
+  }
+}
 ```
 
-**Called From**: CameraService.getAllWithSearch()
+---
 
-- **Parameters**: page, limit, name (optional string for search)
-- **Return Value**: IDataPaginator<ICamera> - used to map to CameraDTO[]
-- **Purpose**: Filter cameras by name with pagination support
+## Implementation Location
 
-**Data Flow**:
+### File: `knex-rel/src/dao/report-configuration/report-configuration.dao.ts`
 
-```
-API Request → CameraService.getAllWithSearch(page, limit, name)
-  → CameraDAO.getAllWithSearch(page, limit, name)
-  → Returns IDataPaginator<ICamera>
-  → Service maps to CameraDTO[] (exposes UUID, hides ID)
-  → API Response
-```
+**Method to Modify**: `applyConfigurationToNestedStructure()` (Lines 273-315)
 
-### Implementation Requirements
+**Current Implementation**:
 
-**SQL Query**:
+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)
 
-```sql
--- Count query
-SELECT COUNT(*) as count FROM cameras WHERE name ILIKE '%search%'
+**Where to Add "Total"**: AFTER line 312, BEFORE return statement (Line 314)
 
--- Data query
-SELECT * FROM cameras
-WHERE name ILIKE '%search%'
-LIMIT ? OFFSET ?
-```
+---
 
-**Key Details**:
+## Detailed Implementation Plan
 
-- Use ILIKE for case-insensitive search (PostgreSQL)
-- Search is optional (if name undefined/null, return all)
-- Use '%search%' pattern for partial matching
-- Follow existing getAll() pattern from camera.dao.ts:34-50
+### Step 1: Add "Total" Class After Custom Class Transformation
 
-**Performance Considerations**:
+**Location**: `ReportConfigurationDAO.applyConfigurationToNestedStructure()` (After line 312)
 
-- Index on name column NOT currently exists - consider adding
-- ILIKE with leading wildcard prevents index usage
-- For now, acceptable for camera table (likely small dataset)
+**Logic**:
 
----
+```typescript
+// After line 312 (end of detection label iteration)
+// Add "Total" class that aggregates all custom classes
+
+result["Total"] = this._createTotalClass(result);
 
-## Method 2: CameraDAO.getVideosByCamera()
+return result;
+```
 
-### Call Analysis
+### Step 2: Implement `_createTotalClass()` Helper Method
 
-**Location**: `api-rel/src/service/camera/camera.service.ts:308`
+**Location**: Add new private method in `ReportConfigurationDAO` class (After line 350)
 
 **Method Signature**:
 
 ```typescript
-async getVideosByCamera(cameraId: number, page: number, limit: number): Promise<IDataPaginator<IVideo>>
+private _createTotalClass(customClassesData: Record<string, any>): any
 ```
 
-**Called From**: CameraService.getVideosByCamera()
+**Implementation**:
 
-- **Parameters**: cameraId (internal numeric ID), page, limit
-- **Return Value**: IDataPaginator with video data PLUS folder information
-- **Purpose**: Get all videos associated with a specific camera (paginated)
-
-**Data Flow**:
+```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 = {};
+
+    // 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));
+    }
 
-```
-API Request (cameraUuid) → CameraService.getVideosByCamera(cameraUuid, page, limit)
-  → Get camera by UUID to obtain ID (line 302)
-  → CameraDAO.getVideosByCamera(camera.id, page, limit)
-  → Returns IDataPaginator<IVideo> with folder data
-  → Service maps to VideoWithFolderDTO[] (line 311-312)
-  → API Response
+    return total;
+}
 ```
 
-**Critical Detail**: Service expects folder data in response (line 312: mapToVideoWithFolderDTO)
+**Explanation**:
 
-### Implementation Requirements
+- 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 `{}`)
 
-**SQL Query** (must JOIN with folders):
+---
 
-```sql
--- Count query
-SELECT COUNT(*) as count
-FROM video v
-WHERE v.cameraId = ?
+## Key Ordering Strategy
 
--- Data query with folder JOIN
-SELECT v.*, to_jsonb(f.*) as folder
-FROM video v
-INNER JOIN folders f ON v.folderId = f.id
-WHERE v.cameraId = ?
-LIMIT ? OFFSET ?
-```
+### Ensuring "Total" Appears Last
 
-**Key Details**:
+JavaScript object key ordering is preserved in modern engines (ES2015+) when:
 
-- MUST include folder data (use to_jsonb like VideoDAO.getById:21)
-- Filter by cameraId (indexed)
-- Follow VideoDAO.getAll() pattern for folder JOIN (lines 50-59)
-- Return IDataPaginator<IVideo> with folder field populated
+1. String keys are added in insertion order
+2. Keys are enumerated via `Object.entries()`, `Object.keys()`, `for...in`
 
-**Performance Considerations**:
+**Our Implementation**:
 
-- cameraId already indexed (migration 20250911000000_migration.ts:20)
-- JOIN with folders is necessary for DTO mapping
-- Consider ORDER BY created_at DESC for chronological listing
+```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
+}
 
-## Method 3: VideoDAO.bulkUpdateCamera()
+// NEW: Add "Total" LAST (after all custom classes)
+result["Total"] = this._createTotalClass(result);
 
-### Call Analysis
+// Line 314: Return result (Total is last key)
+return result;
+```
 
-**Location 1**: `api-rel/src/service/camera/camera.service.ts:364`
-**Location 2**: `api-rel/src/service/video/video.service.ts:34`
-**Location 3**: `api-rel/src/service/folder/folder.service.ts:96`
+**Why This Works**:
 
-**Method Signature**:
+- 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
 
-```typescript
-async bulkUpdateCamera(videoIds: number[], cameraId: number | null, trx?: Knex.Transaction): Promise<number>
-```
+---
 
-**Call Patterns**:
+## ATR vs TMC Behavior
 
-**Pattern 1 - CameraService.bulkAssignToVideos() (line 364)**:
+### ATR (Lane-Based Totals)
 
-- Context: Assigning camera to multiple videos
-- Parameters: videoIds (array of numeric IDs), camera.id (number)
-- Transaction: NO transaction passed (relies on DAO atomicity)
-- Return: updatedCount used for logging (line 365)
+**Input Structure**:
+
+```json
+{
+  "Light": { "0": 45, "1": 50 },
+  "Heavy": { "0": 10, "1": 8 }
+}
+```
 
-**Pattern 2 - VideoService.bulkUpdateCamera() (line 34)**:
+**Total Output**:
 
-- Context: Bulk update within service transaction
-- Parameters: videoIds, cameraId (can be null), trx (REQUIRED)
-- Transaction: YES - passed from service-level transaction (line 15)
-- Return: updatedCount used for result tracking (line 54)
-- Error Handling: Transaction rollback on failure (line 58)
+```json
+{
+  "Total": { "0": 55, "1": 58 } // Sum per lane
+}
+```
 
-**Pattern 3 - FolderService.cascadeUpdateVideosCamera() (line 96)**:
+**Calculation**:
 
-- Context: Cascading camera assignment from folder to videos
-- Parameters: videoIds, cameraId (can be null), trx (OPTIONAL)
-- Transaction: OPTIONAL - may be passed from folder update (line 86)
-- Return: updatedCount for cascade logging (line 59)
+- Lane "0": 45 (Light) + 10 (Heavy) = 55
+- Lane "1": 50 (Light) + 8 (Heavy) = 58
 
-### Implementation Requirements
+**Alternative (Use existing `lane_counts`)**:
 
-**SQL Query**:
+The ATR structure ALREADY has `lane_counts` at the top level:
 
-```sql
-UPDATE video
-SET cameraId = ?, updated_at = NOW()
-WHERE id = ANY(?)
-RETURNING id
+```json
+{
+  "vehicles": { "Light": {...}, "Heavy": {...} },
+  "lane_counts": { "0": 55, "1": 58 }  // Already calculated!
+}
 ```
 
-**Key Details**:
+**Decision**: For ATR, we can EITHER:
 
-- Accept optional transaction parameter (trx?: Knex.Transaction)
-- Use transaction if provided, otherwise use default connection
-- Update cameraId (can be null for unassignment)
-- Update updated_at timestamp
-- Return count of updated rows (number)
-- Use whereIn() for array parameter
+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)
 
-**Transaction Handling**:
+**Recommendation**: Use Option A (sum custom classes) for consistency with TMC, even though Option B is technically available.
 
-```typescript
-const query = trx || this._knex;
-const result = await query("video")
-  .whereIn("id", videoIds)
-  .update({ cameraId, updated_at: query.fn.now() })
-  .returning("id");
-return result.length;
+### TMC (Direction/Turn-Based Totals)
+
+**Input Structure**:
+
+```json
+{
+  "Light": {
+    "NORTH": { "straight": 10, "left": 5, "right": 3 },
+    "SOUTH": { "straight": 8, "left": 2, "right": 4 }
+  },
+  "Heavy": {
+    "NORTH": { "straight": 5, "left": 1, "right": 0 },
+    "SOUTH": { "straight": 2, "left": 0, "right": 1 }
+  }
+}
 ```
 
-**Performance Considerations**:
+**Total Output**:
 
-- Bulk update is efficient (single query)
-- videoIds array should be validated (non-empty)
-- Consider max batch size limit (100-1000 videos)
-- No index needed on id (primary key)
+```json
+{
+  "Total": {
+    "NORTH": { "straight": 15, "left": 6, "right": 3 },
+    "SOUTH": { "straight": 10, "left": 2, "right": 5 }
+  }
+}
+```
 
-**Error Handling**:
+**Calculation**:
 
-- If transaction fails in caller, rollback handles cleanup
-- Return 0 if videoIds is empty array
-- Let Knex errors propagate to service layer
+- NORTH/straight: 10 (Light) + 5 (Heavy) = 15
+- NORTH/left: 5 (Light) + 1 (Heavy) = 6
+- SOUTH/straight: 8 (Light) + 2 (Heavy) = 10
+- etc.
 
 ---
 
-## Method 4: VideoDAO.getVideoIdsByFolderId()
+## Edge Cases & Validation
 
-### Call Analysis
+### Edge Case 1: Empty Data (No Vehicles)
 
-**Location 1**: `api-rel/src/service/folder/folder.service.ts:49`
-**Location 2**: `api-rel/src/service/folder/folder.service.ts:89`
-**Location 3**: `api-rel/src/service/folder/folder.service.ts:163`
-**Location 4**: `api-rel/src/service/video/video.service.ts:119`
+**Input**:
 
-**Method Signature**:
+```json
+{
+  "vehicles": {}
+}
+```
 
-```typescript
-async getVideoIdsByFolderId(folderId: number): Promise<number[]>
+**After Transformation**:
+
+```json
+{
+  "vehicles": {
+    "Light": {},
+    "Heavy": {},
+    "Total": {} // Empty object
+  }
+}
 ```
 
-**Call Patterns**:
+**Behavior**: `_createTotalClass()` returns empty object `{}`
 
-**Pattern 1 - FolderService.updateWithCameraCascade() (line 49)**:
+### Edge Case 2: Single Custom Class
 
-- Context: Get all videos in folder to cascade camera update
-- Parameters: existingFolder.id
-- Return: videoIds array used for cascading (line 52-57)
-- Transaction Context: Within folder update transaction
+**Input**:
 
-**Pattern 2 - FolderService.cascadeUpdateVideosCamera() (line 89)**:
+```json
+{
+  "vehicles": {
+    "AllVehicles": { "0": 100, "1": 95 }
+  }
+}
+```
 
-- Context: Get video IDs for bulk camera update
-- Parameters: folderId
-- Return: videoIds passed to bulkUpdateCamera (line 96)
-- Early return if empty array (line 91-93)
+**Output**:
 
-**Pattern 3 - FolderService.getVideoCascadeCount() (line 163)**:
+```json
+{
+  "vehicles": {
+    "AllVehicles": { "0": 100, "1": 95 },
+    "Total": { "0": 100, "1": 95 } // Same as single class
+  }
+}
+```
 
-- Context: Count videos that would be affected by cascade
-- Parameters: folder.id
-- Return: videoIds.length for count (line 164)
-- Read-only operation (no updates)
+**Behavior**: "Total" equals the single custom class (valid)
 
-**Pattern 4 - VideoService.getVideoIdsByFolderId() (line 119)**:
+### Edge Case 3: Missing Directions/Turns
 
-- Context: Get all video IDs in folder for cascade operations
-- Parameters: folderId
-- Return: number[] passed back to caller
-- Used for service-level cascade logic
+**Input** (TMC - Light has NORTH, Heavy only has SOUTH):
 
-### Implementation Requirements
+```json
+{
+  "Light": { "NORTH": { "straight": 10 } },
+  "Heavy": { "SOUTH": { "straight": 5 } }
+}
+```
 
-**SQL Query**:
+**Output**:
 
-```sql
-SELECT id FROM video WHERE folderId = ?
+```json
+{
+  "Total": {
+    "NORTH": { "straight": 10 },
+    "SOUTH": { "straight": 5 }
+  }
+}
 ```
 
-**Key Details**:
+**Behavior**: `_deepMergeNumericData()` handles missing keys gracefully (Lines 339-347)
 
-- Simple SELECT of id column only
-- Filter by folderId
-- Return array of numeric IDs: number[]
-- No pagination needed (cascade operations need ALL videos)
-- No JOIN needed (only IDs required)
+### Edge Case 4: Null/Undefined Values
 
-**Performance Considerations**:
+**Input**:
 
-- folderId should be indexed (check if exists)
-- Query is read-only, no locking needed
-- Could return large arrays (100s-1000s of videos per folder)
-- Consider ORDER BY id for consistency
+```json
+{
+  "Light": { "0": 10, "1": null },
+  "Heavy": { "0": 5 }
+}
+```
 
-**Return Value**:
+**Output**:
 
-```typescript
-const ids = await this._knex("video")
-  .where({ folderId })
-  .select("id")
-  .orderBy("id", "asc");
-return ids.map((row) => row.id);
+```json
+{
+  "Total": { "0": 15, "1": 0 } // null treated as 0
+}
 ```
 
+**Behavior**: `_deepMergeNumericData()` checks `typeof source === 'number'` (Line 330)
+
 ---
 
-## Method 5: VideoDAO.getVideosByCameraIdWithFolder()
+## Testing Strategy
 
-### Call Analysis
+### Unit Tests (to be created)
 
-**Location**: `api-rel/src/service/video/video.service.ts:77`
+**File**: `knex-rel/src/dao/report-configuration/report-configuration.dao.test.ts`
 
-**Method Signature**:
+**Test Cases**:
 
-```typescript
-async getVideosByCameraIdWithFolder(cameraId: number, page: number, limit: number): Promise<IDataPaginator<IVideo>>
-```
+1. **ATR: Total Class Aggregation**
+   - Input: 2 custom classes with lane counts
+   - Verify: Total sums all lanes correctly
+   - Verify: Total appears as last key
 
-**Called From**: VideoService.getVideosByCameraId()
+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
 
-- **Parameters**: cameraId (numeric ID), page, limit
-- **Return Value**: IDataPaginator<IVideo> - directly returned to caller
-- **Purpose**: Get paginated videos for a camera with folder info
+3. **Edge Case: Empty Vehicles**
+   - Input: No vehicle data
+   - Verify: Total is empty object `{}`
 
-**Data Flow**:
+4. **Edge Case: Single Custom Class**
+   - Input: 1 custom class
+   - Verify: Total equals the single class
 
-```
-API/Service Request → VideoService.getVideosByCameraId(cameraId, page, limit)
-  → VideoDAO.getVideosByCameraIdWithFolder(cameraId, page, limit)
-  → Returns IDataPaginator<IVideo>
-  → Service returns directly (line 77)
-```
+5. **Edge Case: Missing Directions**
+   - Input: Asymmetric direction/turn data
+   - Verify: Total includes all unique keys
 
-**Critical Detail**: Method name explicitly includes "WithFolder" - MUST JOIN folders
+6. **Key Ordering Test**
+   - Input: 5 custom classes
+   - Verify: Total is the 6th key (last)
+   - Verify: `Object.keys(result)` ends with "Total"
 
-### Implementation Requirements
+### Integration Tests
 
-**SQL Query**:
+**Test in api-rel controller**:
 
-```sql
--- Count query
-SELECT COUNT(*) as count
-FROM video v
-WHERE v.cameraId = ?
+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
 
--- Data query with folder JOIN
-SELECT v.*, to_jsonb(f.*) as folder
-FROM video v
-INNER JOIN folders f ON v.folderId = f.id
-WHERE v.cameraId = ?
-ORDER BY v.created_at DESC
-LIMIT ? OFFSET ?
-```
+**Test in traffic-webapp**:
 
-**Key Details**:
+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
 
-- IDENTICAL to CameraDAO.getVideosByCamera() implementation
-- Filter by cameraId
-- MUST include folder data via JOIN
-- Follow VideoDAO.getAll() JOIN pattern (lines 50-59)
-- Return IDataPaginator<IVideo>
+---
 
-**Performance Considerations**:
+## Performance Considerations
 
-- Same as Method 2 (getVideosByCamera)
-- cameraId indexed
-- Consider composite index on (cameraId, created_at) for sorting
+### Computational Complexity
 
-**Pattern Consistency**:
+**Current**: O(n × m) where:
 
-- This method duplicates CameraDAO.getVideosByCamera() logic
-- Both should use IDENTICAL query structure
-- Consider refactoring to shared private method in future
+- n = number of detection labels
+- m = average nesting depth (2 for ATR, 3 for TMC)
 
----
+**After Adding Total**: O(n × m + c × m) where:
 
-## Implementation Order
+- c = number of custom classes (2-7 per validation)
 
-### Phase 1: Simple Methods (No Dependencies)
+**Impact**: Minimal - additional O(c × m) is negligible
 
-1. **CameraDAO.getAllWithSearch()** - Standalone search method
-2. **VideoDAO.getVideoIdsByFolderId()** - Simple ID retrieval
+- c ≤ 7 (max custom classes)
+- m ≤ 3 (max nesting depth)
+- Total iteration: ~21 operations per minute result
 
-### Phase 2: Complex Query Methods (JOINs)
+### Memory Impact
 
-3. **CameraDAO.getVideosByCamera()** - JOIN with folders
-4. **VideoDAO.getVideosByCameraIdWithFolder()** - Same as #3, different DAO
+**Additional Memory**: One new key per transformed result
 
-### Phase 3: Transaction-Aware Methods
+- ATR Total: ~100 bytes (lanes object)
+- TMC Total: ~500 bytes (directions/turns object)
+- Per minute result: negligible
+- For 60 minutes: ~6-30 KB additional
 
-5. **VideoDAO.bulkUpdateCamera()** - Transaction support required
+**Conclusion**: No performance concerns
 
 ---
 
-## Database Indexing Recommendations
-
-### Existing Indexes (Already Present)
+## Backward Compatibility
 
-- cameras.uuid (migration 20250911000000_migration.ts:13)
-- cameras.(longitude, latitude) (migration 20250911000000_migration.ts:14)
-- video.cameraId (migration 20250911000000_migration.ts:20)
-- folders.cameraId (migration 20250911000000_migration.ts:26)
+### Changes Are Additive Only
 
-### Recommended New Indexes
+✅ **No Breaking Changes**:
 
-**Optional - cameras.name (for search optimization)**
+- Existing custom classes remain unchanged
+- Existing API response structure preserved
+- "Total" is a NEW key (optional to consume)
 
-```sql
-CREATE INDEX idx_cameras_name ON cameras(name);
-```
-
-- Benefits: Speeds up getAllWithSearch() ILIKE queries
-- Tradeoff: ILIKE with leading wildcard still can't use index fully
-- Decision: SKIP for now (camera table likely small)
+✅ **Frontend Compatibility**:
 
-**High Priority - video.folderId (for cascade operations)**
+- Old frontend: Ignores "Total" key (no errors)
+- New frontend: Displays "Total" as last tab
 
-```sql
-CREATE INDEX idx_video_folder_id ON video(folderId);
-```
+✅ **Database Compatibility**:
 
-- Benefits: Critical for getVideoIdsByFolderId() performance
-- Usage: Heavy usage in cascade operations
-- Decision: **CHECK IF EXISTS** - likely already present
+- No schema changes required
+- Raw results in database unchanged
+- Transformation happens at runtime
 
-**Optional - video.(cameraId, created_at) composite**
+---
 
-```sql
-CREATE INDEX idx_video_camera_created ON video(cameraId, created_at DESC);
-```
+## Implementation Checklist
 
-- Benefits: Optimizes sorted queries in getVideosByCameraIdWithFolder
-- Decision: SKIP for now (single column index sufficient)
+### Pre-Implementation
 
----
+- [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
 
-## Type Safety & Interfaces
+### Implementation Phase
 
-All methods already have proper TypeScript interfaces defined:
+- [ ] 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`
 
-**ICamera** - knex-rel/src/interfaces/camera/camera.interfaces.ts
+### Testing Phase
 
-- All fields present and correct
-- No modifications needed
+- [ ] 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`
 
-**IVideo** - knex-rel/src/interfaces/video/video.interfaces.ts
+### Integration Phase
 
-- Includes optional folder?: IFolder field (line 33)
-- Includes optional cameraId?: number field (line 8)
-- Supports all required fields
-- No modifications needed
+- [ ] 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
 
-**IDataPaginator<T>** - Used consistently across all methods
+### Frontend Integration (Separate Task)
 
-- success: boolean
-- data: T[]
-- page: number
-- limit: number
-- count: number
-- totalCount: number
-- totalPages: number
+- [ ] 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
 
 ---
 
-## Error Handling Patterns
+## Code Changes Summary
+
+### File 1: `knex-rel/src/dao/report-configuration/report-configuration.dao.ts`
 
-### Pattern 1: Search Methods (getAllWithSearch)
+**Location 1: After Line 312 (Inside `applyConfigurationToNestedStructure()`)**
 
 ```typescript
-// No try/catch in DAO
-// Let Knex errors propagate to service
-const result = await query...
-return result;
-```
+// 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,
+  );
+}
 
-### Pattern 2: Transaction Methods (bulkUpdateCamera)
+// NEW CODE: Add "Total" class that aggregates all custom classes
+result["Total"] = this._createTotalClass(result);
 
-```typescript
-// No try/catch in DAO
-// Let transaction rollback handle errors at service level
-const query = trx || this._knex;
-const result = await query...
-return result.length;
+return result;
 ```
 
-### Pattern 3: Simple Queries (getVideoIdsByFolderId)
+**Location 2: After Line 350 (New Private Method)**
 
 ```typescript
-// No try/catch needed
-// Direct Knex query with error propagation
-const ids = await this._knex...
-return ids.map(row => row.id);
+/**
+ * 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 = {};
+
+    // Iterate through all custom classes and merge their data
+    for (const [className, nestedData] of Object.entries(customClassesData)) {
+        total = this._deepMergeNumericData(total, nestedData);
+    }
+
+    return total;
+}
 ```
 
 ---
 
-## Code Pattern Examples
+## Validation Plan
 
-### Example 1: getAllWithSearch() Implementation
+### Manual Testing Checklist
 
-```typescript
-async getAllWithSearch(page: number, limit: number, name?: string): Promise<IDataPaginator<ICamera>> {
-    const offset = (page - 1) * limit;
+**Test 1: ATR Video (2 Custom Classes)**
 
-    let query = this._knex("cameras");
+- [ ] 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
 
-    // Apply search filter if name provided
-    if (name && name.trim().length > 0) {
-        query = query.where('name', 'ilike', `%${name.trim()}%`);
-    }
+**Test 2: TMC Video (3 Custom Classes)**
 
-    const [countResult] = await query.clone().count("* as count");
-    const totalCount = +countResult.count;
-    const cameras = await query.clone().limit(limit).offset(offset).orderBy('name', 'asc');
-
-    return {
-        success: true,
-        data: cameras,
-        page,
-        limit,
-        count: cameras.length,
-        totalCount,
-        totalPages: Math.ceil(totalCount / limit),
-    };
-}
-```
+- [ ] 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
 
-### Example 2: bulkUpdateCamera() Implementation
+**Test 3: Edge Cases**
 
-```typescript
-async bulkUpdateCamera(videoIds: number[], cameraId: number | null, trx?: Knex.Transaction): Promise<number> {
-    if (!videoIds || videoIds.length === 0) {
-        return 0;
-    }
+- [ ] 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)
 
-    const query = trx || this._knex;
+**Test 4: Grouped Results (Multiple Minutes)**
 
-    const result = await query('video')
-        .whereIn('id', videoIds)
-        .update({
-            cameraId: cameraId,
-            updated_at: query.fn.now()
-        })
-        .returning('id');
+- [ ] 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
 
-    return result.length;
-}
-```
+---
 
-### Example 3: getVideosByCamera() Implementation
+## Risks & Mitigations
 
-```typescript
-async getVideosByCamera(cameraId: number, page: number, limit: number): Promise<IDataPaginator<IVideo>> {
-    const offset = (page - 1) * limit;
-
-    const query = this._knex("video as v")
-        .innerJoin("folders as f", "v.folderId", "f.id")
-        .select("v.*", this._knex.raw("to_jsonb(f.*) as folder"))
-        .where("v.cameraId", cameraId);
-
-    const [countResult] = await query.clone().clearSelect().count("* as count");
-    const totalCount = +countResult.count;
-    const videos = await query.clone().limit(limit).offset(offset).orderBy('v.created_at', 'desc');
-
-    return {
-        success: true,
-        data: videos,
-        page,
-        limit,
-        count: videos.length,
-        totalCount,
-        totalPages: Math.ceil(totalCount / limit),
-    };
-}
-```
+### Risk 1: Key Ordering Not Guaranteed
 
-### Example 4: getVideoIdsByFolderId() Implementation
+**Risk**: JavaScript object keys might not preserve insertion order
 
-```typescript
-async getVideoIdsByFolderId(folderId: number): Promise<number[]> {
-    const rows = await this._knex('video')
-        .where({ folderId })
-        .select('id')
-        .orderBy('id', 'asc');
+**Likelihood**: Very Low (ES2015+ guarantees string key order)
 
-    return rows.map(row => row.id);
-}
-```
+**Mitigation**:
 
-### Example 5: getVideosByCameraIdWithFolder() Implementation
+- Add unit test to verify `Object.keys(result)` ends with "Total"
+- If ordering fails, use explicit ordering array in frontend
 
-```typescript
-async getVideosByCameraIdWithFolder(cameraId: number, page: number, limit: number): Promise<IDataPaginator<IVideo>> {
-    const offset = (page - 1) * limit;
-
-    const query = this._knex("video as v")
-        .innerJoin("folders as f", "v.folderId", "f.id")
-        .select("v.*", this._knex.raw("to_jsonb(f.*) as folder"))
-        .where("v.cameraId", cameraId);
-
-    const [countResult] = await query.clone().clearSelect().count("* as count");
-    const totalCount = +countResult.count;
-    const videos = await query.clone().limit(limit).offset(offset).orderBy('v.created_at', 'desc');
-
-    return {
-        success: true,
-        data: videos,
-        page,
-        limit,
-        count: videos.length,
-        totalCount,
-        totalPages: Math.ceil(totalCount / limit),
-    };
-}
-```
+### Risk 2: Performance Degradation
 
----
+**Risk**: Additional aggregation adds processing time
+
+**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
 
-## Migration Requirements
+**Risk**: Old frontend version throws error on "Total" key
 
-**No new migrations needed** - All schema changes already exist:
+**Likelihood**: Very Low (key is additive, not breaking)
 
-- cameras table: migration 20250911000000_migration.ts
-- video.cameraId column: migration 20250911000000_migration.ts:19
-- folders.cameraId column: migration 20250911000000_migration.ts:25
-- All indexes already created
+**Mitigation**:
 
-**Optional migration for performance**:
+- "Total" is just another custom class name
+- Frontend already iterates dynamic class names
+- No special handling needed
 
-- Check if video.folderId index exists (likely already present)
+### 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()`
 
 ---
 
-## Testing Strategy
+## Alternative Approaches Considered
 
-### Unit Tests Required
+### Alternative 1: Add "Total" in Frontend
 
-**CameraDAO.getAllWithSearch()**
+**Approach**: Calculate "Total" in traffic-webapp instead of backend
 
-- Test: Search with matching name (partial match)
-- Test: Search with no matches (empty result)
-- Test: Search with null/undefined name (return all)
-- Test: Pagination (page 1, page 2, etc.)
-- Test: Case insensitivity (ILIKE behavior)
+**Pros**:
 
-**CameraDAO.getVideosByCamera()**
+- No backend changes required
+- Frontend controls display logic
 
-- Test: Camera with videos (verify folder JOIN)
-- Test: Camera with no videos (empty result)
-- Test: Pagination with multiple pages
-- Test: Verify folder data structure in results
+**Cons**:
 
-**VideoDAO.bulkUpdateCamera()**
+- Duplicates logic across frontend
+- Inconsistent if API consumed elsewhere
+- Cannot use "Total" in backend reports/exports
 
-- Test: Update with cameraId (assignment)
-- Test: Update with null cameraId (unassignment)
-- Test: Update with transaction (commit)
-- Test: Update with transaction (rollback)
-- Test: Empty videoIds array (return 0)
-- Test: Invalid videoIds (non-existent IDs)
+**Decision**: ❌ Rejected - Backend is single source of truth
 
-**VideoDAO.getVideoIdsByFolderId()**
+### Alternative 2: Add "Total" as Separate Field
 
-- Test: Folder with videos (return IDs)
-- Test: Folder with no videos (empty array)
-- Test: Non-existent folderId (empty array)
-- Test: Large folder (100+ videos)
+**Approach**: Add `results.totalClass` instead of `results.vehicles["Total"]`
 
-**VideoDAO.getVideosByCameraIdWithFolder()**
+**Pros**:
 
-- Test: Camera with videos (verify folder JOIN)
-- Test: Camera with no videos (empty result)
-- Test: Pagination
-- Test: Verify folder data in results
-- Test: Null cameraId handling
+- Clearer separation of concerns
+- No risk of key ordering issues
 
----
+**Cons**:
 
-## Implementation Checklist
+- Inconsistent with custom class structure
+- Frontend needs special handling
+- Breaks uniform class iteration logic
 
-### Pre-Implementation
+**Decision**: ❌ Rejected - Keep "Total" as vehicle class for uniformity
 
-- [ ] Check if video.folderId index exists in database
-- [ ] Review existing DAO patterns in camera.dao.ts and video.dao.ts
-- [ ] Verify IDataPaginator structure in d.types.ts
+### Alternative 3: Make "Total" Configurable
 
-### Implementation Phase
+**Approach**: Add `includeTotalClass: boolean` to report configuration
 
-- [ ] Implement CameraDAO.getAllWithSearch()
-- [ ] Implement VideoDAO.getVideoIdsByFolderId()
-- [ ] Implement CameraDAO.getVideosByCamera()
-- [ ] Implement VideoDAO.getVideosByCameraIdWithFolder()
-- [ ] Implement VideoDAO.bulkUpdateCamera()
+**Pros**:
 
-### Testing Phase
+- User control over Total display
+- Backward compatible (default false)
 
-- [ ] Write unit tests for all 5 methods
-- [ ] Test transaction handling in bulkUpdateCamera
-- [ ] Test pagination edge cases (page 1, last page, beyond last page)
-- [ ] Test search with special characters (SQL injection prevention)
+**Cons**:
 
-### Integration Phase
+- Adds complexity to configuration
+- Not needed (Total is always useful)
+- Extra validation logic
 
-- [ ] Build knex-rel package: `npm run build`
-- [ ] Verify no TypeScript compilation errors
-- [ ] Test in api-rel: `npm run start:dev`
-- [ ] Verify all service methods work end-to-end
-- [ ] Test camera bulk assignment workflow
-- [ ] Test folder camera cascade workflow
+**Decision**: ❌ Rejected - Always include "Total" (KISS principle)
 
 ---
 
-## Risk Assessment
+## 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)
 
-### Low Risk
+### Functional Success
+
+✅ 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)
+
+### Integration Success
+
+✅ 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)
+
+---
 
-- getAllWithSearch() - Simple extension of getAll()
-- getVideoIdsByFolderId() - Straightforward SELECT query
+## Timeline Estimate
 
-### Medium Risk
+### Backend Implementation (knex-rel)
 
-- getVideosByCamera() - Requires correct JOIN syntax
-- getVideosByCameraIdWithFolder() - Same as above
+- Code changes: 30 minutes
+- Unit tests: 1 hour
+- Build & test: 15 minutes
+- **Total: ~2 hours**
 
-### High Risk
+### Integration Testing (api-rel)
 
-- bulkUpdateCamera() - Transaction handling complexity
-  - **Mitigation**: Carefully test both transaction and non-transaction paths
-  - **Mitigation**: Validate videoIds array before query
-  - **Mitigation**: Let service layer handle rollback logic
+- Manual testing with ATR video: 30 minutes
+- Manual testing with TMC video: 30 minutes
+- Edge case validation: 30 minutes
+- **Total: ~1.5 hours**
 
-### Performance Risks
+### Frontend Integration (traffic-webapp - Separate)
 
-- getVideoIdsByFolderId() could return large arrays (1000+ IDs)
-  - **Mitigation**: Acceptable for cascade operations
-  - **Mitigation**: Ensure folderId index exists for speed
-- getAllWithSearch() ILIKE with leading wildcard is slow
-  - **Mitigation**: Acceptable for small camera table
-  - **Mitigation**: Consider full-text search if needed later
+- 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)
 
 ---
 
 ## Summary
 
-All 5 missing methods have been thoroughly analyzed:
+### 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
 
-- **Call patterns documented** from 8 different service method locations
-- **Data flow mapped** from API → Service → DAO → Database
-- **SQL queries designed** with proper JOINs, indexes, and performance
-- **Transaction handling** specified for bulkUpdateCamera()
-- **Type safety verified** - all interfaces already correct
-- **No migrations needed** - schema already complete
-- **Implementation order prioritized** - simple to complex
-- **Testing strategy defined** - 25+ test cases identified
-- **Risk assessment completed** - mitigations specified
+✅ 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** - All patterns follow existing DAO conventions in codebase.
+**Ready for Implementation** - Plan is complete with exact code locations, logic, edge cases, and validation strategy.
 
 ---
 
 ## Files to Modify
 
-### knex-rel/src/dao/camera/camera.dao.ts
+### knex-rel/src/dao/report-configuration/report-configuration.dao.ts
 
-- Add method: `getAllWithSearch(page, limit, name?)`
-- Add method: `getVideosByCamera(cameraId, page, limit)`
+- **Line 312**: Add `result["Total"] = this._createTotalClass(result);`
+- **After Line 350**: Add `_createTotalClass()` private method
 
-### knex-rel/src/dao/video/video.dao.ts
+### knex-rel/src/dao/report-configuration/report-configuration.dao.test.ts (New File)
 
-- Add method: `bulkUpdateCamera(videoIds, cameraId, trx?)`
-- Add method: `getVideoIdsByFolderId(folderId)`
-- Add method: `getVideosByCameraIdWithFolder(cameraId, page, limit)`
+- Create unit tests for Total class aggregation
+- Test ATR format, TMC format, edge cases, key ordering
 
 ---
 
@@ -808,24 +839,33 @@ All 5 missing methods have been thoroughly analyzed:
 
 ### Database Patterns ✅
 
-- All tables use `id` (auto-increment primary key)
-- All tables use `uuid` (unique, not null) for external references
-- All tables use `created_at`/`updated_at` timestamps
-- Foreign keys use ON DELETE SET NULL for cameras
-- Indexes on UUID and foreign keys
+- No database changes required (transformation only)
+- Follows DAO pattern (logic in ReportConfigurationDAO)
+- No new migrations needed
 
-### DAO Patterns ✅
+### Code Patterns ✅
 
-- Singleton KnexManager.getConnection()
-- Standard CRUD methods (create, getById, getByUuid, getAll, update, delete)
-- Pagination with IDataPaginator<T> return type
-- JOINs use to_jsonb() for nested objects
-- Transaction support via optional trx parameter
+- 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)
+
+---
 
-### Query Patterns ✅
+## Next Steps
 
-- Use `this._knex` for queries
-- Use `query.clone()` for count vs data queries
-- Use `whereIn()` for array filters
-- Use `query.fn.now()` for timestamps
-- Use `returning('id')` for update counts
+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