@trafficgroup/knex-rel 0.1.3 → 0.1.4

package/cameras_analysis.md

@@ -1,199 +0,0 @@
-# Database Schema Analysis - Cameras Table Implementation
-
-## Current Schema Analysis
-
-### 1. Videos Table (Current Structure)
-
-- **Table Name**: `video`
-- **Primary Key**: `id` (auto-increment number)
-- **UUID**: `uuid` (unique, not null) - for external references
-- **Foreign Keys**:
-  - `folderId`: references `folders.id` (CASCADE delete)
-  - `cameraId`: references `cameras.id` (SET NULL on delete) ✅ **ALREADY EXISTS**
-  - `annotationSourceId`: self-reference to `video.id` (SET NULL)
-- **Key Fields**:
-  - `videoLocation`: S3 path/URL for video file
-  - `videoRate`: frame rate (FPS)
-  - `videoType`: enum ['TMC', 'ATR', 'JUNCTION', 'ROUNDABOUT', 'PATHWAY']
-  - `status`: enum ['QUEUED', 'PROCESSING', 'COMPLETED', 'FAILED', 'PENDING']
-  - `metadata`: JSONB for lane annotations
-  - `results`: JSONB for processing results
-- **Timestamps**: `created_at`, `updated_at`
-- **Indexes**:
-  - `uuid` (unique)
-  - `cameraId`
-  - `annotationSourceId`
-  - Composite: `(folderId, videoType, status)`
-
-### 2. Folders Table (Current Structure)
-
-- **Table Name**: `folders`
-- **Primary Key**: `id` (auto-increment number)
-- **UUID**: `uuid` (unique, not null) - for external references
-- **Foreign Keys**:
-  - `createdBy`: references `user.id` (CASCADE delete)
-  - `studyId`: references `study.id` (CASCADE delete)
-  - `cameraId`: references `cameras.id` (SET NULL on delete) ✅ **ALREADY EXISTS**
-- **Key Fields**:
-  - `name`: folder name
-  - `status`: enum ['UPLOADING', 'COMPLETE']
-- **Timestamps**: `created_at`, `updated_at`
-- **Indexes**:
-  - `uuid` (unique)
-  - `cameraId`
-
-### 3. Cameras Table (Current Structure) ✅ **ALREADY IMPLEMENTED**
-
-- **Table Name**: `cameras`
-- **Primary Key**: `id` (auto-increment number)
-- **UUID**: `uuid` (unique, not null) - for external references
-- **Fields**:
-  - `name`: string(100), not null
-  - `longitude`: decimal(10,7), not null
-  - `latitude`: decimal(10,7), not null
-- **Timestamps**: `created_at`, `updated_at`
-- **Indexes**:
-  - `uuid` (unique)
-  - Composite: `(longitude, latitude)` for geospatial queries
-
-## Relationship Analysis
-
-### Current Relationships ✅ **FULLY IMPLEMENTED**
-
-1. **Study → Folders** (One-to-Many)
-   - Foreign key: `folders.studyId → study.id`
-   - Cascade delete: deleting study removes all folders
-
-2. **Folders → Videos** (One-to-Many)
-   - Foreign key: `video.folderId → folders.id`
-   - Cascade delete: deleting folder removes all videos
-
-3. **Cameras → Folders** (One-to-Many) ✅
-   - Foreign key: `folders.cameraId → cameras.id`
-   - SET NULL on delete: deleting camera keeps folders but removes reference
-
-4. **Cameras → Videos** (One-to-Many) ✅
-   - Foreign key: `video.cameraId → cameras.id`
-   - SET NULL on delete: deleting camera keeps videos but removes reference
-
-5. **Videos → Videos** (Self-Reference for Templates)
-   - Foreign key: `video.annotationSourceId → video.id`
-   - Used for lane annotation templates
-
-## DAO Implementation Status
-
-### CameraDAO ✅ **FULLY IMPLEMENTED**
-
-- **File**: `src/dao/camera/camera.dao.ts`
-- **Standard Methods**: create, getById, getByUuid, update, delete, getAll ✅
-- **Custom Methods**:
-  - `getByName(name: string)`: Find camera by name ✅
-  - `getCamerasNearCoordinates(lng, lat, radius)`: Geospatial search using PostGIS ✅
-- **Performance Features**: Uses PostGIS ST_DWithin for geographic queries ✅
-
-### VideoDAO - Camera Integration ✅ **ALREADY INTEGRATED**
-
-- **JOIN Queries**: Already includes folder data in getById/getByUuid ✅
-- **Camera Support**: Interface includes `cameraId?: number` and `camera?: ICamera` ✅
-- **Note**: DAO doesn't currently JOIN camera data, but interface supports it
-
-### FolderDAO - Camera Integration ✅ **ALREADY INTEGRATED**
-
-- **JOIN Queries**: Already includes study data in getById/getByUuid ✅
-- **Camera Support**: Interface includes `cameraId?: number` and `camera?: ICamera` ✅
-- **Note**: DAO doesn't currently JOIN camera data, but interface supports it
-
-## Migration Status ✅ **COMPLETE**
-
-**Migration**: `20250911000000_migration.ts` ✅ **ALREADY DEPLOYED**
-
-- Creates `cameras` table with proper schema ✅
-- Adds `cameraId` to `video` table with foreign key ✅
-- Adds `cameraId` to `folders` table with foreign key ✅
-- Proper indexes for performance ✅
-- Safe rollback implementation ✅
-
-## Interface Implementation Status ✅ **COMPLETE**
-
-### ICamera ✅ **FULLY IMPLEMENTED**
-
-- **File**: `src/interfaces/camera/camera.interfaces.ts`
-- **Fields**: id, uuid, name, longitude, latitude, created_at, updated_at ✅
-- **Export**: Properly exported in `src/index.ts` ✅
-
-### IVideo ✅ **CAMERA INTEGRATION COMPLETE**
-
-- **Camera Fields**: `cameraId?: number`, `camera?: ICamera` ✅
-- **Relationships**: Imports ICamera interface ✅
-
-### IFolder ✅ **CAMERA INTEGRATION COMPLETE**
-
-- **Camera Fields**: `cameraId?: number`, `camera?: ICamera` ✅
-- **Relationships**: Imports ICamera interface ✅
-
-## Performance Considerations ✅ **OPTIMIZED**
-
-### Database Indexes ✅
-
-- `cameras.uuid` (unique) - for UUID lookups ✅
-- `cameras(longitude, latitude)` - for geospatial queries ✅
-- `video.cameraId` - for camera-to-videos lookups ✅
-- `folders.cameraId` - for camera-to-folders lookups ✅
-
-### Query Optimization ✅
-
-- **VideoDAO**: Uses JOINs to eliminate N+1 queries (folder data) ✅
-- **FolderDAO**: Uses JOINs to eliminate N+1 queries (study data) ✅
-- **CameraDAO**: Geospatial queries use PostGIS for performance ✅
-
-### Missing JOIN Optimizations (Minor Enhancement Opportunity)
-
-- VideoDAO could JOIN camera data in getById/getByUuid queries
-- FolderDAO could JOIN camera data in getById/getByUuid queries
-- These would eliminate additional queries when camera data is needed
-
-## System Architecture Compliance ✅
-
-### Pattern Compliance ✅
-
-- **Naming**: Follows `entityUuid` pattern for external references ✅
-- **Timestamps**: Uses `created_at`/`updated_at` consistently ✅
-- **Primary Keys**: Auto-increment `id` for internal use ✅
-- **Foreign Keys**: Proper referential integrity with appropriate cascade rules ✅
-
-### TypeScript Integration ✅
-
-- **Type Safety**: Full TypeScript interfaces with proper typing ✅
-- **Optional Fields**: Camera relationships marked as optional ✅
-- **Export Structure**: All entities properly exported from main index ✅
-
-## Current Implementation Status: ✅ **COMPLETE**
-
-### What's Already Working:
-
-1. **Database Schema**: Cameras table exists with proper relationships ✅
-2. **Migrations**: All database changes deployed ✅
-3. **DAOs**: CameraDAO fully implemented with geospatial features ✅
-4. **Interfaces**: All TypeScript interfaces support camera relationships ✅
-5. **Exports**: All components properly exported ✅
-6. **Relationships**: Many-to-one relationships correctly implemented ✅
-7. **Performance**: Proper indexing for UUID and geospatial queries ✅
-
-### Minor Optimization Opportunities:
-
-1. **JOIN Queries**: VideoDAO and FolderDAO could include camera data in their JOIN queries
-2. **Query Performance**: Consider adding camera data to reduce roundtrips
-
-## Conclusion
-
-The cameras table implementation is **COMPLETE and FULLY FUNCTIONAL**. The database schema, migrations, DAOs, and interfaces are all properly implemented following the project's architectural patterns. The system supports:
-
-- ✅ Camera management with geographic coordinates
-- ✅ Many-to-one relationships between cameras and folders/videos
-- ✅ UUID-based external references
-- ✅ Geospatial queries for location-based camera searches
-- ✅ Proper foreign key constraints with appropriate cascade behavior
-- ✅ Full TypeScript type safety
-- ✅ Performance optimization through proper indexing
-
-**No database changes are required** - the system is ready for camera-based video processing workflows.

