@trafficgroup/knex-rel 0.1.4 → 0.1.6

package/plan.md

@@ -1,1034 +1,871 @@
-# Report Configurations Database Implementation Plan
+# Total Vehicle Class Implementation Plan
 
 ## Executive Summary
 
-This plan implements a **system-wide** report configuration system that allows users to map FHWA 13-class vehicle classifications to custom groupings for traffic reports. The configuration applies a **3-tier mapping** system: Detection Labels → FHWA Classes → Custom Classes.
+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 Decisions from User Clarifications:**
+**Key Requirements**:
 
-- System-wide configurations (NOT user-scoped)
-- Configurations selected when viewing video results or study summaries
-- Always maintain at least 1 configuration (cannot delete last one)
-- Many-to-One ONLY mapping (no duplicates allowed)
-- Unmapped FHWA classes excluded from reports
-- API-level transformation (frontend receives only transformed data)
-- Applies to both TMC and ATR study types
-- Minute-level granularity transformation
+- 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()`
 
 ---
 
-## Critical Design Challenge: Detection Label → FHWA Class Mapping
+## Current Architecture Analysis
 
-### The Problem
-
-The user described a 3-tier mapping system:
+### Data Flow
 
 ```
-Detection Labels → FHWA Classes → Custom Classes
+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
 ```
 
-However, **I cannot find a hardcoded mapping** from detection labels to FHWA classes in the codebase.
+### Current Structure Patterns
 
-**Detection Labels Found in System:**
+**ATR Format (Lane-based)**:
 
-- From VideoMinuteResultDAO.normalizeATRVehicleClass() (lines 702-731):
-  - `car`, `vehicle`, `automobiles` → normalized to `cars`
-  - `medium`, `pickup`, `truck` → normalized to `mediums`
-  - `heavy`, `largetruck`, `bigtruck` → normalized to `heavy_trucks`
-  - `pedestrian`, `person`, `people` → normalized to `pedestrians`
-  - `bicycle`, `bike`, `cyclist` → normalized to `bicycles`
+```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"
+}
+```
 
-**FHWA 13-Class System (from user clarifications):**
+**TMC Format (Direction/Turn-based)**:
 
-```
-Class 1: motorcycle
-Class 2: car
-Class 3: pickup_truck
-Class 4: bus
-Class 5: work_van
-Class 6-8: single_unit_truck
-Class 9-13: articulated_truck
+```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"
+}
 ```
 
-### The Solution: Hardcoded FHWA Mapping in ReportConfigurationDAO
+**After Custom Class Transformation** (2 custom classes: "Light" and "Heavy"):
 
-Since no existing mapping exists, we'll create a **static mapping table** in the ReportConfigurationDAO:
+```json
+{
+  "vehicles": {
+    "Light": { "NORTH": { "straight": 10, "left": 5 }, ... },
+    "Heavy": { "NORTH": { "straight": 5, "left": 1 }, ... }
+  }
+}
+```
 
-```typescript
-const DETECTION_LABEL_TO_FHWA: Record<string, number[]> = {
-  motorcycle: [1],
-  car: [2],
-  pickup_truck: [3],
-  bus: [4],
-  work_van: [5],
-  single_unit_truck: [6, 7, 8],
-  articulated_truck: [9, 10, 11, 12, 13],
-  // Non-motorized (excluded from FHWA system)
-  pedestrian: [],
-  bicycle: [],
-  motorized_vehicle: [2], // Map to car
-  non_motorized_vehicle: [],
-};
+**After Total Addition** (desired output):
+
+```json
+{
+  "vehicles": {
+    "Light": { "NORTH": { "straight": 10, "left": 5 }, ... },
+    "Heavy": { "NORTH": { "straight": 5, "left": 1 }, ... },
+    "Total": { "NORTH": { "straight": 15, "left": 6 }, ... }  // Sum of all classes
+  }
+}
 ```
 
-**Transformation Flow:**
+---
+
+## Implementation Location
+
+### File: `knex-rel/src/dao/report-configuration/report-configuration.dao.ts`
 
-1. Video processing returns detection labels (e.g., `car`, `pickup_truck`)
-2. DAO converts detection labels → FHWA classes using DETECTION_LABEL_TO_FHWA
-3. DAO applies user configuration: FHWA classes → Custom classes
-4. API returns only custom class counts to frontend
+**Method to Modify**: `applyConfigurationToNestedStructure()` (Lines 273-315)
 
-### Replacement of Existing Normalization
+**Current Implementation**:
 
-The `normalizeATRVehicleClass()` function (VideoMinuteResultDAO lines 702-731) will be **completely replaced**. Instead of normalizing to `cars`, `mediums`, `heavy_trucks`, the new system will:
+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)
 
-1. Keep raw detection labels in database
-2. Apply FHWA mapping + user configuration at aggregation time
-3. Return only custom class names to API
+**Where to Add "Total"**: AFTER line 312, BEFORE return statement (Line 314)
 
 ---
 
-## Database Schema
-
-### Table: `report_configurations`
-
-```sql
-CREATE TABLE report_configurations (
-  id SERIAL PRIMARY KEY,
-  uuid UUID NOT NULL UNIQUE DEFAULT gen_random_uuid(),
-  name VARCHAR(30) NOT NULL UNIQUE,
-  description TEXT,
-  configuration JSONB NOT NULL,
-  is_default BOOLEAN NOT NULL DEFAULT false,
-  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-  updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
-);
-
-CREATE INDEX idx_report_configurations_uuid ON report_configurations(uuid);
-CREATE INDEX idx_report_configurations_is_default ON report_configurations(is_default);
-CREATE INDEX idx_report_configurations_name_lower ON report_configurations(LOWER(name));
+## 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);
+
+return result;
 ```
 
-**Constraints:**
+### Step 2: Implement `_createTotalClass()` Helper Method
 
-- `name`: VARCHAR(30), UNIQUE, NOT NULL (max 30 characters)
-- `uuid`: UUID, UNIQUE, NOT NULL, auto-generated
-- `configuration`: JSONB, NOT NULL
-- At least 1 configuration must exist (enforced at application level)
+**Location**: Add new private method in `ReportConfigurationDAO` class (After line 350)
 
-### Configuration JSONB Structure
+**Method Signature**:
 
 ```typescript
