@trafficgroup/knex-rel 0.1.3 → 0.1.4

package/plan.md

@@ -1,288 +1,1034 @@
-# Database Optimization Plan for Camera Bulk Operations
+# Report Configurations Database Implementation Plan
 
-## Current Schema Analysis
+## Executive Summary
 
-### Existing Tables & Indexes
+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.
 
-**cameras table:**
+**Key Decisions from User Clarifications:**
 
-- Primary key: `id` (auto-increment)
-- Unique index: `uuid`
-- Composite index: `[longitude, latitude]` for geospatial queries
+- 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
+
+---
+
+## Critical Design Challenge: Detection Label → FHWA Class Mapping
+
+### The Problem
+
+The user described a 3-tier mapping system:
+
+```
+Detection Labels → FHWA Classes → Custom Classes
+```
+
+However, **I cannot find a hardcoded mapping** from detection labels to FHWA classes in the codebase.
+
+**Detection Labels Found in System:**
 
-**video table:**
+- 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`
 
-- Primary key: `id`
-- Foreign key: `cameraId` → `cameras.id` (nullable, with index)
-- Foreign key: `folderId` → `folders.id` (with implicit index)
-- Unique index: `uuid`
-- Composite indexes:
-  - `[annotationSourceId]`
-  - `[folderId, videoType, status]` (template lookup)
+**FHWA 13-Class System (from user clarifications):**
 
-**folders table:**
+```
+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
+```
+
+### The Solution: Hardcoded FHWA Mapping in ReportConfigurationDAO
+
+Since no existing mapping exists, we'll create a **static mapping table** in the ReportConfigurationDAO:
+
+```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: [],
+};
+```
 
-- Primary key: `id`
-- Foreign key: `cameraId` → `cameras.id` (nullable, with index)
-- Foreign key: `studyId` → `study.id` (with implicit index)
-- Unique index: `uuid`
+**Transformation Flow:**
 
-### Performance Analysis for Required Operations
+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
 
-#### 1. ✅ Bulk update videos when folder cameraId changes
+### Replacement of Existing Normalization
 
-**Query:** `UPDATE video SET cameraId = ? WHERE folderId = ?`
+The `normalizeATRVehicleClass()` function (VideoMinuteResultDAO lines 702-731) will be **completely replaced**. Instead of normalizing to `cars`, `mediums`, `heavy_trucks`, the new system will:
 
-- **Current Performance:** GOOD
-- **Existing Index:** `[folderId]` (implicit from FK constraint)
-- **Status:** No optimization needed
+1. Keep raw detection labels in database
+2. Apply FHWA mapping + user configuration at aggregation time
+3. Return only custom class names to API
 
-#### 2. ❌ Search cameras by name with pagination
+---
 
-**Query:** `SELECT * FROM cameras WHERE name ILIKE '%search%' ORDER BY name LIMIT ? OFFSET ?`
+## Database Schema
 
-- **Current Performance:** POOR - Full table scan
-- **Missing Index:** Text search index on `name` column
-- **Impact:** Critical performance issue for camera search
+### Table: `report_configurations`
 
-#### 3. ✅ Find videos by specific camera
+```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));
+```
 
-**Query:** `SELECT * FROM video WHERE cameraId = ?`
+**Constraints:**
 
-- **Current Performance:** GOOD
-- **Existing Index:** `[cameraId]` from migration `20250911000000_migration.ts`
-- **Status:** No optimization needed
+- `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)
 
-#### 4. ⚠️ Bulk assign camera to multiple videos
+### Configuration JSONB Structure
 
-**Query:** `UPDATE video SET cameraId = ? WHERE id IN (...)`
+```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]
+    }
+  ]
+}
+```
 
-- **Current Performance:** ACCEPTABLE but can be optimized
-- **Existing Index:** Primary key on `id`
-- **Optimization Opportunity:** Batch processing with transaction optimization
+**Validation Rules:**
 
-## Required Database Optimizations
+- `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)
 
-### New Migrations Required
+---
 
-#### Migration: Add camera name search index
+## Migration
 
-**File:** `20250924000000_camera_name_search_index.ts`
-**Purpose:** Optimize camera search by name functionality
+### File: `YYYYMMDDHHMMSS_create_report_configurations.ts`
 
 ```typescript
