detections/_docs/02_tasks/backlog/AZ-172_distributed_architecture_adaptation.md

Distributed Architecture Adaptation

Task: AZ-172_distributed_architecture_adaptation Name: Adapt detections module for distributed architecture: stream-based input & DB-driven AI config Description: Replace the co-located file-path-based detection flow with stream-based input and DB-driven configuration, enabling UI to run on a separate device from the detections API. Complexity: 5 points Dependencies: Annotations service (C# backend) needs endpoints for per-user AI config and Media management Component: Architecture Jira: AZ-172

Problem

The detections module assumes co-located deployment (same machine as the WPF UI). The UI sends local file paths, and inference reads files directly from disk:

• inference.pyx → _process_video() opens local video via cv2.VideoCapture(<str>video_name)
• inference.pyx → _process_images() reads local images via cv2.imread(<str>path)
• ai_config.pyx has a paths: list[str] field carrying local filesystem paths
• AIRecognitionConfig is passed from UI as a dict (via the config_dict parameter in run_detect)

In the new distributed architecture, UI runs on a separate device (laptop, tablet, phone). The detections module is a standalone API on a different device. Local file paths are meaningless.

Outcome

• Video detection works with streamed input (no local file paths required)
• Video is simultaneously saved to disk and processed frame-by-frame
• Image detection works with uploaded bytes (no local file paths required)
• AIRecognitionConfig is fetched from DB by userId, not passed from UI
• Media table records created on upload with correct XxHash64 Id, path, type, status
• Old path-based code removed

Subtasks

Jira	Summary	Points
AZ-173	Replace path-based run_detect with stream-based API in inference.pyx	3
AZ-174	Fetch AIRecognitionConfig from DB by userId instead of UI-passed config	2
AZ-175	Integrate Media table: create record on upload, store file, track status	2
AZ-176	Clean up obsolete path-based code and old methods	1

Acceptance Criteria

AC-1: Stream-based video detection Given a video is uploaded via HTTP to the detection API When the detections module processes it Then frames are decoded and run through inference without requiring a local file path from the caller

AC-2: Concurrent write and detect for video Given a video stream is being received When the detection module processes it Then the stream is simultaneously written to persistent storage AND processed frame-by-frame for detection

AC-3: Stream-based image detection Given an image is uploaded via HTTP to the detection API When the detections module processes it Then the image bytes are decoded and run through inference without requiring a local file path

AC-4: DB-driven AI config Given a detection request arrives with a userId (from JWT) When the detection module needs AIRecognitionConfig Then it fetches AIRecognitionSettings + CameraSettings from the DB via the annotations service, not from the request payload

AC-5: Default config on user creation Given a new user is created in the system When their account is provisioned Then default AIRecognitionSettings and CameraSettings rows are created for that user

AC-6: Media record lifecycle Given a file is uploaded for detection When the upload is received Then a Media record is created (XxHash64 Id, Name, Path, MediaType, UserId) and MediaStatus transitions through New → AIProcessing → AIProcessed (or Error)

AC-7: Old code removed Given the refactoring is complete When the codebase is reviewed Then no references to paths in AIRecognitionConfig, no cv2.VideoCapture(local_path), no cv2.imread(local_path), and no is_video(filepath) remain

File Changes

File	Action	Description
src/inference.pyx	Modified	Replace run_detect with stream-based methods; remove path iteration
src/ai_config.pxd	Modified	Remove paths field
src/ai_config.pyx	Modified	Remove paths field; adapt from_dict
src/main.py	Modified	Fetch config from DB; handle Media records; adapt endpoints
src/loader_http_client.pyx	Modified	Add method to fetch user AI config from annotations service

Technical Notes

• cv2.VideoCapture can read from a named pipe or a file being appended to. Alternative: feed frames via a queue from the HTTP upload handler, or use PyAV for direct byte-stream decoding
• The annotations service (C# backend) owns the DB. Config retrieval requires API endpoints on that service
• XxHash64 ID generation algorithm is documented in _docs/00_database_schema.md
• Token management (JWT refresh) is already implemented in main.py via TokenManager
• DB tables AIRecognitionSettings and CameraSettings exist in schema but are not yet linked to Users; need FK or join table

Risks & Mitigation

Risk 1: Concurrent write + read of video file

• Risk: cv2.VideoCapture may fail or stall reading an incomplete file
• Mitigation: Use a frame queue pipeline (one thread writes, another reads) or PyAV for byte-stream decoding

Risk 2: Annotations service API dependency

• Risk: New endpoints needed on the C# backend for config retrieval and Media management
• Mitigation: Define API contract upfront; detections module can use fallback defaults if service is unreachable

Risk 3: Config-to-User linking not yet in DB

• Risk: AIRecognitionSettings and CameraSettings tables have no FK to Users
• Mitigation: Add UserId FK or create a UserAIConfig join table in the backend migration