-{
-  "version": "1.0",
-  "customClasses": [
-    {
-      "name": "Light Vehicles",
-      "fhwaClasses": [1, 2, 3]
-    },
-    {
-      "name": "Medium Trucks",
-      "fhwaClasses": [5]
-    },
-    {
-      "name": "Heavy Trucks",
-      "fhwaClasses": [4, 6, 7, 8, 9, 10, 11, 12, 13]
+private _createTotalClass(customClassesData: Record<string, any>): any
+```
+
+**Implementation**:
+
+```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));
     }
-  ]
+
+    return total;
 }
 ```
 
-**Validation Rules:**
+**Explanation**:
 
-- `customClasses` array: min 2, max 7 items
-- Each `name`: max 30 characters
-- Each `fhwaClasses` array: unique integers from 1-13
-- No FHWA class can appear in multiple custom classes (Many-to-One)
-- Unmapped FHWA classes are allowed (will be excluded from reports)
+- 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 `{}`)
 
 ---
 
-## Migration
+## Key Ordering Strategy
+
+### 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`
 
-### File: `YYYYMMDDHHMMSS_create_report_configurations.ts`
+**Our Implementation**:
 
 ```typescript
-import type { Knex } from "knex";
-
-export async function up(knex: Knex): Promise<void> {
-  await knex.schema.createTable("report_configurations", (table) => {
-    table.increments("id").primary();
-    table
-      .uuid("uuid")
-      .notNullable()
-      .unique()
-      .defaultTo(knex.raw("gen_random_uuid()"));
-    table.string("name", 30).notNullable().unique();
-    table.text("description").nullable();
-    table.jsonb("configuration").notNullable();
-    table.boolean("is_default").notNullable().defaultTo(false);
-    table.timestamps(true, true);
-
-    // Indexes
-    table.index("uuid", "idx_report_configurations_uuid");
-    table.index("is_default", "idx_report_configurations_is_default");
-  });
-
-  // Add case-insensitive name index
-  await knex.raw(`
-    CREATE INDEX idx_report_configurations_name_lower
-    ON report_configurations(LOWER(name))
-  `);
-
-  // Seed default configuration (matches current system behavior)
-  await knex("report_configurations").insert({
-    name: "Default",
-    description: "Standard configuration matching current system behavior",
-    configuration: JSON.stringify({
-      version: "1.0",
-      customClasses: [
-        {
-          name: "Cars",
-          fhwaClasses: [1, 2], // motorcycle, car
-        },
-        {
-          name: "Medium Trucks",
-          fhwaClasses: [3, 5], // pickup_truck, work_van
-        },
-        {
-          name: "Heavy Trucks",
-          fhwaClasses: [4, 6, 7, 8, 9, 10, 11, 12, 13], // bus, single_unit_truck, articulated_truck
-        },
-      ],
-    }),
-    is_default: true,
-  });
+// Lines 293-296: Initialize custom classes FIRST (insertion order)
+for (const customClass of config.configuration.customClasses) {
+  result[customClass.name] = {};
 }
 
-export async function down(knex: Knex): Promise<void> {
-  await knex.raw("DROP INDEX IF EXISTS idx_report_configurations_name_lower");
-  await knex.schema.dropTableIfExists("report_configurations");
+// 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;
 ```
 
-**Migration Safety:** LOW RISK
+**Why This Works**:
 
-- Creates new table (no data loss)
-- Seeds single default configuration
-- Rollback is clean (drop table)
+- 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
 
 ---
 
-## Interface Definition
+## ATR vs TMC Behavior
 
-### File: `src/interfaces/report-configuration/report-configuration.interfaces.ts`
+### ATR (Lane-Based Totals)
 
-```typescript
-export interface IReportConfiguration {
-  id: number;
-  uuid: string;
-  name: string;
-  description?: string;
-  configuration: IReportConfigurationData;
-  isDefault: boolean;
-  createdAt: string;
-  updatedAt: string;
+**Input Structure**:
+
+```json
+{
+  "Light": { "0": 45, "1": 50 },
+  "Heavy": { "0": 10, "1": 8 }
 }
+```
+
+**Total Output**:
 
-export interface IReportConfigurationData {
-  version: string;
-  customClasses: ICustomClass[];
+```json
+{
+  "Total": { "0": 55, "1": 58 } // Sum per lane
 }
+```
+
+**Calculation**:
+
+- Lane "0": 45 (Light) + 10 (Heavy) = 55
+- Lane "1": 50 (Light) + 8 (Heavy) = 58
 
-export interface ICustomClass {
-  name: string;
-  fhwaClasses: number[];
+**Alternative (Use existing `lane_counts`)**:
+
+The ATR structure ALREADY has `lane_counts` at the top level:
+
+```json
+{
+  "vehicles": { "Light": {...}, "Heavy": {...} },
+  "lane_counts": { "0": 55, "1": 58 }  // Already calculated!
 }
+```
+
+**Decision**: For ATR, we can EITHER:
 
-export interface IReportConfigurationInput {
-  name: string;
-  description?: string;
-  configuration: IReportConfigurationData;
-  isDefault?: boolean;
+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**:
+
+```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 }
+  }
 }