+import type { Knex } from "knex";
+
 export async function up(knex: Knex): Promise<void> {
-  await knex.schema.alterTable("cameras", (table) => {
-    // Add index for case-insensitive name searches
-    table.index(knex.raw("LOWER(name)"), "idx_cameras_name_lower");
+  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 GIN index for full-text search if needed for fuzzy matching
+  // Add case-insensitive name index
   await knex.raw(`
-    CREATE INDEX idx_cameras_name_gin
-    ON cameras
-    USING GIN (to_tsvector('english', name))
+    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,
+  });
 }
 
 export async function down(knex: Knex): Promise<void> {
-  await knex.raw("DROP INDEX IF EXISTS idx_cameras_name_gin");
-  await knex.schema.alterTable("cameras", (table) => {
-    table.dropIndex(knex.raw("LOWER(name)"), "idx_cameras_name_lower");
-  });
+  await knex.raw("DROP INDEX IF EXISTS idx_report_configurations_name_lower");
+  await knex.schema.dropTableIfExists("report_configurations");
 }
 ```
 
-### DAO Method Optimizations
+**Migration Safety:** LOW RISK
+
+- Creates new table (no data loss)
+- Seeds single default configuration
+- Rollback is clean (drop table)
+
+---
 
-#### CameraDAO Enhancements Required
+## Interface Definition
 
-**New Methods Needed:**
+### File: `src/interfaces/report-configuration/report-configuration.interfaces.ts`
 
 ```typescript
-// Optimized paginated search by name
-async searchByName(
-  searchTerm: string,
-  page: number,
-  limit: number
-): Promise<IDataPaginator<ICamera>> {
-  const offset = (page - 1) * limit;
-  const searchPattern = `%${searchTerm.toLowerCase()}%`;
-
-  const query = this._knex("cameras")
-    .whereRaw("LOWER(name) LIKE ?", [searchPattern])
-    .orderBy("name");
-
-  const [countResult] = await query.clone().clearSelect().count("* as count");
-  const totalCount = +countResult.count;
-  const cameras = await query.clone().limit(limit).offset(offset);
-
-  return {
-    success: true,
-    data: cameras,
-    page,
-    limit,
-    count: cameras.length,
-    totalCount,
-    totalPages: Math.ceil(totalCount / limit),
-  };
+export interface IReportConfiguration {
+  id: number;
+  uuid: string;
+  name: string;
+  description?: string;
+  configuration: IReportConfigurationData;
+  isDefault: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface IReportConfigurationData {
+  version: string;
+  customClasses: ICustomClass[];
 }
 
-// Get all videos associated with a camera (with pagination)
-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)
-    .orderBy("v.created_at", "desc");
-
-  const [countResult] = await query.clone().clearSelect().count("* as count");
-  const totalCount = +countResult.count;
-  const videos = await query.clone().limit(limit).offset(offset);
-
-  return {
-    success: true,
-    data: videos,
-    page,
-    limit,
-    count: videos.length,
-    totalCount,
-    totalPages: Math.ceil(totalCount / limit),
-  };
+export interface ICustomClass {
+  name: string;
+  fhwaClasses: number[];
+}
+
+export interface IReportConfigurationInput {
+  name: string;
+  description?: string;
+  configuration: IReportConfigurationData;
+  isDefault?: boolean;
+}
+
+export interface IConfigurationValidationResult {
+  valid: boolean;
+  errors: string[];
 }
 ```
 
-#### VideoDAO Enhancements Required
+---
+
+## DAO Implementation
 
-**New Methods Needed:**
+### File: `src/dao/report-configuration/report-configuration.dao.ts`
 
 ```typescript
-// Bulk update videos by folder (folder camera cascade)
-async bulkUpdateCameraByFolder(
-  folderId: number,
-  cameraId: number | null
-): Promise<number> {
-  const result = await this._knex("video")
-    .where("folderId", folderId)
-    .update({
-      cameraId: cameraId,
-      updated_at: this._knex.fn.now()
+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(", ")}`);
+    }
+
+    const dbData = this.mapInputToDbRow(item);
+    const [result] = await this.knex(this.tableName)
+      .insert(dbData)
+      .returning("*");
+
+    return this.mapDbRowToEntity(result);
+  }
+
+  async getById(id: number): Promise<IReportConfiguration | null> {
+    const result = await this.knex(this.tableName).where("id", id).first();
+    return result ? this.mapDbRowToEntity(result) : null;
+  }
+
+  async getByUuid(uuid: string): Promise<IReportConfiguration | null> {
+    const result = await this.knex(this.tableName).where("uuid", uuid).first();
+    return result ? this.mapDbRowToEntity(result) : null;
+  }
+
+  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),
+    };
+  }
+
+  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(", ")}`,
+        );
+      }
+    }
+
+    const dbData = this.mapInputToDbRow(item);
+    const [result] = await this.knex(this.tableName)
+      .where("id", id)
+      .update({ ...dbData, updated_at: this.knex.fn.now() })
+      .returning("*");
+
+    return result ? this.mapDbRowToEntity(result) : null;
+  }
+
+  async delete(id: number): Promise<boolean> {
+    // Use deleteWithValidation to prevent deletion of last config
+    return this.deleteWithValidation(id);
+  }
+
+  // ==================== CUSTOM METHODS ====================
+
+  /**
+   * 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;
+
+    if (totalCount <= 1) {
+      throw new Error(
+        "Cannot delete the last configuration. At least one configuration must exist.",
+      );
+    }
+
+    const result = await this.knex(this.tableName).where("id", id).del();
+    return result > 0;
+  }
+
+  /**
+   * 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;
+    }
+
+    return this.mapDbRowToEntity(result);
+  }
+
+  /**
+   * 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 });
+
+      // Set new default
+      await trx(this.tableName).where("id", id).update({ is_default: true });
     });
-  return result;
-}
 
-// Bulk assign camera to multiple videos
-async bulkUpdateCamera(
-  videoIds: number[],
-  cameraId: number | null
-): Promise<number> {
-  if (videoIds.length === 0) return 0;
-
-  const result = await this._knex("video")
-    .whereIn("id", videoIds)
-    .update({
-      cameraId: cameraId,
-      updated_at: this._knex.fn.now()
-    });
-  return result;
+    return true;
+  }
+
+  /**
+   * 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 };
+    }
+
+    if (!config.customClasses || !Array.isArray(config.customClasses)) {
+      errors.push("customClasses must be an array");
+      return { valid: false, errors };
+    }
+
+    // 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");
+    }
+
+    // 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)`);
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * 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;
+      }
+    }
+
+    // Step 2: Apply user configuration (FHWA classes → Custom classes)
+    const customCounts: Record<string, number> = {};
+
+    for (const customClass of configuration.customClasses) {
+      let total = 0;
+
+      for (const fhwaClass of customClass.fhwaClasses) {
+        total += fhwaCounts[fhwaClass] || 0;
+      }
+
+      customCounts[customClass.name] = Math.round(total);
+    }
+
+    return customCounts;
+  }
+
+  // ==================== 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,
+    };
+  }
+
+  private mapDbRowsToEntities(rows: any[]): IReportConfiguration[] {
+    return rows.map((row) => this.mapDbRowToEntity(row));
+  }
+
+  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;
+
+    return dbRow;
+  }
 }
 