package/folder_cameraid_analysis.md

@@ -1,167 +0,0 @@
-# Folder Table CameraId Analysis
-
-## Issue Summary
-
-The `cameraId` column in the `folders` table is being saved as `null` despite being defined as optional in the schema and interface.
-
-## Database Schema Analysis
-
-### Current Schema (from migrations)
-
-#### Initial Folder Table Creation (20250717161310_migration.ts)
-
-```sql
-CREATE TABLE folders (
-  id SERIAL PRIMARY KEY,
-  name VARCHAR NOT NULL,
-  createdBy INTEGER NOT NULL REFERENCES user(id) ON DELETE CASCADE,
-  status ENUM('UPLOADING', 'COMPLETE') NOT NULL DEFAULT 'UPLOADING',
-  studyId INTEGER NOT NULL REFERENCES study(id) ON DELETE CASCADE,
-  created_at TIMESTAMP,
-  updated_at TIMESTAMP
-);
-```
-
-#### Camera Integration (20250911000000_migration.ts)
-
-```sql
--- Added cameraId column to folders table
-ALTER TABLE folders ADD COLUMN cameraId INTEGER NULLABLE
-  REFERENCES cameras(id) ON DELETE SET NULL;
-CREATE INDEX ON folders (cameraId);
-```
-
-### Current Interface Definition
-
-```typescript
-export interface IFolder {
-  id: number;
-  uuid: string;
-  name: string;
-  createdBy: number; // user.id
-  status: "UPLOADING" | "COMPLETE";
-  studyId: number; // study.id
-  cameraId?: number; // camera.id - OPTIONAL field
-  created_at: string;
-  updated_at: string;
-  study?: IStudy;
-  camera?: ICamera;
-}
-```
-
-## DAO Implementation Analysis
-
-### Current FolderDAO Issues
-
-1. **No Camera Relationship Joins**: The DAO queries join with `study` table but don't include `camera` joins
-2. **Missing Camera Data Population**: Queries don't populate the optional `camera` field
-3. **Basic CRUD Operations**: The `create()` method simply inserts the provided data without validation
-
-### Key Methods Analysis
-
-#### Create Method
-
-```typescript
-async create(item: IFolder): Promise<IFolder> {
-  const [createdFolder] = await this._knex("folders")
-    .insert(item)
-    .returning("*");
-  return createdFolder;
-}
-```
-
-- **Issue**: This will insert whatever `cameraId` is provided in the `item` parameter
-- **Behavior**: If `cameraId` is undefined or not provided, it will be stored as `NULL` (which is valid)
-
-#### Query Methods (getById, getByUuid, getAll)
-
-```typescript
-// Current pattern - only joins with study
-const folder = await this._knex("folders as f")
-  .innerJoin("study as s", "f.studyId", "s.id")
-  .select("f.*", this._knex.raw("to_jsonb(s.*) as study"))
-  .where("f.id", id)
-  .first();
-```
-
-- **Missing**: No LEFT JOIN with cameras table to populate camera data
-- **Impact**: Even if `cameraId` has a valid value, the `camera` object won't be populated
-
-## Root Cause Analysis
-
-### Why CameraId is Null
-
-1. **Optional Field Behavior**: Since `cameraId` is optional (`cameraId?: number`), if not explicitly provided in create requests, it defaults to `null`
-
-2. **No Default Value**: Unlike other fields, there's no database-level default value for `cameraId`
-
-3. **Application Logic Gap**: No validation or business logic to ensure `cameraId` is populated when appropriate
-
-### Database Schema is Correct
-
-The database schema properly supports `cameraId`:
-
-- ✅ Column exists and is nullable
-- ✅ Foreign key constraint to `cameras(id)`
-- ✅ Proper ON DELETE SET NULL behavior
-- ✅ Index created for performance
-
-## Recommended Solutions
-
-### 1. Immediate Fix: Verify Input Data
-
-Check what data is being passed to the `create()` method:
-
-- Log the `item` parameter in FolderDAO.create()
-- Verify if `cameraId` is being provided in the request
-
-### 2. Enhanced DAO Queries
-
-Update FolderDAO to include camera relationships:
-
-```typescript
-// Enhanced getById with camera join
-async getById(id: number): Promise<IFolder | null> {
-  const folder = await this._knex("folders as f")
-    .innerJoin("study as s", "f.studyId", "s.id")
-    .leftJoin("cameras as c", "f.cameraId", "c.id")
-    .select(
-      "f.*",
-      this._knex.raw("to_jsonb(s.*) as study"),
-      this._knex.raw("to_jsonb(c.*) as camera")
-    )
-    .where("f.id", id)
-    .first();
-  return folder || null;
-}
-```
-
-### 3. API Layer Investigation
-
-Check the API endpoints that create folders:
-
-- Verify if `cameraId` is being extracted from request body
-- Ensure DTO/validation layer passes `cameraId` through
-- Check if frontend is sending `cameraId` in requests
-
-### 4. Business Logic Validation
-
-Consider if folders should always have a camera:
-
-- If required: Add validation in create method
-- If optional: Current behavior is correct (null is valid)
-
-## Implementation Priority
-
-1. **High**: Investigate API request data flow
-2. **High**: Add camera relationship to DAO queries
-3. **Medium**: Add logging to track cameraId values
-4. **Low**: Consider business logic changes
-
-## Files to Examine Next
-
-1. `api-rel/src/controllers/folder/folder.controller.ts` - Controller logic
-2. `api-rel/src/routes/folder/` - Route definitions and DTOs
-3. Frontend folder creation forms - Check if cameraId is being sent
-
-The database schema and DAO patterns are correctly implemented. The issue likely lies in the data flow from the API/frontend layers not providing `cameraId` values during folder creation.

package/migrations/20250924000000_camera_name_search_index.ts

@@ -1,22 +0,0 @@
-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");
-  });
-
-  // Add GIN index for full-text search if needed for fuzzy matching
-  await knex.raw(`
-    CREATE INDEX idx_cameras_name_gin
-    ON cameras
-    USING GIN (to_tsvector('english', name))
-  `);
-}
-
-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");
-  });
-}