+```
+
+**Total Output**:
 
-export interface IConfigurationValidationResult {
-  valid: boolean;
-  errors: string[];
+```json
+{
+  "Total": {
+    "NORTH": { "straight": 15, "left": 6, "right": 3 },
+    "SOUTH": { "straight": 10, "left": 2, "right": 5 }
+  }
 }
 ```
 
+**Calculation**:
+
+- NORTH/straight: 10 (Light) + 5 (Heavy) = 15
+- NORTH/left: 5 (Light) + 1 (Heavy) = 6
+- SOUTH/straight: 8 (Light) + 2 (Heavy) = 10
+- etc.
+
 ---
 
-## DAO Implementation
+## Edge Cases & Validation
 
-### File: `src/dao/report-configuration/report-configuration.dao.ts`
+### Edge Case 1: Empty Data (No Vehicles)
 
-```typescript
-import { Knex } from "knex";
-import { IBaseDAO, IDataPaginator } from "../../d.types";
-import {
-  IReportConfiguration,
-  IReportConfigurationInput,
-  IReportConfigurationData,
-  IConfigurationValidationResult,
-} from "../../interfaces/report-configuration/report-configuration.interfaces";
-import KnexManager from "../../KnexConnection";
-
-// Static mapping: Detection Label → FHWA Classes
-const DETECTION_LABEL_TO_FHWA: Record<string, number[]> = {
-  motorcycle: [1],
-  car: [2],
-  pickup_truck: [3],
-  bus: [4],
-  work_van: [5],
-  single_unit_truck: [6, 7, 8],
-  articulated_truck: [9, 10, 11, 12, 13],
-  motorized_vehicle: [2], // Map to car
-  // Non-motorized excluded from FHWA
-  pedestrian: [],
-  bicycle: [],
-  non_motorized_vehicle: [],
-};
-
-export class ReportConfigurationDAO implements IBaseDAO<IReportConfiguration> {
-  private knex: Knex = KnexManager.getConnection();
-  private tableName = "report_configurations";
-
-  // ==================== STANDARD CRUD ====================
-
-  async create(item: IReportConfigurationInput): Promise<IReportConfiguration> {
-    // Validate configuration before creation
-    const validation = this.validateConfiguration(item.configuration);
-    if (!validation.valid) {
-      throw new Error(`Invalid configuration: ${validation.errors.join(", ")}`);
-    }
+**Input**:
 
-    const dbData = this.mapInputToDbRow(item);
-    const [result] = await this.knex(this.tableName)
-      .insert(dbData)
-      .returning("*");
+```json
+{
+  "vehicles": {}
+}
+```
 
-    return this.mapDbRowToEntity(result);
-  }
+**After Transformation**:
 
-  async getById(id: number): Promise<IReportConfiguration | null> {
-    const result = await this.knex(this.tableName).where("id", id).first();
-    return result ? this.mapDbRowToEntity(result) : null;
+```json
+{
+  "vehicles": {
+    "Light": {},
+    "Heavy": {},
+    "Total": {} // Empty object
   }
+}
+```
 
-  async getByUuid(uuid: string): Promise<IReportConfiguration | null> {
-    const result = await this.knex(this.tableName).where("uuid", uuid).first();
-    return result ? this.mapDbRowToEntity(result) : null;
+**Behavior**: `_createTotalClass()` returns empty object `{}`
+
+### Edge Case 2: Single Custom Class
+
+**Input**:
+
+```json
+{
+  "vehicles": {
+    "AllVehicles": { "0": 100, "1": 95 }
   }
+}
+```
+
+**Output**:
 
-  async getAll(
-    page: number = 1,
-    limit: number = 10,
-  ): Promise<IDataPaginator<IReportConfiguration>> {
-    const offset = (page - 1) * limit;
-
-    const [countResult] = await this.knex(this.tableName).count("* as count");
-    const totalCount = +countResult.count;
-
-    const data = await this.knex(this.tableName)
-      .select("*")
-      .orderBy("is_default", "desc") // Default first
-      .orderBy("name", "asc")
-      .limit(limit)
-      .offset(offset);
-
-    return {
-      success: true,
-      data: this.mapDbRowsToEntities(data),
-      page,
-      limit,
-      count: data.length,
-      totalCount,
-      totalPages: Math.ceil(totalCount / limit),
-    };
+```json
+{
+  "vehicles": {
+    "AllVehicles": { "0": 100, "1": 95 },
+    "Total": { "0": 100, "1": 95 } // Same as single class
   }
+}
+```
 
-  async update(
-    id: number,
-    item: Partial<IReportConfigurationInput>,
-  ): Promise<IReportConfiguration | null> {
-    // Validate configuration if provided
-    if (item.configuration) {
-      const validation = this.validateConfiguration(item.configuration);
-      if (!validation.valid) {
-        throw new Error(
-          `Invalid configuration: ${validation.errors.join(", ")}`,
-        );
-      }
-    }
+**Behavior**: "Total" equals the single custom class (valid)
 
-    const dbData = this.mapInputToDbRow(item);
-    const [result] = await this.knex(this.tableName)
-      .where("id", id)
-      .update({ ...dbData, updated_at: this.knex.fn.now() })
-      .returning("*");
+### Edge Case 3: Missing Directions/Turns
 
-    return result ? this.mapDbRowToEntity(result) : null;
-  }
+**Input** (TMC - Light has NORTH, Heavy only has SOUTH):
+
+```json
+{
+  "Light": { "NORTH": { "straight": 10 } },
+  "Heavy": { "SOUTH": { "straight": 5 } }
+}
+```
 
-  async delete(id: number): Promise<boolean> {
-    // Use deleteWithValidation to prevent deletion of last config
-    return this.deleteWithValidation(id);
+**Output**:
+
+```json
+{
+  "Total": {
+    "NORTH": { "straight": 10 },
+    "SOUTH": { "straight": 5 }
   }
+}
+```
 
-  // ==================== CUSTOM METHODS ====================
+**Behavior**: `_deepMergeNumericData()` handles missing keys gracefully (Lines 339-347)
 
-  /**
-   * Delete configuration with validation (prevents deletion of last config)
-   */
-  async deleteWithValidation(id: number): Promise<boolean> {
-    const [countResult] = await this.knex(this.tableName).count("* as count");
-    const totalCount = +countResult.count;
+### Edge Case 4: Null/Undefined Values
 
-    if (totalCount <= 1) {
-      throw new Error(
-        "Cannot delete the last configuration. At least one configuration must exist.",
-      );
-    }
+**Input**:
 
-    const result = await this.knex(this.tableName).where("id", id).del();
-    return result > 0;
-  }
+```json
+{
+  "Light": { "0": 10, "1": null },
+  "Heavy": { "0": 5 }
+}
+```
 
-  /**
-   * Get default configuration (for UI convenience)
-   */
-  async getDefault(): Promise<IReportConfiguration | null> {
-    const result = await this.knex(this.tableName)
-      .where("is_default", true)
-      .first();
-
-    // If no default, return first configuration
-    if (!result) {
-      const fallback = await this.knex(this.tableName)
-        .orderBy("created_at", "asc")
-        .first();
-      return fallback ? this.mapDbRowToEntity(fallback) : null;
-    }
+**Output**:
 
-    return this.mapDbRowToEntity(result);
-  }
+```json
+{
+  "Total": { "0": 15, "1": 0 } // null treated as 0
+}
+```
 
-  /**
-   * Set a configuration as default (removes default flag from others)
-   */
-  async setDefault(id: number): Promise<boolean> {
-    await this.knex.transaction(async (trx) => {
-      // Remove default flag from all
-      await trx(this.tableName).update({ is_default: false });
+**Behavior**: `_deepMergeNumericData()` checks `typeof source === 'number'` (Line 330)
 
-      // Set new default
-      await trx(this.tableName).where("id", id).update({ is_default: true });
-    });
+---
 
-    return true;
-  }
+## Testing Strategy
 
-  /**
-   * Validate configuration structure and business rules
-   */
-  validateConfiguration(
-    config: IReportConfigurationData,
-  ): IConfigurationValidationResult {
-    const errors: string[] = [];
-
-    // Check structure
-    if (!config || typeof config !== "object") {
-      errors.push("Configuration must be an object");
-      return { valid: false, errors };
-    }
+### Unit Tests (to be created)
 
-    if (!config.customClasses || !Array.isArray(config.customClasses)) {
-      errors.push("customClasses must be an array");
-      return { valid: false, errors };
-    }
+**File**: `knex-rel/src/dao/report-configuration/report-configuration.dao.test.ts`
 
-    // Rule: Min 2, max 7 custom classes
-    if (config.customClasses.length < 2) {
-      errors.push("At least 2 custom classes required");
-    }
-    if (config.customClasses.length > 7) {
-      errors.push("Maximum 7 custom classes allowed");
-    }
+**Test Cases**:
 
-    // Track FHWA classes to detect duplicates
-    const usedFhwaClasses = new Set<number>();
-    const classNames = new Set<string>();
-
-    for (const customClass of config.customClasses) {
-      // Check name length
-      if (!customClass.name || customClass.name.length > 30) {
-        errors.push(
-          `Custom class name must be 1-30 characters: "${customClass.name}"`,
-        );
-      }
-
-      // Check for duplicate names
-      if (classNames.has(customClass.name)) {
-        errors.push(`Duplicate custom class name: "${customClass.name}"`);
-      }
-      classNames.add(customClass.name);
-
-      // Check fhwaClasses array
-      if (
-        !Array.isArray(customClass.fhwaClasses) ||
-        customClass.fhwaClasses.length === 0
-      ) {
-        errors.push(
-          `Custom class "${customClass.name}" must have at least one FHWA class`,
-        );
-        continue;
-      }
-
-      // Check for duplicates (Many-to-One enforcement)
-      for (const fhwaClass of customClass.fhwaClasses) {
-        if (usedFhwaClasses.has(fhwaClass)) {
-          errors.push(
-            `FHWA class ${fhwaClass} appears in multiple custom classes (not allowed)`,
-          );
-        }
-        usedFhwaClasses.add(fhwaClass);
-
-        // Validate FHWA class range
-        if (fhwaClass < 1 || fhwaClass > 13) {
-          errors.push(`Invalid FHWA class ${fhwaClass} (must be 1-13)`);
-        }
-      }
-    }
+1. **ATR: Total Class Aggregation**
+   - Input: 2 custom classes with lane counts
+   - Verify: Total sums all lanes correctly
+   - Verify: Total appears as last key
 
-    return {
-      valid: errors.length === 0,
-      errors,
-    };
-  }
+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
 
-  /**
-   * Apply configuration to raw detection counts
-   * @param detectionCounts - Raw counts from video processing (e.g., {car: 50, pickup_truck: 20})
-   * @param configuration - Report configuration to apply
-   * @returns Transformed counts with custom class names
-   */
-  applyConfiguration(
-    detectionCounts: Record<string, number>,
-    configuration: IReportConfigurationData,
-  ): Record<string, number> {
-    // Step 1: Convert detection labels to FHWA classes
-    const fhwaCounts: Record<number, number> = {};
-
-    for (const [detectionLabel, count] of Object.entries(detectionCounts)) {
-      const fhwaClasses = DETECTION_LABEL_TO_FHWA[detectionLabel] || [];
-
-      // Distribute count equally among FHWA classes (for multi-mapped labels like single_unit_truck)
-      const countPerClass = count / fhwaClasses.length;
-
-      for (const fhwaClass of fhwaClasses) {
-        fhwaCounts[fhwaClass] = (fhwaCounts[fhwaClass] || 0) + countPerClass;
-      }
-    }
+3. **Edge Case: Empty Vehicles**
+   - Input: No vehicle data
+   - Verify: Total is empty object `{}`
 
-    // Step 2: Apply user configuration (FHWA classes → Custom classes)
-    const customCounts: Record<string, number> = {};
+4. **Edge Case: Single Custom Class**
+   - Input: 1 custom class
+   - Verify: Total equals the single class
 
-    for (const customClass of configuration.customClasses) {
-      let total = 0;
+5. **Edge Case: Missing Directions**
+   - Input: Asymmetric direction/turn data
+   - Verify: Total includes all unique keys
 
-      for (const fhwaClass of customClass.fhwaClasses) {
-        total += fhwaCounts[fhwaClass] || 0;
-      }
+6. **Key Ordering Test**
+   - Input: 5 custom classes
+   - Verify: Total is the 6th key (last)
+   - Verify: `Object.keys(result)` ends with "Total"
 
-      customCounts[customClass.name] = Math.round(total);
-    }
+### Integration Tests
 
-    return customCounts;
-  }
+**Test in api-rel controller**:
 
-  // ==================== MAPPING HELPERS ====================
-
-  private mapDbRowToEntity(row: any): IReportConfiguration {
-    return {
-      id: row.id,
-      uuid: row.uuid,
-      name: row.name,
-      description: row.description,
-      configuration: row.configuration,
-      isDefault: row.is_default,
-      createdAt: row.created_at,
-      updatedAt: row.updated_at,
-    };
-  }
+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
 
-  private mapDbRowsToEntities(rows: any[]): IReportConfiguration[] {
-    return rows.map((row) => this.mapDbRowToEntity(row));
-  }
+**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
 
-  private mapInputToDbRow(input: Partial<IReportConfigurationInput>): any {
-    const dbRow: any = {};
+---
 
-    if (input.name !== undefined) dbRow.name = input.name;
-    if (input.description !== undefined) dbRow.description = input.description;
-    if (input.configuration !== undefined)
-      dbRow.configuration = input.configuration;
-    if (input.isDefault !== undefined) dbRow.is_default = input.isDefault;
+## Performance Considerations
 
-    return dbRow;
-  }
-}
+### Computational Complexity
 
-export default ReportConfigurationDAO;
-```
+**Current**: O(n × m) where:
+
+- n = number of detection labels
+- m = average nesting depth (2 for ATR, 3 for TMC)
+
+**After Adding Total**: O(n × m + c × m) where:
+
+- c = number of custom classes (2-7 per validation)
+
+**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
 
 ---
 
-## Integration with VideoMinuteResultDAO
+## Backward Compatibility
 
-### Modifications Required
+### Changes Are Additive Only
 
-The `VideoMinuteResultDAO` must be modified to accept and apply report configurations during aggregation.
+✅ **No Breaking Changes**:
 
-**File:** `src/dao/VideoMinuteResultDAO.ts`
+- Existing custom classes remain unchanged
+- Existing API response structure preserved
+- "Total" is a NEW key (optional to consume)
 
-### Changes to Method Signatures
+✅ **Frontend Compatibility**:
 
-```typescript
-// NEW: Add configurationId parameter to aggregation methods
-async getGroupedMinuteResultsByVideoUuid(
-  videoUuid: string,
-  groupingMinutes: number = 1,
-  configurationId?: number,  // NEW PARAMETER
-  startMinute?: number,
-  endMinute?: number,
-): Promise<IGroupedResponse>
-```
+- Old frontend: Ignores "Total" key (no errors)
+- New frontend: Displays "Total" as last tab
 
-### Integration Strategy
+✅ **Database Compatibility**:
 
-1. **Import ReportConfigurationDAO:**
+- No schema changes required
+- Raw results in database unchanged
+- Transformation happens at runtime
 
-   ```typescript
-   import { ReportConfigurationDAO } from "./report-configuration/report-configuration.dao";
-   ```
+---
 
-2. **Modify aggregateTMCResults() (lines 508-585):**
-   - Accept `configuration` parameter
-   - Apply configuration transformation AFTER aggregating detection labels
-   - Replace vehicle class keys with custom class names
+## Implementation Checklist
 
-3. **Modify aggregateATRResults() (lines 590-642):**
-   - Accept `configuration` parameter
-   - Remove `normalizeATRVehicleClass()` calls (lines 606, 634)
-   - Apply configuration transformation instead
+### Pre-Implementation
 
-4. **Add new helper method:**
+- [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
 
-   ```typescript
-   private async fetchConfiguration(configurationId?: number): Promise<IReportConfigurationData> {
-     const configDAO = new ReportConfigurationDAO();
+### Implementation Phase
 
-     let config: IReportConfiguration | null;
+- [ ] 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`
 
-     if (configurationId) {
-       config = await configDAO.getById(configurationId);
-     } else {
-       config = await configDAO.getDefault();
-     }
+### Testing Phase
 
-     if (!config) {
-       throw new Error("No report configuration found");
-     }
+- [ ] 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`
 
-     return config.configuration;
-   }
-   ```
+### Integration Phase
 
-5. **Update aggregation flow:**
+- [ ] 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
 
-   ```typescript
-   // In getGroupedMinuteResultsByVideoUuid()
-   const configuration = await this.fetchConfiguration(configurationId);
+### Frontend Integration (Separate Task)
 
-   const aggregatedGroups: IGroupedResult[] = rows.map((row: any) => {
-     // ... existing aggregation logic ...
+- [ ] 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
 
-     let aggregatedResult;
-     if (studyType === "TMC") {
-       aggregatedResult = this.aggregateTMCResults(allResults, configuration);
-     } else {
-       aggregatedResult = this.aggregateATRResults(allResults, configuration);
-     }
+---
 
-     // ... return result ...
-   });
-   ```
+## Code Changes Summary
 
-### Detailed Transformation Example (ATR)
+### File 1: `knex-rel/src/dao/report-configuration/report-configuration.dao.ts`
 
-**Before transformation (raw detection labels):**
+**Location 1: After Line 312 (Inside `applyConfigurationToNestedStructure()`)**
 
 ```typescript
-{
-  vehicles: {
-    car: { lane_1: 50, lane_2: 30 },
-    pickup_truck: { lane_1: 10, lane_2: 15 },
-    bus: { lane_1: 5, lane_2: 3 }
-  },
-  detected_classes: {
-    car: 80,
-    pickup_truck: 25,
-    bus: 8
+// 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;
 ```
 
-**After applying configuration:**
+**Location 2: After Line 350 (New Private Method)**
 
 ```typescript
-// Configuration: Cars [1,2], Medium Trucks [3,5], Heavy Trucks [4,6-13]
-{
-  vehicles: {
-    "Cars": { lane_1: 50, lane_2: 30 },           // car → FHWA 2 → Cars
-    "Medium Trucks": { lane_1: 10, lane_2: 15 },   // pickup_truck → FHWA 3 → Medium Trucks
-    "Heavy Trucks": { lane_1: 5, lane_2: 3 }       // bus → FHWA 4 → Heavy Trucks
-  },
-  detected_classes: {
-    "Cars": 80,
-    "Medium Trucks": 25,
-    "Heavy Trucks": 8
-  }
+/**
+ * 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;
 }
 ```
 
 ---
 
-## Export Updates
+## Validation Plan
 
-### File: `src/index.ts`
+### Manual Testing Checklist
 
-Add exports for new DAO and interfaces:
+**Test 1: ATR Video (2 Custom Classes)**
 
-```typescript
-// Add to DAOs section
-export { ReportConfigurationDAO } from "./dao/report-configuration/report-configuration.dao";
-
-// Add to Interfaces section
-export {
-  IReportConfiguration,
-  IReportConfigurationInput,
-  IReportConfigurationData,
-  ICustomClass,
-  IConfigurationValidationResult,
-} from "./interfaces/report-configuration/report-configuration.interfaces";
-```
+- [ ] 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)**
 
-## Implementation Order
+- [ ] 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
 
-### Phase 1: Database Foundation
+**Test 3: Edge Cases**
 
-1. Create interface file: `report-configuration.interfaces.ts`
-2. Create migration: `YYYYMMDDHHMMSS_create_report_configurations.ts`
-3. Run migration: `npm run migrate:deploy`
-4. Verify seed data exists (1 default configuration)
+- [ ] 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)
 
-### Phase 2: DAO Implementation
+**Test 4: Grouped Results (Multiple Minutes)**
 
-5. Create DAO: `report-configuration.dao.ts`
-6. Implement standard CRUD methods
-7. Implement validation logic
-8. Implement `applyConfiguration()` transformation logic
-9. Test DAO methods in isolation
+- [ ] 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
 
-### Phase 3: Integration
+---
 
-10. Modify `VideoMinuteResultDAO.aggregateTMCResults()`
-11. Modify `VideoMinuteResultDAO.aggregateATRResults()`
-12. Remove `normalizeATRVehicleClass()` calls
-13. Add `fetchConfiguration()` helper
-14. Update method signatures to accept `configurationId`
+## Risks & Mitigations
 
-### Phase 4: Exports & Build
+### Risk 1: Key Ordering Not Guaranteed
 
-15. Update `src/index.ts` exports
-16. Run `npm run build` in knex-rel
-17. Verify no TypeScript errors
-18. Test against sample video data
+**Risk**: JavaScript object keys might not preserve insertion order
 
----
+**Likelihood**: Very Low (ES2015+ guarantees string key order)
 
-## Risks & Concerns
+**Mitigation**:
 
-### 🔴 CRITICAL: Detection Label Mapping Assumption
+- Add unit test to verify `Object.keys(result)` ends with "Total"
+- If ordering fails, use explicit ordering array in frontend
 
-**Risk:** The `DETECTION_LABEL_TO_FHWA` mapping is based on user clarifications, but there's no guarantee that video processing returns exactly these labels.
+### Risk 2: Performance Degradation
 
-**Mitigation:**
+**Risk**: Additional aggregation adds processing time
 
-- Test with actual video processing output
-- Add logging when unknown detection labels are encountered
-- Provide fallback behavior (map unknown labels to FHWA Class 2 by default)
+**Likelihood**: Very Low (O(c × m) is negligible)
 
-### 🟡 MEDIUM: Performance at Minute-Level Granularity
+**Mitigation**:
 
-**Risk:** Applying configuration transformation at minute-level for 100+ videos could be slow.
+- Benchmark transformation time before/after
+- If impact > 10ms, consider caching Total class
 
-**Current Decision:** Apply transformation on-the-fly (per user clarification Q10.2).
+### Risk 3: Frontend Breaks on Unknown Class
 
-**Future Optimization:**
+**Risk**: Old frontend version throws error on "Total" key
 
-- Cache configuration object in memory (singleton pattern)
-- Pre-compute transformed results and store in separate JSONB column
-- Add database-level JSONB transformation functions
+**Likelihood**: Very Low (key is additive, not breaking)
 
-### 🟡 MEDIUM: Replacement of normalizeATRVehicleClass()
+**Mitigation**:
 
-**Risk:** Existing API clients may expect normalized class names (`cars`, `mediums`, `heavy_trucks`).
+- "Total" is just another custom class name
+- Frontend already iterates dynamic class names
+- No special handling needed
 
-**Mitigation:**
+### Risk 4: Incorrect Aggregation Logic
 
-- Default configuration seed matches current normalization
-- API will return same class names initially (backwards compatible)
-- Users can create custom configurations as needed
+**Risk**: `_deepMergeNumericData()` doesn't handle all cases
 
-### 🟢 LOW: Migration Safety
+**Likelihood**: Low (method already tested for custom class merging)
 
-**Risk:** Minimal - only creates new table with seed data.
+**Mitigation**:
 
-**Rollback:** Clean rollback with `down()` migration drops table entirely.
+- 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 (DAO Level)
+### Alternative 1: Add "Total" in Frontend
 
-```typescript
-// Test validation
-describe("ReportConfigurationDAO.validateConfiguration", () => {
-  it("should reject configurations with < 2 custom classes");
-  it("should reject configurations with > 7 custom classes");
-  it("should reject duplicate FHWA classes");
-  it("should reject custom class names > 30 chars");
-  it("should accept valid configurations");
-});
-
-// Test transformation
-describe("ReportConfigurationDAO.applyConfiguration", () => {
-  it("should map detection labels to FHWA classes");
-  it("should map FHWA classes to custom classes");
-  it("should exclude unmapped FHWA classes");
-  it("should handle multi-mapped detection labels (single_unit_truck)");
-});
-
-// Test deletion validation
-describe("ReportConfigurationDAO.deleteWithValidation", () => {
-  it("should prevent deletion of last configuration");
-  it("should allow deletion when > 1 configuration exists");
-});
-```
+**Approach**: Calculate "Total" in traffic-webapp instead of backend
 
-### Integration Tests (VideoMinuteResultDAO)
+**Pros**:
 
-```typescript
-describe("VideoMinuteResultDAO with ReportConfigurations", () => {
-  it("should apply configuration to TMC results");
-  it("should apply configuration to ATR results");
-  it("should use default configuration when none specified");
-  it("should handle unmapped vehicle classes correctly");
-});
-```
+- No backend changes required
+- Frontend controls display logic
 
----
+**Cons**:
 
-## Performance Considerations
+- Duplicates logic across frontend
+- Inconsistent if API consumed elsewhere
+- Cannot use "Total" in backend reports/exports
 
-### Query Optimization
+**Decision**: ❌ Rejected - Backend is single source of truth
 
-**Configuration Lookup:**
+### Alternative 2: Add "Total" as Separate Field
 
-- Index on `uuid` for fast lookup by UUID
-- Index on `is_default` for quick default retrieval
-- Consider in-memory caching (singleton) if configurations queried frequently
+**Approach**: Add `results.totalClass` instead of `results.vehicles["Total"]`
 
-**Transformation:**
+**Pros**:
 
-- `applyConfiguration()` runs in O(n) time where n = number of detection labels
-- For minute-level data (potentially 1000s of minutes), this could be expensive
-- **Future optimization:** Move transformation to PostgreSQL JSONB functions
+- Clearer separation of concerns
+- No risk of key ordering issues
 
-### Caching Strategy (Future)
+**Cons**:
 
-```typescript
-class ReportConfigurationCache {
-  private static instance: Map<number, IReportConfigurationData> = new Map();
+- Inconsistent with custom class structure
+- Frontend needs special handling
+- Breaks uniform class iteration logic
 
-  static get(id: number): IReportConfigurationData | undefined {
-    return this.instance.get(id);
-  }
+**Decision**: ❌ Rejected - Keep "Total" as vehicle class for uniformity
 
-  static set(id: number, config: IReportConfigurationData): void {
-    this.instance.set(id, config);
-  }
+### Alternative 3: Make "Total" Configurable
 
-  static clear(): void {
-    this.instance.clear();
-  }
-}
-```
+**Approach**: Add `includeTotalClass: boolean` to report configuration
 
----
+**Pros**:
 
-## Open Questions & Future Enhancements
+- User control over Total display
+- Backward compatible (default false)
 
-### 1. Unmapped FHWA Classes Display
+**Cons**:
 
-**Question:** Should the API response indicate which FHWA classes were excluded?
+- Adds complexity to configuration
+- Not needed (Total is always useful)
+- Extra validation logic
 
-**Example:**
+**Decision**: ❌ Rejected - Always include "Total" (KISS principle)
 
-```json
-{
-  "customClasses": {
-    "Cars": 100,
-    "Heavy Trucks": 50
-  },
-  "unmappedCounts": {
-    "fhwaClass4": 10,
-    "fhwaClass5": 5
-  }
-}
-```
+---
 
-**Recommendation:** Add this as optional metadata for debugging purposes.
+## Success Criteria
 
-### 2. Configuration Change History
+### Implementation Success
 
-**Question:** Should we track configuration changes over time?
+✅ TypeScript compiles without errors
+✅ `npm run build` succeeds in knex-rel
+✅ All existing unit tests pass
+✅ New unit tests pass (Total class logic)
 
-**Future Enhancement:** Add `report_configuration_history` table to track when configurations are created/modified.
+### Functional Success
 
-### 3. Pedestrians & Bicycles
+✅ 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)
 
-**Question:** Current system excludes pedestrians/bicycles from FHWA mapping. Should users be able to create custom classes for non-motorized traffic?
+### Integration Success
 
-**Recommendation:** Support this by adding FHWA classes 14-15 (non-motorized) in future iteration.
+✅ 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)
 
-### 4. Detection Label Variability
+---
 
-**Question:** What if video processing returns different detection labels than expected?
+## Timeline Estimate
 
-**Recommendation:** Add logging and admin dashboard to monitor unmapped detection labels.
+### Backend Implementation (knex-rel)
 
----
+- Code changes: 30 minutes
+- Unit tests: 1 hour
+- Build & test: 15 minutes
+- **Total: ~2 hours**
 
-## Validation Checklist
+### Integration Testing (api-rel)
 
-Before marking this plan as complete, verify:
+- Manual testing with ATR video: 30 minutes
+- Manual testing with TMC video: 30 minutes
+- Edge case validation: 30 minutes
+- **Total: ~1.5 hours**
 
-- [x] Database schema includes all required fields
-- [x] Migration has proper up/down functions
-- [x] Seed data matches current system behavior
-- [x] Interface definitions match database schema
-- [x] DAO implements all IBaseDAO methods
-- [x] Validation logic covers all business rules (2-7 classes, no duplicates, 30 char limit)
-- [x] DETECTION_LABEL_TO_FHWA mapping is complete
-- [x] Integration strategy with VideoMinuteResultDAO is clear
-- [x] Export updates are documented
-- [x] Implementation order is logical
-- [x] Risks are identified and mitigated
-- [x] Testing strategy is comprehensive
+### Frontend Integration (traffic-webapp - Separate)
 
----
+- Display "Total" tab: 1 hour
+- Chart/table rendering: 1 hour
+- Testing both video types: 1 hour
+- **Total: ~3 hours**
 
-## Pattern Compliance
+**Overall Estimate: ~6.5 hours** (Backend: 3.5 hours, Frontend: 3 hours)
 
-### Database Patterns ✅
+---
 
-- Primary key: `id` (auto-increment)
-- External identifier: `uuid` (unique, not null, auto-generated)
-- Timestamps: `created_at`, `updated_at`
-- Foreign keys: N/A (system-wide table)
+## Summary
 
-### DAO Patterns ✅
+### What Changes
 
-- Implements `IBaseDAO<IReportConfiguration>`
-- Singleton KnexManager connection
-- Methods: create, getById, getByUuid, getAll, update, delete
-- Custom methods: deleteWithValidation, getDefault, setDefault, validateConfiguration, applyConfiguration
+✅ **ADD**: `_createTotalClass()` private method in ReportConfigurationDAO
+✅ **ADD**: `result["Total"] = ...` line after custom class transformation
+✅ **ADD**: Unit tests for Total class aggregation
 
-### File Naming ✅
+### What Stays the Same
 
-- Migration: `YYYYMMDDHHMMSS_create_report_configurations.ts`
-- DAO: `report-configuration.dao.ts`
-- Interface: `report-configuration.interfaces.ts` (matches folder structure)
+✅ Database schema (no migrations)
+✅ Existing custom classes (no modifications)
+✅ API response structure (additive only)
+✅ `_deepMergeNumericData()` helper (reused, not changed)
 
-### Performance ✅
+### Key Benefits
 
-- Indexed UUID for fast lookups
-- JOINs eliminated (no foreign keys, system-wide table)
-- Pagination implemented in getAll()
-- Future: Consider caching for frequently accessed configurations
+✅ 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.
 
 ---
 
-## Next Steps for Orchestrator
+## Files to Modify
 
-This plan is now ready for handoff to the **knex-code-agent** for implementation.
+### knex-rel/src/dao/report-configuration/report-configuration.dao.ts
 
-**Orchestrator should:**
+- **Line 312**: Add `result["Total"] = this._createTotalClass(result);`
+- **After Line 350**: Add `_createTotalClass()` private method
 
-1. Review this plan for completeness
-2. Approve DETECTION_LABEL_TO_FHWA mapping accuracy
-3. Confirm migration timestamp format
-4. Hand off to knex-code-agent for execution
+### knex-rel/src/dao/report-configuration/report-configuration.dao.test.ts (New File)
 
-**knex-code-agent should:**
+- Create unit tests for Total class aggregation
+- Test ATR format, TMC format, edge cases, key ordering
 
-1. Implement in exact order specified (Phase 1 → Phase 2 → Phase 3 → Phase 4)
-2. Test each phase before proceeding
-3. Report any conflicts or issues discovered during implementation
-4. Request clarification if detection labels don't match expectations
+---
 
-**Blockers:**
+## Pattern Compliance Summary
 
-- None identified. Plan is complete and ready for implementation.
+### Database Patterns ✅
 
----
+- No database changes required (transformation only)
+- Follows DAO pattern (logic in ReportConfigurationDAO)
+- No new migrations needed
 
-## Appendix: FHWA 13-Class System Reference
+### Code Patterns ✅
 
-```
-Class 1:  Motorcycles
-Class 2:  Passenger Cars
-Class 3:  Other Two-Axle, Four-Tire Single Unit Vehicles (Pickups, Vans)
-Class 4:  Buses
-Class 5:  Two-Axle, Six-Tire Single Unit Trucks (Work Vans)
-Class 6:  Three-Axle Single Unit Trucks
-Class 7:  Four or More Axle Single Unit Trucks
-Class 8:  Four or Less Axle Single Trailer Trucks
-Class 9:  Five-Axle Single Trailer Trucks
-Class 10: Six or More Axle Single Trailer Trucks
-Class 11: Five or Less Axle Multi-Trailer Trucks
-Class 12: Six-Axle Multi-Trailer Trucks
-Class 13: Seven or More Axle Multi-Trailer Trucks
-```
+- Reuses existing `_deepMergeNumericData()` helper
+- Follows private method naming convention (`_methodName`)
+- Maintains nested structure consistency
+- Preserves key ordering via insertion order
 
-**Detection Label Mapping:**
+### Performance Patterns ✅
 
-- Classes 6-8: All map to `single_unit_truck` detection label
-- Classes 9-13: All map to `articulated_truck` detection label
-- This creates a many-to-one relationship at the detection level
+- O(c × m) additional complexity (negligible)
+- No N+1 queries (transformation in memory)
+- No database roundtrips
+- Minimal memory overhead (~500 bytes per result)
 
 ---
 
-## Document Version
+## Next Steps
 
-- **Version:** 1.0
-- **Date:** 2025-09-30
-- **Author:** Database Planning Specialist (Claude)
-- **Status:** FINAL - Ready for Implementation
+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