-// Get videos by multiple folder IDs (for folder camera propagation)
-async getVideosByFolderIds(folderIds: number[]): Promise<IVideo[]> {
-  if (folderIds.length === 0) return [];
+export default ReportConfigurationDAO;
+```
+
+---
+
+## Integration with VideoMinuteResultDAO
 
-  return await this._knex("video")
-    .whereIn("folderId", folderIds)
-    .select("id", "uuid", "name", "folderId", "cameraId");
+### Modifications Required
+
+The `VideoMinuteResultDAO` must be modified to accept and apply report configurations during aggregation.
+
+**File:** `src/dao/VideoMinuteResultDAO.ts`
+
+### Changes to Method Signatures
+
+```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>
+```
+
+### Integration Strategy
+
+1. **Import ReportConfigurationDAO:**
+
+   ```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
+
+3. **Modify aggregateATRResults() (lines 590-642):**
+   - Accept `configuration` parameter
+   - Remove `normalizeATRVehicleClass()` calls (lines 606, 634)
+   - Apply configuration transformation instead
+
+4. **Add new helper method:**
+
+   ```typescript
+   private async fetchConfiguration(configurationId?: number): Promise<IReportConfigurationData> {
+     const configDAO = new ReportConfigurationDAO();
+
+     let config: IReportConfiguration | null;
+
+     if (configurationId) {
+       config = await configDAO.getById(configurationId);
+     } else {
+       config = await configDAO.getDefault();
+     }
+
+     if (!config) {
+       throw new Error("No report configuration found");
+     }
+
+     return config.configuration;
+   }
+   ```
+
+5. **Update aggregation flow:**
+
+   ```typescript
+   // In getGroupedMinuteResultsByVideoUuid()
+   const configuration = await this.fetchConfiguration(configurationId);
+
+   const aggregatedGroups: IGroupedResult[] = rows.map((row: any) => {
+     // ... existing aggregation logic ...
+
+     let aggregatedResult;
+     if (studyType === "TMC") {
+       aggregatedResult = this.aggregateTMCResults(allResults, configuration);
+     } else {
+       aggregatedResult = this.aggregateATRResults(allResults, configuration);
+     }
+
+     // ... return result ...
+   });
+   ```
+
+### Detailed Transformation Example (ATR)
+
+**Before transformation (raw detection labels):**
+
+```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
+  }
 }
 ```
 
-## Query Performance Strategies
+**After applying configuration:**
 
-### 1. Camera Search Optimization
+```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
+  }
+}
+```
 
-- **Index Strategy:** Case-insensitive BTREE index on `LOWER(name)`
-- **Query Pattern:** `WHERE LOWER(name) LIKE LOWER(?)`
-- **Full-text Option:** GIN index with `to_tsvector()` for fuzzy search
-- **Expected Performance:** O(log n) lookup instead of O(n) scan
+---
 
-### 2. Bulk Operation Optimization
+## Export Updates
 
-- **Transaction Wrapping:** All bulk operations in single transactions
-- **Batch Size Limits:** Process in chunks of 1000 records max
-- **Index Usage:** Leverage existing primary key and foreign key indexes
+### File: `src/index.ts`
 
-### 3. Folder Camera Cascade Optimization
+Add exports for new DAO and interfaces:
 
-- **Single Query Strategy:** Use `WHERE folderId = ?` leveraging existing index
-- **Atomic Updates:** Single UPDATE statement rather than individual updates
-- **Expected Performance:** O(log n) folder lookup + O(k) video updates
+```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";
+```
+
+---
 
 ## Implementation Order
 
-1. **Migration First:** Deploy camera name search index
-2. **DAO Methods:** Add optimized search and bulk operation methods
-3. **Transaction Optimization:** Implement proper transaction handling
-4. **Testing:** Validate performance improvements
+### Phase 1: Database Foundation
 
-## Risk Assessment
+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)
 
