Skip to main content

Data Flow

This page describes how data moves through FOVEA during common operations using sequence diagrams.

Annotation Creation Flow​

When a user creates an annotation, the data flows from the frontend through Redux to the backend and PostgreSQL.

Flow Steps:

  1. User draws bounding box in video player
  2. Frontend dispatches Redux action to add keyframe
  3. Redux interpolation engine generates frames between keyframes
  4. Frontend displays interpolated boxes in real-time
  5. User clicks Save button
  6. Frontend sends POST request to backend API
  7. Backend creates annotation via Prisma ORM
  8. Prisma inserts record into PostgreSQL
  9. Backend returns created annotation to frontend
  10. Frontend updates Redux state and shows success notification

Export Flow​

Export generates JSON Lines files containing ontologies, world objects, and annotations.

Flow Steps:

  1. User clicks Export button in toolbar
  2. Frontend displays export options dialog
  3. User selects export mode (keyframes-only or fully interpolated)
  4. Frontend sends GET request to backend with options
  5. Backend queries annotations from database via Prisma
  6. For keyframes-only mode, backend extracts keyframes and interpolation configs
  7. Backend generates JSON Lines format (one object per line)
  8. Frontend receives file and triggers browser download
  9. User saves file to local filesystem

Export Optimization: Keyframes-only mode produces files 90% smaller than fully interpolated mode while preserving all annotation intent.

Import Flow with Conflict Resolution​

Import validates JSON Lines files and resolves conflicts before persisting data.

Flow Steps:

  1. User drags JSON Lines file to import dialog
  2. Frontend sends preview request to backend
  3. Backend validates sequence structure (keyframes, interpolation, visibility)
  4. Backend checks for duplicate IDs in database
  5. Backend returns preview with conflict warnings
  6. User reviews conflicts and chooses resolution strategy
  7. Frontend sends import request with resolution options
  8. Backend applies conflict resolution (skip, replace, merge)
  9. Backend performs database upsert via Prisma
  10. Frontend displays import results (items imported, skipped, errors)

Conflict Types:

  • Duplicate sequence IDs
  • Overlapping frame ranges
  • Invalid interpolation configurations
  • Missing persona or video references

Tracking Job Flow (BullMQ)​

Automated tracking uses BullMQ job queue for long-running operations.

Flow Steps:

  1. User clicks "Run Tracking" button in detection dialog
  2. Frontend sends POST request to backend with tracking options
  3. Backend creates BullMQ job with video ID and model config
  4. BullMQ adds job to Redis queue
  5. Backend returns job ID to frontend (202 Accepted)
  6. Frontend polls job status every 2 seconds
  7. BullMQ worker picks job from Redis queue
  8. Worker calls model service /track endpoint
  9. Model service runs tracking algorithm (e.g., ByteTrack, SAMURAI)
  10. Model service returns tracking results to worker
  11. Worker stores results and marks job complete
  12. Frontend receives results and displays tracking candidates
  13. User reviews and accepts/rejects tracks

Job Status Flow: pending → active → completed (or failed)

Next Steps​