-### Migration Safety: LOW RISK
+### Phase 2: DAO Implementation
 
-- Adding indexes is non-blocking operation
-- No data changes, only performance improvements
-- Easy rollback with down migration
+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
 
-### Performance Impact: HIGH BENEFIT
+### Phase 3: Integration
 
-- Camera search: 100x-1000x improvement (O(n) → O(log n))
-- Bulk operations: Proper indexing already exists
-- Folder cascade: Leverages existing folderId index
+10. Modify `VideoMinuteResultDAO.aggregateTMCResults()`
+11. Modify `VideoMinuteResultDAO.aggregateATRResults()`
+12. Remove `normalizeATRVehicleClass()` calls
+13. Add `fetchConfiguration()` helper
+14. Update method signatures to accept `configurationId`
 
-### Pattern Compliance: 100% COMPLIANT
+### Phase 4: Exports & Build
 
-- Follows existing DAO patterns exactly
-- Maintains IBaseDAO interface requirements
-- Uses established naming conventions
-- Preserves UUID external API pattern
+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
 
-## Validation Strategy
+---
 
-### Performance Testing Queries
+## Risks & Concerns
 
-```sql
--- Test camera search performance
-EXPLAIN ANALYZE SELECT * FROM cameras
-WHERE LOWER(name) LIKE '%traffic%'
-ORDER BY name LIMIT 20;
-
--- Test video-by-camera lookup
-EXPLAIN ANALYZE SELECT * FROM video
-WHERE cameraId = 1
-ORDER BY created_at DESC LIMIT 20;
-
--- Test folder cascade update
-EXPLAIN ANALYZE UPDATE video
-SET cameraId = 1 WHERE folderId = 5;
+### 🔴 CRITICAL: Detection Label Mapping Assumption
+
+**Risk:** The `DETECTION_LABEL_TO_FHWA` mapping is based on user clarifications, but there's no guarantee that video processing returns exactly these labels.
+
+**Mitigation:**
+
+- 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)
+
+### 🟡 MEDIUM: Performance at Minute-Level Granularity
+
+**Risk:** Applying configuration transformation at minute-level for 100+ videos could be slow.
+
+**Current Decision:** Apply transformation on-the-fly (per user clarification Q10.2).
+
+**Future Optimization:**
+
+- Cache configuration object in memory (singleton pattern)
+- Pre-compute transformed results and store in separate JSONB column
+- Add database-level JSONB transformation functions
+
+### 🟡 MEDIUM: Replacement of normalizeATRVehicleClass()
+
+**Risk:** Existing API clients may expect normalized class names (`cars`, `mediums`, `heavy_trucks`).
+
+**Mitigation:**
+
+- Default configuration seed matches current normalization
+- API will return same class names initially (backwards compatible)
+- Users can create custom configurations as needed
+
+### 🟢 LOW: Migration Safety
+
+**Risk:** Minimal - only creates new table with seed data.
+
+**Rollback:** Clean rollback with `down()` migration drops table entirely.
+
+---
+
+## Testing Strategy
+
+### Unit Tests (DAO Level)
+
+```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");
+});
+```
+
+### Integration Tests (VideoMinuteResultDAO)
+
+```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");
+});
+```
+
+---
+
+## Performance Considerations
+
+### Query Optimization
+
+**Configuration Lookup:**
+
+- 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
+
+**Transformation:**
+
+- `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
+
+### Caching Strategy (Future)
+
+```typescript
+class ReportConfigurationCache {
+  private static instance: Map<number, IReportConfigurationData> = new Map();
+
+  static get(id: number): IReportConfigurationData | undefined {
+    return this.instance.get(id);
+  }
+
+  static set(id: number, config: IReportConfigurationData): void {
+    this.instance.set(id, config);
+  }
+
+  static clear(): void {
+    this.instance.clear();
+  }
+}
 ```
 
-### Success Metrics
+---
+
+## Open Questions & Future Enhancements
+
+### 1. Unmapped FHWA Classes Display
+
+**Question:** Should the API response indicate which FHWA classes were excluded?
+
+**Example:**
+
+```json
+{
+  "customClasses": {
+    "Cars": 100,
+    "Heavy Trucks": 50
+  },
+  "unmappedCounts": {
+    "fhwaClass4": 10,
+    "fhwaClass5": 5
+  }
+}
+```
+
+**Recommendation:** Add this as optional metadata for debugging purposes.
+
+### 2. Configuration Change History
+
+**Question:** Should we track configuration changes over time?
+
+**Future Enhancement:** Add `report_configuration_history` table to track when configurations are created/modified.
+
+### 3. Pedestrians & Bicycles
+
+**Question:** Current system excludes pedestrians/bicycles from FHWA mapping. Should users be able to create custom classes for non-motorized traffic?
+
+**Recommendation:** Support this by adding FHWA classes 14-15 (non-motorized) in future iteration.
+
+### 4. Detection Label Variability
+
+**Question:** What if video processing returns different detection labels than expected?
+
+**Recommendation:** Add logging and admin dashboard to monitor unmapped detection labels.
+
+---
+
+## Validation Checklist
+
+Before marking this plan as complete, verify:
+
+- [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
+
+---
+
+## Pattern Compliance
+
+### 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)
+
+### DAO Patterns ✅
+
+- Implements `IBaseDAO<IReportConfiguration>`
+- Singleton KnexManager connection
+- Methods: create, getById, getByUuid, getAll, update, delete
+- Custom methods: deleteWithValidation, getDefault, setDefault, validateConfiguration, applyConfiguration
+
+### File Naming ✅
+
+- Migration: `YYYYMMDDHHMMSS_create_report_configurations.ts`
+- DAO: `report-configuration.dao.ts`
+- Interface: `report-configuration.interfaces.ts` (matches folder structure)
+
+### Performance ✅
+
+- Indexed UUID for fast lookups
+- JOINs eliminated (no foreign keys, system-wide table)
+- Pagination implemented in getAll()
+- Future: Consider caching for frequently accessed configurations
+
+---
+
+## Next Steps for Orchestrator
+
+This plan is now ready for handoff to the **knex-code-agent** for implementation.
+
+**Orchestrator should:**
+
+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-code-agent should:**
+
+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:**
+
+- None identified. Plan is complete and ready for implementation.
+
+---
+
+## Appendix: FHWA 13-Class System Reference
+
+```
+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
+```
 
-- Camera search < 50ms for 10k+ cameras
-- Video-by-camera < 100ms for 1k+ videos
-- Folder cascade < 200ms for 100+ videos per folder
-- Bulk video update < 500ms for 1000+ videos
+**Detection Label Mapping:**
 
-## Conclusion
+- 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
 
-**Current Status:** Schema is well-designed with most needed indexes already present. Only critical gap is camera name search optimization.
+---
 
-**Priority:** HIGH for camera name search index, MEDIUM for DAO method enhancements.
+## Document Version
 
-**Complexity:** LOW - Single migration required, standard DAO patterns.
+- **Version:** 1.0
+- **Date:** 2025-09-30
+- **Author:** Database Planning Specialist (Claude)
+- **Status:** FINAL - Ready for Implementation