diff --git a/contracts/openapi.v1.json b/contracts/openapi.v1.json new file mode 100644 index 0000000..30a9a17 --- /dev/null +++ b/contracts/openapi.v1.json @@ -0,0 +1,1886 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "ANSVIS Server API", + "version": "1.0.0", + "description": "Standards-compliant REST API for ANSVIS. This is the v1 contract that the ANSCORE Layer 3 (Qt/QML desktop UI) codes against. The ANSVIS backend provides this surface via an adapter layer in front of its existing implementation; the legacy endpoints (no /api/v1 prefix) remain available during a single deprecation cycle.\n\n## Conventions\n- Base path: `/api/v1/`\n- Resource paths are plural kebab-case (`/cameras`, `/ai-tasks`, `/deployment-groups`).\n- Field names are `snake_case`. Units are encoded in the field name (`time_interval_seconds`, not `time_interval` with a `(s)` suffix).\n- IDs go in the path, never as a query-string key.\n- Methods: GET=read, POST=create, PUT=replace, PATCH=partial update, DELETE=remove. State-change verbs use `POST /resource/{id}/{action}` (start/stop) — pragmatic exception to pure REST.\n- Errors follow RFC 7807 (`application/problem+json`).\n- List responses use `{items, page, page_size, total, next_cursor}`.\n- Timestamps are RFC 3339 UTC strings.\n- Authentication: `Authorization: Bearer ` header. Never in URL.\n- File uploads ≤10 MB use `multipart/form-data`; larger uploads use the initiate/complete pattern with a presigned PUT URL.\n- Live event streams use Server-Sent Events (`text/event-stream`).\n- Live video uses a separate transport (HLS in v1, WebRTC later) — the UI calls `GET /cameras/{id}/liveview` to obtain a stream descriptor.\n\n## Migration aid\nEach endpoint's description ends with `Replaces:` showing the legacy ANSVIS endpoint(s) it supersedes.", + "contact": { "name": "ANSCENTER" }, + "license": { "name": "Proprietary" } + }, + "servers": [ + { "url": "https://{host}/api/v1", "variables": { "host": { "default": "localhost" } }, "description": "Production / on-prem" }, + { "url": "http://localhost:4010", "description": "Local Prism mock (run `prism mock contracts/openapi.v1.json`)" } + ], + "tags": [ + { "name": "auth", "description": "Authentication & session" }, + { "name": "users", "description": "System users (operators of the UI)" }, + { "name": "cameras", "description": "Camera devices and streams" }, + { "name": "models", "description": "AI model registry" }, + { "name": "edges", "description": "Edge devices (ANSOpenEdge etc.)" }, + { "name": "deployment-groups", "description": "Groups that bind cameras + models + rules + triggers to targets" }, + { "name": "ai-tasks", "description": "Configured AI tasks (vehicle counting, intrusion, etc.)" }, + { "name": "events", "description": "Detected events emitted by AI tasks" }, + { "name": "fr", "description": "Face Recognition: persons, faces, groups, configuration" }, + { "name": "fr-recording", "description": "Face recording / capture tasks" }, + { "name": "alpr", "description": "Automatic License Plate Recognition registrations" }, + { "name": "notifications", "description": "Recipient lists for outbound notifications" }, + { "name": "triggers", "description": "Trigger catalog and test dispatch" }, + { "name": "system", "description": "Server status, health, version, logs, updates" }, + { "name": "jobs", "description": "Asynchronous job tracking (scans, uploads, deploys)" }, + { "name": "composite", "description": "Convenience endpoints that wrap multiple primitives" } + ], + "security": [{ "BearerAuth": [] }], + "components": { + "securitySchemes": { + "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque" } + }, + "parameters": { + "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, + "PageSize": { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, + "Sort": { "name": "sort", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated fields; prefix `-` for descending. Example: `-created_at,name`" }, + "PathId": { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } + }, + "schemas": { + "Problem": { + "type": "object", + "description": "RFC 7807 problem details. Returned with the matching HTTP status code on every error.", + "required": ["type", "title", "status"], + "properties": { + "type": { "type": "string", "format": "uri", "examples": ["https://anscenter.com/errors/validation"] }, + "title": { "type": "string", "examples": ["Validation failed"] }, + "status": { "type": "integer", "examples": [422] }, + "detail": { "type": "string" }, + "instance": { "type": "string" }, + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { "type": "string" }, + "message": { "type": "string" } + } + } + } + } + }, + "PaginationMeta": { + "type": "object", + "required": ["page", "page_size", "total"], + "properties": { + "page": { "type": "integer", "minimum": 1 }, + "page_size": { "type": "integer", "minimum": 1 }, + "total": { "type": "integer", "minimum": 0 }, + "next_cursor": { "type": "string", "nullable": true } + } + }, + "JobAck": { + "type": "object", + "required": ["job_id", "status"], + "properties": { + "job_id": { "type": "string" }, + "status": { "type": "string", "enum": ["queued", "running", "succeeded", "failed", "cancelled"] }, + "links": { "type": "object", "properties": { "self": { "type": "string" } } } + } + }, + "Job": { + "type": "object", + "required": ["job_id", "status", "created_at"], + "properties": { + "job_id": { "type": "string" }, + "kind": { "type": "string", "examples": ["camera_scan", "model_upload", "config_deploy"] }, + "status": { "type": "string", "enum": ["queued", "running", "succeeded", "failed", "cancelled"] }, + "progress": { "type": "number", "minimum": 0, "maximum": 1 }, + "created_at": { "type": "string", "format": "date-time" }, + "updated_at": { "type": "string", "format": "date-time" }, + "result": { "type": "object", "additionalProperties": true, "nullable": true }, + "error": { "$ref": "#/components/schemas/Problem", "nullable": true } + } + }, + + "LoginRequest": { + "type": "object", + "required": ["username", "password"], + "properties": { + "username": { "type": "string" }, + "password": { "type": "string", "format": "password" } + } + }, + "LoginResponse": { + "type": "object", + "required": ["access_token", "expires_at", "user"], + "properties": { + "access_token": { "type": "string" }, + "refresh_token": { "type": "string", "nullable": true }, + "token_type": { "type": "string", "enum": ["Bearer"], "default": "Bearer" }, + "expires_at": { "type": "string", "format": "date-time" }, + "user": { "$ref": "#/components/schemas/User" } + } + }, + "RefreshRequest": { + "type": "object", + "required": ["refresh_token"], + "properties": { "refresh_token": { "type": "string" } } + }, + "User": { + "type": "object", + "required": ["id", "username", "access_level"], + "properties": { + "id": { "type": "integer", "format": "int64" }, + "username": { "type": "string" }, + "email": { "type": "string", "format": "email", "nullable": true }, + "phone_number": { "type": "string", "nullable": true }, + "access_level": { "type": "string", "enum": ["admin", "operator", "viewer"] }, + "group_name": { "type": "string", "nullable": true }, + "extra_settings": { "type": "string", "nullable": true }, + "created_at": { "type": "string", "format": "date-time" } + } + }, + "UserCreate": { + "type": "object", + "required": ["username", "password", "access_level"], + "properties": { + "username": { "type": "string" }, + "password": { "type": "string", "format": "password" }, + "email": { "type": "string", "format": "email" }, + "phone_number": { "type": "string" }, + "access_level": { "type": "string", "enum": ["admin", "operator", "viewer"] }, + "group_name": { "type": "string" } + } + }, + "UserUpdate": { + "type": "object", + "properties": { + "password": { "type": "string", "format": "password" }, + "email": { "type": "string", "format": "email" }, + "phone_number": { "type": "string" }, + "access_level": { "type": "string", "enum": ["admin", "operator", "viewer"] }, + "group_name": { "type": "string" } + } + }, + "UserList": { + "allOf": [ + { "$ref": "#/components/schemas/PaginationMeta" }, + { "type": "object", "required": ["items"], "properties": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } + }} + ] + }, + + "Credentials": { + "type": "object", + "properties": { + "username": { "type": "string" }, + "password": { "type": "string", "format": "password" } + } + }, + "CapturingSettings": { + "type": "object", + "required": ["mode"], + "properties": { + "mode": { "type": "string", "enum": ["timer", "trigger"], "default": "timer" }, + "time_interval_seconds": { "type": "number", "minimum": 0.01, "default": 0.1 }, + "trigger_name": { "type": "string", "default": "" } + } + }, + "Crop": { + "type": "object", + "properties": { + "left": { "type": "integer", "default": 0 }, + "top": { "type": "integer", "default": 0 }, + "right": { "type": "integer", "default": 0 }, + "bottom": { "type": "integer", "default": 0 } + } + }, + "ImageSize": { + "type": "object", + "properties": { + "width": { "type": "integer", "minimum": 0 }, + "height": { "type": "integer", "minimum": 0 } + } + }, + "Camera": { + "type": "object", + "required": ["id", "name", "driver", "address"], + "properties": { + "id": { "type": "integer", "format": "int64", "readOnly": true }, + "name": { "type": "string" }, + "driver": { "type": "string", "enum": ["rtsp", "rtmp", "srt", "mjpeg", "onvif", "webcam", "simulated_video", "simulated_image"] }, + "address": { "type": "string", "description": "URL or local path depending on driver" }, + "credentials": { "$ref": "#/components/schemas/Credentials" }, + "capturing": { "$ref": "#/components/schemas/CapturingSettings" }, + "rotation_degrees": { "type": "integer", "enum": [0, 90, 180, 270], "default": 0 }, + "crop": { "$ref": "#/components/schemas/Crop" }, + "image_size": { "$ref": "#/components/schemas/ImageSize" }, + "active": { "type": "boolean", "default": true }, + "logging_enabled": { "type": "boolean", "default": false }, + "edge_id": { "type": "integer", "nullable": true }, + "deployment_group_ids": { "type": "array", "items": { "type": "integer" }, "default": [] }, + "created_at": { "type": "string", "format": "date-time", "readOnly": true }, + "updated_at": { "type": "string", "format": "date-time", "readOnly": true } + } + }, + "CameraCreate": { + "type": "object", + "required": ["name", "driver", "address"], + "properties": { + "name": { "type": "string" }, + "driver": { "type": "string", "enum": ["rtsp", "rtmp", "srt", "mjpeg", "onvif", "webcam", "simulated_video", "simulated_image"] }, + "address": { "type": "string" }, + "credentials": { "$ref": "#/components/schemas/Credentials" }, + "capturing": { "$ref": "#/components/schemas/CapturingSettings" }, + "rotation_degrees":{ "type": "integer", "enum": [0, 90, 180, 270] }, + "crop": { "$ref": "#/components/schemas/Crop" }, + "image_size": { "$ref": "#/components/schemas/ImageSize" }, + "active": { "type": "boolean", "default": true }, + "logging_enabled": { "type": "boolean", "default": false }, + "edge_id": { "type": "integer", "nullable": true }, + "deployment_group_ids": { "type": "array", "items": { "type": "integer" } } + } + }, + "CameraUpdate": { "$ref": "#/components/schemas/CameraCreate" }, + "CameraList": { + "allOf": [ + { "$ref": "#/components/schemas/PaginationMeta" }, + { "type": "object", "required": ["items"], "properties": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/Camera" } } + }} + ] + }, + "CameraScanRequest": { + "type": "object", + "properties": { + "ip_range": { "type": "string", "examples": ["192.168.1.0/24"] }, + "credentials": { "$ref": "#/components/schemas/Credentials" }, + "timeout_seconds": { "type": "integer", "default": 10 } + } + }, + "CameraProbeRequest": { + "type": "object", + "required": ["ip"], + "properties": { + "ip": { "type": "string" }, + "port": { "type": "integer", "default": 80 }, + "username": { "type": "string" }, + "password": { "type": "string", "format": "password" } + } + }, + "CameraProfile": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "stream_uri": { "type": "string" }, + "encoding": { "type": "string" }, + "resolution": { "$ref": "#/components/schemas/ImageSize" }, + "frame_rate": { "type": "number" } + } + }, + "LiveviewDescriptor": { + "type": "object", + "required": ["url", "transport", "expires_at"], + "properties": { + "url": { "type": "string", "format": "uri" }, + "transport": { "type": "string", "enum": ["rtsp", "hls", "webrtc"] }, + "auth_token": { "type": "string", "nullable": true }, + "expires_at": { "type": "string", "format": "date-time" }, + "overlay_stream": { "type": "string", "nullable": true, "description": "Optional SSE endpoint for bbox overlays synced to PTS" } + } + }, + + "Model": { + "type": "object", + "required": ["id", "model_name", "model_type"], + "properties": { + "id": { "type": "integer", "format": "int64", "readOnly": true }, + "model_name": { "type": "string" }, + "model_type": { "type": "string", "enum": ["object_detection", "classification", "segmentation", "pose", "face_detection", "face_recognition", "ocr", "alpr", "anomaly", "custom"] }, + "classifications": { "type": "array", "items": { "type": "string" } }, + "import_date": { "type": "string", "format": "date-time" }, + "import_source": { "type": "string" }, + "model_crc": { "type": "string" }, + "model_file_path": { "type": "string" }, + "version": { "type": "integer", "default": 1 }, + "size_bytes": { "type": "integer", "format": "int64", "readOnly": true } + } + }, + "ModelUpdate": { + "type": "object", + "properties": { + "model_name": { "type": "string" }, + "classifications": { "type": "array", "items": { "type": "string" } }, + "version": { "type": "integer" } + } + }, + "ModelList": { + "allOf": [ + { "$ref": "#/components/schemas/PaginationMeta" }, + { "type": "object", "required": ["items"], "properties": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } + }} + ] + }, + "InitiateUploadRequest": { + "type": "object", + "required": ["filename", "size_bytes"], + "properties": { + "filename": { "type": "string" }, + "size_bytes": { "type": "integer", "format": "int64" }, + "checksum": { "type": "string", "description": "Hex-encoded SHA-256" } + } + }, + "InitiateUploadResponse": { + "type": "object", + "required": ["upload_id", "presigned_url", "expires_at"], + "properties": { + "upload_id": { "type": "string" }, + "presigned_url": { "type": "string", "format": "uri" }, + "method": { "type": "string", "enum": ["PUT", "POST"], "default": "PUT" }, + "headers": { "type": "object", "additionalProperties": { "type": "string" } }, + "expires_at": { "type": "string", "format": "date-time" } + } + }, + "CompleteUploadRequest": { + "type": "object", + "required": ["upload_id"], + "properties": { + "upload_id": { "type": "string" }, + "metadata": { "$ref": "#/components/schemas/Model" } + } + }, + + "OnboardCamera": { + "type": "object", + "properties": { + "device_id": { "type": "integer", "format": "int64" }, + "camera_id": { "type": "integer", "format": "int64" }, + "camera_type": { "type": "string" }, + "camera_name": { "type": "string" }, + "device_dir": { "type": "string" }, + "width": { "type": "integer" }, + "height": { "type": "integer" } + } + }, + "EdgeModelConfig": { + "type": "object", + "properties": { + "model_id": { "type": "integer", "format": "int64" }, + "model_name": { "type": "string" }, + "config_exists": { "type": "boolean" }, + "token_validated": { "type": "boolean" }, + "device_registered":{ "type": "boolean" }, + "model_optimized": { "type": "boolean" }, + "model_category": { "type": "string" }, + "model_type": { "type": "string" }, + "model_version": { "type": "string" }, + "encryption": { "type": "boolean" }, + "input_shape": { "type": "array", "items": { "type": "integer" } }, + "number_of_classes":{ "type": "integer" }, + "conf_threshold": { "type": "number" }, + "edge_device": { "type": "string" }, + "labels": { "type": "array", "items": { "type": "string" } }, + "model_conversion_type": { "type": "string" } + } + }, + "Edge": { + "type": "object", + "required": ["id", "ip", "port", "edge_type"], + "properties": { + "id": { "type": "integer", "format": "int64", "readOnly": true }, + "ip": { "type": "string" }, + "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, + "serial_number": { "type": "string" }, + "name": { "type": "string" }, + "firmware_version": { "type": "string" }, + "edge_type": { "type": "string", "examples": ["ANSOpenEdge"] }, + "deployment_date": { "type": "string", "format": "date-time" }, + "onboard_cameras": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardCamera" } }, + "onboard_video_files": { "type": "array", "items": { "type": "string" } }, + "onboard_digital_triggers": { "type": "array", "items": { "type": "string" } }, + "onboard_http_triggers": { "type": "array", "items": { "type": "string" } }, + "model_configs": { "type": "array", "items": { "$ref": "#/components/schemas/EdgeModelConfig" } }, + "active": { "type": "boolean", "default": true } + } + }, + "EdgeCreate": { "$ref": "#/components/schemas/Edge" }, + "EdgeUpdate": { + "type": "object", + "properties": { + "ip": { "type": "string" }, + "port": { "type": "integer" }, + "name": { "type": "string" }, + "firmware_version": { "type": "string" }, + "active": { "type": "boolean" } + } + }, + "EdgeList": { + "allOf": [ + { "$ref": "#/components/schemas/PaginationMeta" }, + { "type": "object", "required": ["items"], "properties": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/Edge" } } + }} + ] + }, + "EdgeHealth": { + "type": "object", + "properties": { + "reachable": { "type": "boolean" }, + "uptime_seconds": { "type": "integer" }, + "cpu_percent": { "type": "number" }, + "gpu_percent": { "type": "number" }, + "memory_percent": { "type": "number" }, + "disk_percent": { "type": "number" }, + "temperature_c": { "type": "number" }, + "checked_at": { "type": "string", "format": "date-time" } + } + }, + "EdgeStatus": { + "type": "object", + "properties": { + "state": { "type": "string", "enum": ["online", "offline", "degraded", "updating"] }, + "active_tasks": { "type": "integer" }, + "active_cameras": { "type": "integer" }, + "events_last_hour": { "type": "integer" }, + "last_seen_at": { "type": "string", "format": "date-time" } + } + }, + + "ROI": { + "type": "object", + "description": "Polygon ROI as ordered (x,y) points.", + "required": ["points"], + "properties": { + "name": { "type": "string" }, + "points": { "type": "array", "items": { + "type": "object", "required": ["x","y"], + "properties": { "x": { "type": "integer" }, "y": { "type": "integer" } } + }} + } + }, + "FilterOptions": { + "type": "object", + "properties": { + "iou_threshold": { "type": "number", "minimum": 0, "maximum": 1 }, + "camera_roi": { "$ref": "#/components/schemas/ROI" }, + "camera_roi_enabled": { "type": "boolean" }, + "image_compress": { "type": "boolean" }, + "image_compress_type": { "type": "string" } + } + }, + "ObjectRef": { + "type": "object", + "required": ["model_id", "class"], + "properties": { + "model_id": { "type": "integer", "format": "int64" }, + "class": { "type": "integer" } + } + }, + "RuleConfig": { + "type": "object", + "description": "Replaces the legacy stringified `RuleConfig` field. Fully typed.", + "properties": { + "presence_type": { "type": "string", "enum": ["object_appearing", "object_disappearing", "object_static"] }, + "duration_limit_enabled": { "type": "boolean" }, + "duration_comparison": { "type": "string", "enum": ["<", "<=", "==", ">=", ">"] }, + "duration_seconds": { "type": "number" }, + "duration_max_seconds": { "type": "number" }, + "min_count": { "type": "integer", "default": 1 }, + "max_records": { "type": "integer", "default": 1 }, + "trigger_option": { "type": "string" }, + "include_all_images": { "type": "boolean" } + } + }, + "TriggerActionConfig": { + "type": "object", + "description": "Per-trigger-type configuration. Replaces the legacy stringified `TriggerConfig` field. Use the discriminator `type` to select the right payload subset.", + "required": ["type"], + "properties": { + "type": { "type": "string", "enum": ["http", "mqtt", "email", "sms", "push", "rabbitmq", "pulsar", "digital_io"] }, + "http": { + "type": "object", + "properties": { + "url": { "type": "string", "format": "uri" }, + "method": { "type": "string", "enum": ["GET","POST","PUT","PATCH"], "default": "POST" }, + "append_image": { "type": "boolean", "default": false }, + "style": { "type": "string", "enum": ["standard", "form", "raw"], "default": "standard" }, + "extra_json": { "type": "object", "additionalProperties": true }, + "simple_text": { "type": "string" }, + "login": { + "type": "object", + "properties": { + "required": { "type": "boolean", "default": false }, + "login_url": { "type": "string", "format": "uri" }, + "login_data": { "type": "object", "additionalProperties": true }, + "token_type_name": { "type": "string" }, + "token_name": { "type": "string" } + } + } + } + }, + "mqtt": { + "type": "object", + "properties": { + "broker_url": { "type": "string" }, + "topic": { "type": "string" }, + "qos": { "type": "integer", "enum": [0,1,2], "default": 1 }, + "username": { "type": "string" }, + "password": { "type": "string", "format": "password" } + } + }, + "email": { + "type": "object", + "properties": { + "smtp_host": { "type": "string" }, + "smtp_port": { "type": "integer" }, + "from": { "type": "string", "format": "email" }, + "to": { "type": "array", "items": { "type": "string", "format": "email" } }, + "subject": { "type": "string" }, + "body": { "type": "string" } + } + }, + "rabbitmq": { + "type": "object", + "properties": { + "url": { "type": "string" }, + "exchange": { "type": "string" }, + "routing_key": { "type": "string" }, + "durable": { "type": "boolean", "default": true } + } + }, + "pulsar": { + "type": "object", + "properties": { + "service_url": { "type": "string" }, + "topic": { "type": "string" }, + "token": { "type": "string" } + } + } + } + }, + "TriggerAction": { + "type": "object", + "required": ["name", "type", "config"], + "properties": { + "id": { "type": "integer", "format": "int64", "readOnly": true }, + "name": { "type": "string" }, + "type": { "type": "string", "enum": ["http", "mqtt", "email", "sms", "push", "rabbitmq", "pulsar", "digital_io"] }, + "config": { "$ref": "#/components/schemas/TriggerActionConfig" } + } + }, + "Rule": { + "type": "object", + "required": ["join_condition", "rule_type", "objects"], + "properties": { + "join_condition": { "type": "string", "enum": ["AND", "OR"] }, + "rule_type": { "type": "string", "enum": ["presence", "inclusive", "exclusive", "count", "loitering", "crossing", "abandoned"] }, + "objects": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectRef" } }, + "rois": { "type": "array", "items": { "$ref": "#/components/schemas/ROI" } }, + "config": { "$ref": "#/components/schemas/RuleConfig" }, + "pipeline_option":{ "type": "string", "enum": ["no_pipeline", "pipeline_after"] }, + "pipeline_filters": { + "type": "object", + "properties": { + "texts": { "type": "array", "items": { "type": "string" } }, + "and": { "type": "boolean" }, + "option": { "type": "string" } + } + }, + "license_plate_group_filter": { + "type": "object", + "properties": { + "groups": { "type": "array", "items": { "type": "string" } }, + "option": { "type": "string", "enum": ["all", "any", "none"] } + } + }, + "monitoring_time_seconds": { "type": "number", "default": 0 } + } + }, + "EventTimeSchedule": { + "type": "object", + "properties": { + "days": { + "type": "object", + "properties": { + "mon": { "type": "boolean", "default": true }, + "tue": { "type": "boolean", "default": true }, + "wed": { "type": "boolean", "default": true }, + "thu": { "type": "boolean", "default": true }, + "fri": { "type": "boolean", "default": true }, + "sat": { "type": "boolean", "default": true }, + "sun": { "type": "boolean", "default": true } + } + }, + "start_time_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 }, + "end_time_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 } + } + }, + "DGEvent": { + "type": "object", + "required": ["event_name", "camera_id", "rules"], + "properties": { + "event_name": { "type": "string" }, + "camera_id": { "type": "integer", "format": "int64" }, + "onboard_camera_id": { "type": "integer" }, + "rules": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" } }, + "deactivation_seconds": { "type": "number", "default": 0 }, + "trigger_actions": { "type": "array", "items": { "$ref": "#/components/schemas/TriggerAction" } }, + "vision_post_processes":{ "type": "array", "items": { "type": "object", "additionalProperties": true } }, + "time_schedule": { "$ref": "#/components/schemas/EventTimeSchedule" }, + "post_processing": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, + "save_images": { "type": "boolean", "default": true }, + "image_series": { + "type": "object", + "properties": { + "enabled": { "type": "boolean", "default": false }, + "images_before": { "type": "integer", "default": 0 }, + "images_after": { "type": "integer", "default": 0 } + } + } + } + }, + "TrackerSettings": { + "type": "object", + "properties": { + "tracker": { "type": "string", "enum": ["none", "simple", "ans_tracker", "bytetrack", "deepsort"] }, + "time_to_remember_seconds": { "type": "number", "default": 0 }, + "class_groups": { + "type": "array", + "items": { + "type": "object", + "properties": { + "classes": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectRef" } } + } + } + } + } + }, + "DGModelConfig": { + "type": "object", + "required": ["id", "model_type"], + "properties": { + "id": { "type": "integer", "format": "int64" }, + "model_type": { "type": "string" }, + "config": { + "type": "object", + "description": "Replaces the legacy stringified `ModelConfigJson`.", + "properties": { + "filter_categories": { "type": "array", "items": { "type": "integer" } }, + "minimum_score": { "type": "number", "minimum": 0, "maximum": 1 }, + "tracking": { "type": "boolean" } + } + }, + "share_module": { "type": "boolean", "default": false }, + "custom_settings":{ "type": "object", "additionalProperties": true } + } + }, + "DeploymentGroup": { + "type": "object", + "required": ["id", "name", "camera_ids", "model_configs"], + "properties": { + "id": { "type": "integer", "format": "int64", "readOnly": true }, + "name": { "type": "string" }, + "camera_ids": { "type": "array", "items": { "type": "integer" } }, + "onboard_camera_indexes": { "type": "array", "items": { "type": "integer" } }, + "model_configs": { "type": "array", "items": { "$ref": "#/components/schemas/DGModelConfig" } }, + "device_id": { "type": "integer", "description": "0 for server PC" }, + "active": { "type": "boolean", "default": true }, + "simulate": { "type": "boolean", "default": false }, + "ai_task": { "type": "boolean", "default": false }, + "tracking": { "type": "boolean", "default": false }, + "filter_options": { "$ref": "#/components/schemas/FilterOptions" }, + "face_recognition":{ "type": "boolean", "default": false }, + "events": { "type": "array", "items": { "$ref": "#/components/schemas/DGEvent" } }, + "image_data_interval_seconds": { "type": "number", "default": 0.5 }, + "vision_settings": { + "type": "object", + "properties": { + "pre_processing": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, + "main_processing": { "type": "array", "items": { "type": "object", "additionalProperties": true } } + } + }, + "image_process_configs": { + "type": "array", + "items": { + "type": "object", + "properties": { + "camera_id": { "type": "integer" }, + "configs": { "type": "array", "items": { "type": "object", "additionalProperties": true } } + } + } + }, + "tracker_settings": { "$ref": "#/components/schemas/TrackerSettings" }, + "buffer_size": { "type": "integer", "default": 0 }, + "periodic_triggers":{ "type": "array", "items": { "type": "object", "additionalProperties": true } }, + "execution_time_seconds": { "type": "number" }, + "min_object_width": { "type": "integer" }, + "min_object_height": { "type": "integer" }, + "class_cleanup": { + "type": "object", + "properties": { + "class_checker_active": { "type": "boolean", "default": false }, + "duplicate_object_remover_active": { "type": "boolean", "default": false }, + "remove_threshold_iou_percent": { "type": "number" }, + "debug_attributes": { "type": "boolean", "default": false } + } + }, + "input_trigger_config": { + "type": "object", + "properties": { + "config_type": { "type": "string", "enum": ["periodic", "external"] }, + "monitor_duration_seconds":{ "type": "number" }, + "execution_rate_seconds": { "type": "number" }, + "run_in_background": { "type": "boolean", "default": false }, + "enabled": { "type": "boolean", "default": false } + } + } + } + }, + "DeploymentGroupList": { + "allOf": [ + { "$ref": "#/components/schemas/PaginationMeta" }, + { "type": "object", "required": ["items"], "properties": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/DeploymentGroup" } } + }} + ] + }, + "DeploymentGroupStatus": { + "type": "object", + "properties": { + "id": { "type": "integer", "format": "int64" }, + "state": { "type": "string", "enum": ["stopped", "starting", "running", "stopping", "errored"] }, + "active_since": { "type": "string", "format": "date-time", "nullable": true }, + "fps": { "type": "number" }, + "events_last_hour": { "type": "integer" }, + "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, + "error_message": { "type": "string", "nullable": true } + } + }, + + "AITaskType": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "category": { "type": "string" }, + "description": { "type": "string" }, + "default_parameters": { "type": "array", "items": { "$ref": "#/components/schemas/ParameterConfig" } } + } + }, + "ParameterConfig": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "data_type": { "type": "string", "enum": ["integer","number","string","boolean","list_single","list_multiple"] }, + "decimals": { "type": "integer" }, + "min_value": { "type": "number" }, + "max_value": { "type": "number" }, + "default_value": { "type": "string" }, + "list_items": { "type": "array", "items": { "type": "string" } } + } + }, + "ROIValue": { + "type": "object", + "properties": { + "roi_match": { "type": "string", "enum": ["centre_point", "bottom_centre", "full_overlap"] }, + "points": { "type": "array", "items": { + "type": "object", "required": ["x","y"], + "properties": { "x": { "type": "integer" }, "y": { "type": "integer" } } + }}, + "option": { "type": "string", "examples": ["both_directions"] }, + "name": { "type": "string" } + } + }, + "TriggerSchedule": { + "type": "object", + "properties": { + "days": { + "type": "object", + "properties": { + "mon": { "type": "boolean" }, "tue": { "type": "boolean" }, "wed": { "type": "boolean" }, + "thu": { "type": "boolean" }, "fri": { "type": "boolean" }, "sat": { "type": "boolean" }, "sun": { "type": "boolean" } + } + }, + "start_time_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 }, + "end_time_seconds": { "type": "integer", "minimum": 0, "maximum": 86400 } + } + }, + "AITask": { + "type": "object", + "required": ["id", "name", "task_type", "camera_id"], + "properties": { + "id": { "type": "integer", "format": "int64", "readOnly": true }, + "name": { "type": "string" }, + "task_type": { "type": "string", "examples": ["Vehicle Counting"] }, + "camera_id": { "type": "integer", "format": "int64" }, + "roi_values": { "type": "array", "items": { "$ref": "#/components/schemas/ROIValue" } }, + "parameter_configs": { "type": "array", "items": { "$ref": "#/components/schemas/ParameterConfig" } }, + "parameter_values": { "type": "array", "items": { "type": "string" } }, + "trigger_values": { "type": "array", "items": { "type": "string" } }, + "trigger_schedule": { "$ref": "#/components/schemas/TriggerSchedule" }, + "auto_start": { "type": "boolean", "default": true } + } + }, + "AITaskCreate": { + "type": "object", + "required": ["name", "task_type", "camera_id"], + "properties": { + "name": { "type": "string" }, + "task_type": { "type": "string" }, + "camera_id": { "type": "integer", "format": "int64" }, + "roi_values": { "type": "array", "items": { "$ref": "#/components/schemas/ROIValue" } }, + "parameter_values": { "type": "array", "items": { "type": "string" } }, + "trigger_values": { "type": "array", "items": { "type": "string" } }, + "trigger_schedule": { "$ref": "#/components/schemas/TriggerSchedule" }, + "auto_start": { "type": "boolean" } + } + }, + "AITaskList": { + "allOf": [ + { "$ref": "#/components/schemas/PaginationMeta" }, + { "type": "object", "required": ["items"], "properties": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/AITask" } } + }} + ] + }, + "AITaskStatus": { + "type": "object", + "properties": { + "id": { "type": "integer", "format": "int64" }, + "state": { "type": "string", "enum": ["stopped", "starting", "running", "stopping", "errored"] }, + "fps": { "type": "number" }, + "started_at": { "type": "string", "format": "date-time", "nullable": true }, + "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, + "error_message": { "type": "string", "nullable": true } + } + }, + + "EventRecord": { + "type": "object", + "required": ["id", "task_id", "camera_id", "timestamp"], + "properties": { + "id": { "type": "string", "examples": ["20240621_191241-3"] }, + "task_id": { "type": "integer", "format": "int64" }, + "camera_id": { "type": "integer", "format": "int64" }, + "task_type": { "type": "string" }, + "timestamp": { "type": "string", "format": "date-time" }, + "object": { "type": "string", "examples": ["car"] }, + "score": { "type": "number", "minimum": 0, "maximum": 1 }, + "bbox": { + "type": "object", + "properties": { + "x": { "type": "integer" }, "y": { "type": "integer" }, + "w": { "type": "integer" }, "h": { "type": "integer" } + } + }, + "track_id": { "type": "integer", "nullable": true }, + "metadata": { "type": "object", "additionalProperties": true }, + "image_url": { "type": "string", "format": "uri", "nullable": true }, + "clip_url": { "type": "string", "format": "uri", "nullable": true } + } + }, + "EventList": { + "allOf": [ + { "$ref": "#/components/schemas/PaginationMeta" }, + { "type": "object", "required": ["items"], "properties": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/EventRecord" } } + }} + ] + }, + "EventSummary": { + "type": "object", + "properties": { + "task_id": { "type": "integer" }, + "camera_id": { "type": "integer" }, + "group_by": { "type": "string", "enum": ["objects", "hour", "day", "rule"] }, + "interval": { "type": "string", "enum": ["minutes", "hours", "days"] }, + "buckets": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { "type": "string" }, + "from": { "type": "string", "format": "date-time" }, + "to": { "type": "string", "format": "date-time" }, + "count": { "type": "integer" }, + "breakdown": { "type": "object", "additionalProperties": { "type": "integer" } } + } + } + } + } + }, + + "FRPerson": { + "type": "object", + "required": ["id", "name"], + "properties": { + "id": { "type": "integer", "format": "int64", "readOnly": true }, + "name": { "type": "string" }, + "code": { "type": "string" }, + "group_ids": { "type": "array", "items": { "type": "integer" } }, + "group_names":{ "type": "array", "items": { "type": "string" } }, + "face_count": { "type": "integer", "readOnly": true }, + "created_at": { "type": "string", "format": "date-time", "readOnly": true } + } + }, + "FRPersonCreate": { + "type": "object", + "required": ["name"], + "properties": { + "name": { "type": "string" }, + "code": { "type": "string" }, + "group_ids": { "type": "array", "items": { "type": "integer" } }, + "group_names":{ "type": "array", "items": { "type": "string" } } + } + }, + "FRPersonList": { + "allOf": [ + { "$ref": "#/components/schemas/PaginationMeta" }, + { "type": "object", "required": ["items"], "properties": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/FRPerson" } } + }} + ] + }, + "FRPersonGroup": { + "type": "object", + "required": ["id", "name"], + "properties": { + "id": { "type": "integer", "format": "int64" }, + "name": { "type": "string" }, + "description": { "type": "string" }, + "person_ids": { "type": "array", "items": { "type": "integer" } } + } + }, + "FRFace": { + "type": "object", + "required": ["id", "person_id"], + "properties": { + "id": { "type": "integer", "format": "int64" }, + "person_id": { "type": "integer", "format": "int64" }, + "image_url": { "type": "string", "format": "uri" }, + "quality": { "type": "number" }, + "captured_at":{ "type": "string", "format": "date-time" } + } + }, + "FRFaceList": { + "allOf": [ + { "$ref": "#/components/schemas/PaginationMeta" }, + { "type": "object", "required": ["items"], "properties": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/FRFace" } } + }} + ] + }, + "FRConfig": { + "type": "object", + "properties": { + "known_person_threshold": { "type": "number", "minimum": 0, "maximum": 1 }, + "age_gender": { "type": "boolean" }, + "emotions": { "type": "boolean" }, + "head_pose": { "type": "boolean" }, + "min_face_size_px": { "type": "integer" } + } + }, + + "FRRecordingTaskCreate": { + "type": "object", + "required": ["camera_id"], + "properties": { + "camera_id": { "type": "integer", "format": "int64" }, + "min_face_score": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 }, + "max_faces_per_id": { "type": "integer", "default": 0 }, + "start_time": { "type": "string", "format": "date-time" }, + "stop_time": { "type": "string", "format": "date-time" }, + "max_faces_to_record": { "type": "integer", "default": 10 }, + "min_face_size_px": { "type": "integer", "default": 50 } + } + }, + "FRRecordingTask": { + "allOf": [ + { "$ref": "#/components/schemas/FRRecordingTaskCreate" }, + { "type": "object", "properties": { + "id": { "type": "integer", "format": "int64", "readOnly": true }, + "state": { "type": "string", "enum": ["created", "running", "stopped", "completed", "errored"] }, + "faces_recorded": { "type": "integer", "readOnly": true }, + "created_at": { "type": "string", "format": "date-time", "readOnly": true } + }} + ] + }, + "FRRecordingFace": { + "type": "object", + "properties": { + "face_id": { "type": "integer" }, + "task_id": { "type": "integer" }, + "image_url": { "type": "string", "format": "uri" }, + "score": { "type": "number" }, + "captured_at": { "type": "string", "format": "date-time" }, + "assigned_person_id": { "type": "integer", "nullable": true }, + "assigned_person_name":{ "type": "string", "nullable": true } + } + }, + "FRRecordingFaceAssign": { + "type": "object", + "required": ["face_ids"], + "properties": { + "face_ids": { "type": "array", "items": { "type": "integer" } }, + "person_id": { "type": "integer", "nullable": true }, + "person_name":{ "type": "string", "nullable": true } + } + }, + + "ALPRPlate": { + "type": "object", + "required": ["plate"], + "properties": { + "plate": { "type": "string" }, + "groups": { "type": "array", "items": { "type": "string" } }, + "created_at": { "type": "string", "format": "date-time", "readOnly": true } + } + }, + "ALPRPlateList": { + "allOf": [ + { "$ref": "#/components/schemas/PaginationMeta" }, + { "type": "object", "required": ["items"], "properties": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/ALPRPlate" } } + }} + ] + }, + "ALPRPlateRegisterRequest": { + "type": "object", + "required": ["plates"], + "properties": { + "plates": { "type": "array", "items": { "type": "string" } }, + "groups": { "type": "array", "items": { "type": "string" } } + } + }, + "ALPRPlateGroup": { + "type": "object", + "required": ["id", "name"], + "properties": { + "id": { "type": "integer", "format": "int64" }, + "name": { "type": "string" }, + "description": { "type": "string" } + } + }, + + "NotificationRecipient": { + "type": "object", + "required": ["id", "name"], + "properties": { + "id": { "type": "integer", "format": "int64", "readOnly": true }, + "name": { "type": "string" }, + "phone_number": { "type": "string" }, + "email": { "type": "string", "format": "email" }, + "group": { "type": "string" } + } + }, + "NotificationRecipientCreate": { + "type": "object", + "required": ["name"], + "properties": { + "name": { "type": "string" }, + "phone_number": { "type": "string" }, + "email": { "type": "string", "format": "email" }, + "group": { "type": "string" } + } + }, + "NotificationRecipientList": { + "allOf": [ + { "$ref": "#/components/schemas/PaginationMeta" }, + { "type": "object", "required": ["items"], "properties": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationRecipient" } } + }} + ] + }, + + "TriggerTestRequest": { + "type": "object", + "required": ["type", "config"], + "properties": { + "type": { "type": "string", "enum": ["http", "mqtt", "email", "sms", "push", "rabbitmq", "pulsar"] }, + "config": { "$ref": "#/components/schemas/TriggerActionConfig" }, + "payload": { "type": "object", "additionalProperties": true } + } + }, + "TriggerTestResponse": { + "type": "object", + "properties": { + "success": { "type": "boolean" }, + "status_code": { "type": "integer", "nullable": true }, + "latency_ms": { "type": "integer" }, + "response_body":{ "type": "string", "nullable": true }, + "error": { "$ref": "#/components/schemas/Problem", "nullable": true } + } + }, + + "SystemStatus": { + "type": "object", + "properties": { + "ok": { "type": "boolean" }, + "service": { "type": "string" }, + "timestamp": { "type": "string", "format": "date-time" }, + "message": { "type": "string" } + } + }, + "SystemHealth": { + "type": "object", + "properties": { + "ok": { "type": "boolean" }, + "uptime_seconds": { "type": "integer" }, + "cpu_percent": { "type": "number" }, + "memory_percent": { "type": "number" }, + "gpu_percent": { "type": "number" }, + "disk_percent": { "type": "number" }, + "active_cameras": { "type": "integer" }, + "active_ai_tasks": { "type": "integer" }, + "events_last_hour": { "type": "integer" } + } + }, + "SystemInfo": { + "type": "object", + "properties": { + "hostname": { "type": "string" }, + "os": { "type": "string" }, + "arch": { "type": "string" }, + "cpu": { "type": "string" }, + "gpu": { "type": "string" }, + "memory_gb": { "type": "number" }, + "disk_gb": { "type": "number" } + } + }, + "SystemVersion": { + "type": "object", + "properties": { + "version": { "type": "string" }, + "build_date": { "type": "string", "format": "date-time" }, + "git_commit": { "type": "string" }, + "api_version": { "type": "string", "default": "v1" } + } + }, + "SystemLogEntry": { + "type": "object", + "properties": { + "timestamp": { "type": "string", "format": "date-time" }, + "level": { "type": "string", "enum": ["debug", "info", "warn", "error", "fatal"] }, + "logger": { "type": "string" }, + "message": { "type": "string" }, + "context": { "type": "object", "additionalProperties": true } + } + }, + "SystemLogList": { + "allOf": [ + { "$ref": "#/components/schemas/PaginationMeta" }, + { "type": "object", "required": ["items"], "properties": { + "items": { "type": "array", "items": { "$ref": "#/components/schemas/SystemLogEntry" } } + }} + ] + }, + "SystemUpdateStatus": { + "type": "object", + "properties": { + "available": { "type": "boolean" }, + "current_version":{ "type": "string" }, + "latest_version":{ "type": "string" }, + "state": { "type": "string", "enum": ["idle", "downloading", "installing", "succeeded", "failed"] }, + "progress": { "type": "number", "minimum": 0, "maximum": 1 } + } + }, + + "CameraWithTasksRequest": { + "type": "object", + "required": ["camera"], + "properties": { + "camera": { "$ref": "#/components/schemas/CameraCreate" }, + "deployment_groups": { "type": "array", "items": { "$ref": "#/components/schemas/DeploymentGroup" } } + } + }, + "CameraWithTasksResponse": { + "type": "object", + "properties": { + "camera": { "$ref": "#/components/schemas/Camera" }, + "deployment_groups": { "type": "array", "items": { "$ref": "#/components/schemas/DeploymentGroup" } } + } + } + }, + "responses": { + "BadRequest": { "description": "Bad request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, + "Unauthorized": { "description": "Missing/invalid token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, + "Forbidden": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, + "NotFound": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, + "Conflict": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, + "Validation": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, + "ServerError": { "description": "Server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, + "NoContent": { "description": "Deleted / no content" } + } + }, + "paths": { + + "/auth/login": { + "post": { + "tags": ["auth"], "summary": "Log in", "security": [], + "description": "Replaces: `POST /user/Login`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, + "responses": { + "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, + "401": { "$ref": "#/components/responses/Unauthorized" }, + "422": { "$ref": "#/components/responses/Validation" } + } + } + }, + "/auth/logout": { + "post": { + "tags": ["auth"], "summary": "Invalidate the current token", + "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "401": { "$ref": "#/components/responses/Unauthorized" } } + } + }, + "/auth/refresh": { + "post": { + "tags": ["auth"], "summary": "Exchange refresh token for new access token", "security": [], + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshRequest" } } } }, + "responses": { + "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, + "401": { "$ref": "#/components/responses/Unauthorized" } + } + } + }, + + "/users": { + "get": { + "tags": ["users"], "summary": "List users", + "description": "Replaces: `GET /user/GetUsers`.", + "parameters": [{ "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Sort" }], + "responses": { + "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserList" } } } } + } + }, + "post": { + "tags": ["users"], "summary": "Create user", + "description": "Replaces (create half of): `POST /user/EditUser`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCreate" } } } }, + "responses": { + "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, + "409": { "$ref": "#/components/responses/Conflict" }, + "422": { "$ref": "#/components/responses/Validation" } + } + } + }, + "/users/{id}": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["users"], "summary": "Get user", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, + "patch": { "tags": ["users"], "summary": "Update user", + "description": "Replaces (update half of): `POST /user/EditUser`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdate" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Validation" } } }, + "delete": { "tags": ["users"], "summary": "Delete user", + "description": "Replaces: `POST /user/DeleteUser`.", + "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "404": { "$ref": "#/components/responses/NotFound" } } } + }, + + "/cameras": { + "get": { + "tags": ["cameras"], "summary": "List cameras", + "description": "Replaces: `GET /Camera` (list mode).", + "parameters": [ + { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Sort" }, + { "name": "driver", "in": "query", "schema": { "type": "string" } }, + { "name": "active", "in": "query", "schema": { "type": "boolean" } }, + { "name": "edge_id", "in": "query", "schema": { "type": "integer" } }, + { "name": "deployment_group_id", "in": "query", "schema": { "type": "integer" } } + ], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CameraList" } } } } } + }, + "post": { + "tags": ["cameras"], "summary": "Create camera", + "description": "Replaces (create half of): `POST /Camera`. Note that `Parameters(json)` is no longer a stringified blob — credentials are nested.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CameraCreate" }, + "examples": { + "rtsp": { "value": { + "name": "Front gate", + "driver": "rtsp", + "address": "rtsp://192.168.1.87:554/h264Preview_01_main", + "credentials": { "username": "root", "password": "admin123" }, + "capturing": { "mode": "timer", "time_interval_seconds": 0.1 }, + "active": true + }}, + "simulated_video": { "value": { + "name": "Sim", + "driver": "simulated_video", + "address": "video_still.mp4", + "capturing": { "mode": "timer", "time_interval_seconds": 0.05 } + }} + } + }}}, + "responses": { + "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Camera" } } }, "headers": { "Location": { "schema": { "type": "string" } } } }, + "422": { "$ref": "#/components/responses/Validation" } + } + } + }, + "/cameras/{id}": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["cameras"], "summary": "Get camera", + "description": "Replaces: `GET /Camera?{id}`.", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Camera" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, + "put": { "tags": ["cameras"], "summary": "Replace camera", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CameraUpdate" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Camera" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, + "patch": { "tags": ["cameras"], "summary": "Patch camera", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CameraUpdate" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Camera" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, + "delete": { "tags": ["cameras"], "summary": "Delete camera", + "description": "Replaces: `DELETE /Camera?{id}` and `POST /delete/Camera?{id}`.", + "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "404": { "$ref": "#/components/responses/NotFound" } } } + }, + "/cameras/{id}/snapshot": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { + "tags": ["cameras"], "summary": "Get a still snapshot from a camera", + "description": "Replaces: `GET /GetCameraImage?id={id}` and `POST /GetCameraImage?id={id}`. Returns the image bytes directly; pass `?format=url` to receive a short-lived presigned URL instead.", + "parameters": [ + { "name": "width", "in": "query", "schema": { "type": "integer" } }, + { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["jpeg", "url"], "default": "jpeg" } } + ], + "responses": { + "200": { "description": "Image bytes (or `{url}` when format=url)", "content": { + "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, + "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } } + }}, + "404": { "$ref": "#/components/responses/NotFound" } + } + } + }, + "/cameras/{id}/liveview": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { + "tags": ["cameras"], "summary": "Get a liveview stream descriptor", + "description": "New endpoint. Returns the URL + transport + short-lived auth token that the UI uses to connect to the live stream (HLS in v1, WebRTC later).", + "parameters": [ + { "name": "transport", "in": "query", "schema": { "type": "string", "enum": ["auto", "hls", "rtsp", "webrtc"], "default": "auto" } } + ], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveviewDescriptor" } } } } } + } + }, + "/cameras/scan": { + "post": { + "tags": ["cameras"], "summary": "Discover cameras on a network (ONVIF)", + "description": "Replaces: `GET /ScanCameras`. Async — returns a job acknowledgement; poll `GET /jobs/{id}` for results.", + "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CameraScanRequest" } } } }, + "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAck" } } } } } + } + }, + "/cameras/probe": { + "post": { + "tags": ["cameras"], "summary": "Probe a camera for its ONVIF profiles", + "description": "Replaces: `POST /GetCameraProfiles`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CameraProbeRequest" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CameraProfile" } } } } } } + } + }, + + "/models": { + "get": { + "tags": ["models"], "summary": "List models", + "description": "Replaces: `GET /Model`.", + "parameters": [ + { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, + { "name": "model_type", "in": "query", "schema": { "type": "string" } } + ], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } } } + }, + "post": { + "tags": ["models"], "summary": "Upload + register a model (multipart)", + "description": "Replaces: `POST /Model?{id}` (multipart). For files >100 MB use `/models:initiate-upload` instead.", + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": ["file", "metadata"], + "properties": { + "file": { "type": "string", "format": "binary" }, + "metadata": { "$ref": "#/components/schemas/Model" } + } + } + } + } + }, + "responses": { + "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, + "422": { "$ref": "#/components/responses/Validation" } + } + } + }, + "/models/{id}": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["models"], "summary": "Get model", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, + "patch": { "tags": ["models"], "summary": "Update model metadata (not the binary)", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelUpdate" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, + "delete": { "tags": ["models"], "summary": "Delete model", + "description": "Replaces: `DELETE /Model?{id}` and `POST /delete/Model?{id}`.", + "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "404": { "$ref": "#/components/responses/NotFound" } } } + }, + "/models:initiate-upload": { + "post": { + "tags": ["models"], "summary": "Begin a large-model upload (presigned URL)", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateUploadRequest" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateUploadResponse" } } } } } + } + }, + "/models:complete-upload": { + "post": { + "tags": ["models"], "summary": "Finalize a large-model upload", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteUploadRequest" } } } }, + "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } } } + } + }, + + "/edges": { + "get": { + "tags": ["edges"], "summary": "List edge devices", + "description": "Replaces: `GET /Edge`.", + "parameters": [{ "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeList" } } } } } + }, + "post": { + "tags": ["edges"], "summary": "Register an edge device", + "description": "Replaces (create half of): `POST /Edge`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeCreate" } } } }, + "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Edge" } } } } } + } + }, + "/edges/{id}": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["edges"], "summary": "Get edge", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Edge" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, + "patch": { "tags": ["edges"], "summary": "Update edge", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeUpdate" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Edge" } } } } } }, + "delete": { "tags": ["edges"], "summary": "Delete edge", + "description": "Replaces: `DELETE /Edge?{id}` and `POST /delete/Edge?{id}`.", + "responses": { "204": { "$ref": "#/components/responses/NoContent" } } } + }, + "/edges/{id}/health": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["edges"], "summary": "Get edge health metrics", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeHealth" } } } } } } + }, + "/edges/{id}/status": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["edges"], "summary": "Get edge operational status", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeStatus" } } } } } } + }, + + "/deployment-groups": { + "get": { + "tags": ["deployment-groups"], "summary": "List deployment groups", + "description": "Replaces: `GET /DeploymentGroup`.", + "parameters": [{ "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "name": "active", "in": "query", "schema": { "type": "boolean" } }], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentGroupList" } } } } } + }, + "post": { + "tags": ["deployment-groups"], "summary": "Create deployment group", + "description": "Replaces (create half of): `POST /DeploymentGroup`. All previously stringified JSON fields (`RuleConfig`, `TriggerConfig`, `ModelConfigJson`, `Config`) are now typed nested objects.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentGroup" } } } }, + "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentGroup" } } } } } + } + }, + "/deployment-groups/{id}": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["deployment-groups"], "summary": "Get deployment group", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentGroup" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, + "put": { "tags": ["deployment-groups"], "summary": "Replace deployment group", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentGroup" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentGroup" } } } } } }, + "delete": { "tags": ["deployment-groups"], "summary": "Delete deployment group", + "description": "Replaces: `DELETE /DeploymentGroup?{id}` and `POST /delete/DeploymentGroup?{id}`.", + "responses": { "204": { "$ref": "#/components/responses/NoContent" } } } + }, + "/deployment-groups/{id}/status": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["deployment-groups"], "summary": "Get runtime status", + "description": "Replaces: `GET /DeploymentGroupStatus?{id}`.", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentGroupStatus" } } } } } } + }, + "/deployment-groups/{id}/start": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "post": { "tags": ["deployment-groups"], "summary": "Start deployment group", + "description": "Replaces: `GET /DeploymentGroupControl?{id}&state=start`.", + "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentGroupStatus" } } } } } } + }, + "/deployment-groups/{id}/stop": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "post": { "tags": ["deployment-groups"], "summary": "Stop deployment group", + "description": "Replaces: `GET /DeploymentGroupControl?{id}&state=stop`.", + "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentGroupStatus" } } } } } } + }, + + "/ai-tasks": { + "get": { + "tags": ["ai-tasks"], "summary": "List AI tasks", + "description": "Replaces: `GET /AI-Task`.", + "parameters": [ + { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, + { "name": "camera_id", "in": "query", "schema": { "type": "integer" } }, + { "name": "task_type", "in": "query", "schema": { "type": "string" } }, + { "name": "active", "in": "query", "schema": { "type": "boolean" } } + ], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AITaskList" } } } } } + }, + "post": { + "tags": ["ai-tasks"], "summary": "Create AI task", + "description": "Replaces (create half of): `POST /AI-Task`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AITaskCreate" } } } }, + "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AITask" } } } } } + } + }, + "/ai-tasks/{id}": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["ai-tasks"], "summary": "Get AI task", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AITask" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, + "put": { "tags": ["ai-tasks"], "summary": "Replace AI task", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AITaskCreate" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AITask" } } } } } }, + "patch": { "tags": ["ai-tasks"], "summary": "Partially update AI task", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AITaskCreate" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AITask" } } } } } }, + "delete": { "tags": ["ai-tasks"], "summary": "Delete AI task", + "description": "Replaces: `DELETE /AI-Task?{id}` and `POST /delete/AI-Task?{id}`.", + "responses": { "204": { "$ref": "#/components/responses/NoContent" } } } + }, + "/ai-tasks/{id}/status": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["ai-tasks"], "summary": "Get task status", + "description": "Replaces: `GET /GetAITaskStatus` (single-task case).", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AITaskStatus" } } } } } } + }, + "/ai-tasks/{id}/start": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "post": { "tags": ["ai-tasks"], "summary": "Start task", + "description": "Replaces: `GET /ControlAITask?ID={id}&State=true`.", + "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AITaskStatus" } } } } } } + }, + "/ai-tasks/{id}/stop": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "post": { "tags": ["ai-tasks"], "summary": "Stop task", + "description": "Replaces: `GET /ControlAITask?ID={id}&State=false`.", + "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AITaskStatus" } } } } } } + }, + "/ai-tasks/{id}/liveview": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["ai-tasks"], "summary": "Get a liveview descriptor for the annotated stream", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveviewDescriptor" } } } } } } + }, + "/ai-tasks/catalog": { + "get": { "tags": ["ai-tasks"], "summary": "List supported AI task types", + "description": "Replaces: `GET /GetSupportedAiTasks`.", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AITaskType" } } } } } } } + }, + + "/events": { + "get": { + "tags": ["events"], "summary": "List events", + "description": "Replaces: `POST /event/Get` (with body filter). All filters are now query params and the method is idempotent GET.", + "parameters": [ + { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, + { "name": "task_id", "in": "query", "schema": { "type": "integer" } }, + { "name": "camera_id", "in": "query", "schema": { "type": "integer" } }, + { "name": "task_type", "in": "query", "schema": { "type": "string" } }, + { "name": "object", "in": "query", "schema": { "type": "string" } }, + { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, + { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, + { "name": "include_images", "in": "query", "schema": { "type": "boolean", "default": false } }, + { "name": "image_width", "in": "query", "schema": { "type": "integer" } } + ], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } } } + } + }, + "/events/summary": { + "get": { + "tags": ["events"], "summary": "Event rollup / analytics", + "description": "Replaces: `POST /event/GetSummary`.", + "parameters": [ + { "name": "task_id", "in": "query", "schema": { "type": "integer" } }, + { "name": "camera_id", "in": "query", "schema": { "type": "integer" } }, + { "name": "task_type", "in": "query", "schema": { "type": "string" } }, + { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, + { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, + { "name": "days", "in": "query", "schema": { "type": "integer", "description": "Convenience: last N days" } }, + { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": ["objects","hour","day","rule"] } }, + { "name": "interval", "in": "query", "schema": { "type": "string", "enum": ["minutes","hours","days"], "default": "hours" } } + ], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventSummary" } } } } } + } + }, + "/events/stream": { + "get": { + "tags": ["events"], "summary": "Live event tail (Server-Sent Events)", + "description": "New endpoint. Returns `text/event-stream`. Each event is a JSON `EventRecord`. Pass filter query params to scope the stream.", + "parameters": [ + { "name": "task_id", "in": "query", "schema": { "type": "integer" } }, + { "name": "camera_id", "in": "query", "schema": { "type": "integer" } } + ], + "responses": { "200": { "description": "Stream", "content": { "text/event-stream": { "schema": { "type": "string" } } } } } + } + }, + "/events/{id}": { + "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], + "get": { "tags": ["events"], "summary": "Get a single event", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventRecord" } } } } } } + }, + "/events/{id}/image": { + "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], + "get": { "tags": ["events"], "summary": "Get the evidence image", + "description": "Replaces: `GET /event/GetImage?ID={id}&ImageWidth=…`.", + "parameters": [{ "name": "width", "in": "query", "schema": { "type": "integer" } }], + "responses": { "200": { "description": "Image bytes", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } } } } + }, + "/events/{id}/clip": { + "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], + "get": { "tags": ["events"], "summary": "Get a presigned URL for the evidence video clip", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } } } } } } + }, + + "/fr/persons": { + "get": { "tags": ["fr"], "summary": "List FR persons", + "description": "Replaces: `GET /FR/User`. Renamed `User` to `Person` to disambiguate from system users.", + "parameters": [{ "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRPersonList" } } } } } }, + "post":{ "tags": ["fr"], "summary": "Create FR person", + "description": "Replaces (create half of): `POST /FR/User`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRPersonCreate" } } } }, + "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRPerson" } } } } } } + }, + "/fr/persons/{id}": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["fr"], "summary": "Get FR person", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRPerson" } } } } } }, + "patch": { "tags": ["fr"], "summary": "Update FR person", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRPersonCreate" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRPerson" } } } } } }, + "delete":{ "tags": ["fr"], "summary": "Delete FR person", + "description": "Replaces: `POST /FR/DeleteUser?{id}`.", + "responses": { "204": { "$ref": "#/components/responses/NoContent" } } } + }, + "/fr/persons/{id}/faces": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["fr"], "summary": "List faces for a person", + "description": "Replaces: `GET /FR/GetFaces` (filtered by person).", + "parameters": [{ "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRFaceList" } } } } } }, + "post":{ "tags": ["fr"], "summary": "Add a face to a person (multipart upload, no base64)", + "description": "Replaces: `POST /FR/AddFace` (which used base64 inside JSON). Now uses `multipart/form-data`.", + "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { + "type": "object", "required": ["image"], "properties": { "image": { "type": "string", "format": "binary" }, "quality_min": { "type": "number" } } + } } } }, + "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRFace" } } } } } } + }, + "/fr/faces/{face_id}": { + "parameters": [{ "name": "face_id", "in": "path", "required": true, "schema": { "type": "integer" } }], + "delete": { "tags": ["fr"], "summary": "Delete a face", + "description": "Replaces: `POST /FR/DeleteFace`.", + "responses": { "204": { "$ref": "#/components/responses/NoContent" } } } + }, + "/fr/person-groups": { + "get": { "tags": ["fr"], "summary": "List FR person groups", + "description": "Replaces: `GET /FR/UserGroup`.", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FRPersonGroup" } } } } } } }, + "post":{ "tags": ["fr"], "summary": "Create person group", + "description": "Replaces (create half of): `POST /FR/UserGroup`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRPersonGroup" } } } }, + "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRPersonGroup" } } } } } } + }, + "/fr/person-groups/{id}": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "patch": { "tags": ["fr"], "summary": "Update person group", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRPersonGroup" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRPersonGroup" } } } } } }, + "delete": { "tags": ["fr"], "summary": "Delete person group", + "description": "Replaces: `POST /FR/DeleteUserGroup?{id}`.", + "responses": { "204": { "$ref": "#/components/responses/NoContent" } } } + }, + "/fr/config": { + "get": { "tags": ["fr"], "summary": "Get FR detection configuration", + "description": "Replaces: `GET /FR/FaceDetectionConfiguration`.", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRConfig" } } } } } }, + "patch": { "tags": ["fr"], "summary": "Update FR detection configuration", + "description": "Replaces: `POST /FR/FaceDetectionConfiguration`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRConfig" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRConfig" } } } } } } + }, + + "/fr/recording-tasks": { + "get": { "tags": ["fr-recording"], "summary": "List face-recording tasks", + "description": "Replaces: `GET /facerecording/ListTasks`.", + "parameters": [{ "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FRRecordingTask" } } } } } } }, + "post": { "tags": ["fr-recording"], "summary": "Create face-recording task", + "description": "Replaces: `POST /facerecording/CreateTask`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRRecordingTaskCreate" } } } }, + "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRRecordingTask" } } } } } } + }, + "/fr/recording-tasks/{id}": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "delete": { "tags": ["fr-recording"], "summary": "Delete face-recording task", + "description": "Replaces: `GET /facerecording/DeleteTask?{id}`.", + "responses": { "204": { "$ref": "#/components/responses/NoContent" } } } + }, + "/fr/recording-tasks/{id}/start": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "post": { "tags": ["fr-recording"], "summary": "Start task", + "description": "Replaces: `GET /facerecording/StartTask`.", + "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRRecordingTask" } } } } } } + }, + "/fr/recording-tasks/{id}/stop": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "post": { "tags": ["fr-recording"], "summary": "Stop task", + "description": "Replaces: `GET /facerecording/StopTask`.", + "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRRecordingTask" } } } } } } + }, + "/fr/recording-tasks/{id}/faces": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "get": { "tags": ["fr-recording"], "summary": "Read recorded faces", + "description": "Replaces: `POST /facerecording/ReadFaces`.", + "parameters": [ + { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, + { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }, + { "name": "image_size", "in": "query", "schema": { "type": "integer", "default": 50 } } + ], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FRRecordingFace" } } } } } } }, + "patch": { "tags": ["fr-recording"], "summary": "Assign recorded faces to a person (bulk)", + "description": "Replaces: `POST /facerecording/UpdateFace`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FRRecordingFaceAssign" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FRRecordingFace" } } } } } } } + }, + + "/alpr/plates": { + "get": { "tags": ["alpr"], "summary": "List registered plates", + "description": "Replaces: `GET /ALPR/GetRegisteredLicensePlates`.", + "parameters": [{ "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "name": "group", "in": "query", "schema": { "type": "string" } }], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ALPRPlateList" } } } } } }, + "post":{ "tags": ["alpr"], "summary": "Register plates (bulk)", + "description": "Replaces: `POST /ALPR/RegisterLicensePlate`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ALPRPlateRegisterRequest" } } } }, + "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ALPRPlate" } } } } } } } + }, + "/alpr/plates/{plate}": { + "parameters": [{ "name": "plate", "in": "path", "required": true, "schema": { "type": "string" } }], + "delete": { "tags": ["alpr"], "summary": "Deregister a single plate", + "description": "Replaces (single case of): `POST /ALPR/DeregisterLicensePlate`.", + "responses": { "204": { "$ref": "#/components/responses/NoContent" } } } + }, + "/alpr/plates:bulk-delete": { + "post": { "tags": ["alpr"], "summary": "Deregister plates (bulk)", + "description": "Replaces: `POST /ALPR/DeregisterLicensePlate` (bulk body).", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, + "responses": { "204": { "$ref": "#/components/responses/NoContent" } } } + }, + "/alpr/plate-groups": { + "get": { "tags": ["alpr"], "summary": "List plate groups", + "description": "Replaces: `GET /ALPR/GetLicensePlateGroups`.", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ALPRPlateGroup" } } } } } } }, + "post": { "tags": ["alpr"], "summary": "Create plate group", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ALPRPlateGroup" } } } }, + "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ALPRPlateGroup" } } } } } } + }, + "/alpr/plate-groups/{id}": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "patch": { "tags": ["alpr"], "summary": "Update plate group", + "description": "Replaces: `POST /ALPR/EditLicensePlateGroup`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ALPRPlateGroup" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ALPRPlateGroup" } } } } } }, + "delete": { "tags": ["alpr"], "summary": "Delete plate group", + "description": "Replaces: `POST /ALPR/DeleteLicensePlateGroup`.", + "responses": { "204": { "$ref": "#/components/responses/NoContent" } } } + }, + + "/notifications/recipients": { + "get": { "tags": ["notifications"], "summary": "List recipients", + "description": "Replaces: `GET /notification/Recipient`.", + "parameters": [{ "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationRecipientList" } } } } } }, + "post": { "tags": ["notifications"], "summary": "Create recipient", + "description": "Replaces (create half of): `POST /notification/Recipient`.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationRecipientCreate" } } } }, + "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationRecipient" } } } } } } + }, + "/notifications/recipients/{id}": { + "parameters": [{ "$ref": "#/components/parameters/PathId" }], + "patch": { "tags": ["notifications"], "summary": "Update recipient", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationRecipientCreate" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationRecipient" } } } } } }, + "delete": { "tags": ["notifications"], "summary": "Delete recipient", + "description": "Replaces: `POST /notification/DeleteRecipient?{id}`.", + "responses": { "204": { "$ref": "#/components/responses/NoContent" } } } + }, + "/notifications/recipient-groups": { + "get": { "tags": ["notifications"], "summary": "List recipient groups", + "description": "Replaces: `GET /notification/RecipientGroups`.", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" } } } } } } } } } + }, + + "/triggers/types": { + "get": { "tags": ["triggers"], "summary": "List supported trigger types and their config schemas", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "config_schema": { "type": "object", "additionalProperties": true } } } } } } } } } + }, + "/triggers/test": { + "post": { "tags": ["triggers"], "summary": "Dispatch a test trigger", + "description": "Replaces: `POST /Trigger`. Useful for validating a trigger configuration without firing a real AI event.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerTestRequest" } } } }, + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerTestResponse" } } } } } } + }, + + "/system/status": { + "get": { "tags": ["system"], "summary": "Quick liveness probe", + "description": "Replaces: `GET /ViewStatus`, `GET /GetStatus`.", + "security": [], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemStatus" } } } } } } + }, + "/system/health": { + "get": { "tags": ["system"], "summary": "Server health snapshot (resources, counts)", + "description": "Replaces: `GET /GetServerHealth`, `GET /GetServerHealthAndLogs`.", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemHealth" } } } } } } + }, + "/system/info": { + "get": { "tags": ["system"], "summary": "Server / host info", + "description": "Replaces: `GET /GetServerInfo`.", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemInfo" } } } } } } + }, + "/system/logs": { + "get": { "tags": ["system"], "summary": "Paginated server logs", + "description": "Replaces: `GET /GetServerLog`.", + "parameters": [ + { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, + { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, + { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, + { "name": "level", "in": "query", "schema": { "type": "string", "enum": ["debug","info","warn","error","fatal"] } } + ], + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemLogList" } } } } } } + }, + "/system/version": { + "get": { "tags": ["system"], "summary": "Server version", + "description": "Replaces: `GET /SW/GetSoftwareVersion`.", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemVersion" } } } } } } + }, + "/system/update": { + "get": { "tags": ["system"], "summary": "Get update status", + "description": "Replaces: `GET /SW/GetSoftwareUpdateStatus`.", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemUpdateStatus" } } } } } }, + "post": { "tags": ["system"], "summary": "Trigger a software update", + "description": "Replaces: `POST /SW/UpdateSoftwareVersion`.", + "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobAck" } } } } } } + }, + + "/jobs/{id}": { + "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], + "get": { "tags": ["jobs"], "summary": "Get an async job's status / result", + "description": "Used to poll scans, model uploads, deploys, and updates.", + "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } + }, + + "/composite/camera-with-tasks": { + "post": { "tags": ["composite"], "summary": "Create a camera and one or more deployment groups in one call", + "description": "Replaces: `POST /CreateCameraAndTasks`. Convenience endpoint — primary CRUD on `/cameras` and `/deployment-groups` should still be preferred.", + "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CameraWithTasksRequest" } } } }, + "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CameraWithTasksResponse" } } } } } } + } + } +} diff --git a/docs/ANSCORE-system-architecture.md b/docs/ANSCORE-system-architecture.md new file mode 100644 index 0000000..1dc2a16 --- /dev/null +++ b/docs/ANSCORE-system-architecture.md @@ -0,0 +1,699 @@ +--- +title: "ANSCORE — System Architecture (L2 + L3)" +subtitle: "Developer reference for the ANSVIS Communication Layer (CL) backend and the Qt/QML cross-platform desktop UI" +author: "ANSCENTER" +date: "2026-05-26" +--- + +# Executive summary + +ANSCORE is a Vision-AI Video Management System split into three layers: + +- **Layer 1 — Edge runtime** (per target). Owns cameras, AI inference, trackers, rules, triggers. Built into the existing `ANSCORE/modules/*` C++ tree (ANSCV, ANSODEngine, ANSFR, ANSLPR, ANSOCR, ANSMOT). For this document L1 is *abstract*: we describe only the interface it exposes upward to L2. +- **Layer 2 — ANSVIS CL** (one per customer). Aggregates targets, persists configuration, ingests events, brokers live media. Exposes a single REST contract (`/api/v1`) to L3. In v1 it is built as an **adapter layer in front of the existing ANSVIS server** — no rewrite required. +- **Layer 3 — Qt/QML desktop UI** (Win / macOS / Linux). The operator-facing application. Talks to L2 exclusively. + +**Build assignment:** + +- L1 and L2 are built by the **core team** under architect-level review. +- L3 is built by a **6-engineer team**. +- L2 ↔ L3 is **REST + SSE + (HLS / RTSP / WebRTC)** — defined by `contracts/openapi.v1.json` (67 paths, 102 operations, 91 schemas). + +The contract is the only artifact both sides block on. Once published, UI engineers develop against a Prism mock; the backend **core team** implements adapters per resource in parallel. Integration is the joining point. + +\newpage + +# Part I — System overview + +## The three layers + +![System context](diagrams/png/01-system-context.png){ width=100% } + +L3 only ever talks to L2. L2 brokers everything else: configuration push down to edges, event upload from edges, media relay. This keeps the UI team fully decoupled from L1 velocity. + +## Three transports between L3 and L2 + +| # | Transport | Purpose | Carries | +|---|---|---|---| +| 1 | REST over HTTPS | Control plane: all CRUD, configuration, deploy commands | JSON request/response, RFC 7807 errors | +| 2 | Server-Sent Events (SSE) over HTTPS | Live event tail (push of detections, target status) | `text/event-stream`, JSON per event | +| 3 | HLS / RTSP / WebRTC | Live video | Media segments; transport chosen per stream | + +The REST API brokers the other two: the UI calls REST to obtain a stream descriptor or SSE endpoint URL. + +## Why this split + +The earlier proposal of using gRPC end-to-end was reversed because the existing ANSVIS server already exposes a REST API. Pragmatic v1: **reuse what exists**, adapt it into a standards-compliant `/api/v1` surface, ship faster. gRPC remains an option for a future v2 if needed. + +## Build ownership at a glance + +| Layer | Pace | +|---|---| +| L1 (edge runtime) | Slower — high complexity (frame bus, inference batching, plugin SDK) | +| L2 (CL) | Faster — modular per-resource adapters | +| L3 (Qt/QML UI) | Independent — mock-first development | + +\newpage + +# Part II — Layer 1 (abstract overview) + +L1 is the **edge runtime** that runs on each target. From L2's perspective it is a black box that: + +- Receives **configuration** (cameras, AI models, AI tasks, rules, triggers) from L2 and persists it locally. +- Captures frames from cameras (RTSP / RTMP / SRT / ONVIF / simulated). +- Runs **AI pipelines** (object detection, FR, LPR, OCR, MOT, custom plugins). +- Evaluates **rules** and emits **events** with evidence (snapshot frame, optional clip). +- Dispatches **triggers** (HTTP, MQTT, email, push, broker integrations). +- Exposes **liveview** streams (RTSP / SRT / future WebRTC). +- Reports **health / metrics / logs** upward. + +L1 ↔ L2 protocol is out of scope for this document. For v1, L2's adapter calls into the legacy ANSVIS server's existing protocol with edges (this is what currently works in production). + +For L2 and L3 developers, L1 is treated as a remote service: + +- Configuration changes go: **L3 (UI) → L2 (REST) → L1 (legacy protocol) → target reconciles**. +- Events flow: **target → L1 → L2 (legacy uplink) → L2 event store → L2 SSE → L3**. +- Liveview: **L3 asks L2 for a stream descriptor → L2 media relay pulls from L1 → L3 plays from L2's relay URL**. + +The detailed L1 architecture (camera pool, inference server, frame bus, plugin SDK, etc.) is documented separately and does not affect L2 / L3 work. + +\newpage + +# Part III — Layer 2 (ANSVIS CL) + +## Architecture + +![Layer 2 internals](diagrams/png/02-l2-internals.png){ width=100% } + +L2 is composed of four logical groups: + +1. **`/api/v1` surface** — REST router, auth middleware, OpenAPI request validation, RFC 7807 error mapper, rate limiter, SSE broadcaster. +2. **v1 adapter layer** — one module per resource (cameras, models, edges, deployment-groups, ai-tasks, events, fr, alpr, notifications, system, jobs). Each adapter translates v1 requests to one or more legacy ANSVIS calls. +3. **Legacy ANSVIS core** — reused as-is. Hosts the existing config store, AI task engine, FR engine, ALPR engine. The adapter is the only layer that calls into it. +4. **Infrastructure** — auth + token store, async job queue, event metadata DB, clip / image object store (S3 / MinIO / FS), logs + metrics, media relay. + +## Ownership inside L2 + +![L2 build ownership](diagrams/png/03-l2-ownership.png){ width=100% } + +- **Architect (human)** keeps direct review on the cross-cutting concerns: REST router, auth, validation pipeline, RFC 7807 errors, RBAC, L2 ↔ L1 tunnel security. +- The **core team** builds the per-resource adapters and infrastructure helpers (job queue, media relay). Each module has a sharp boundary so the team can work in parallel without colliding. +- **Existing ANSVIS** is reused as-is. The adapter is the only entry point. + +## REST API surface — `/api/v1` + +The full contract is `contracts/openapi.v1.json` (OpenAPI 3.1, 67 paths, 102 operations, 91 typed schemas). Summary by resource group: + +| Tag | Operations | Purpose | +|---|---:|---| +| `auth` | 3 | Login, logout, refresh | +| `users` | 5 | System users CRUD | +| `cameras` | 10 | CRUD + snapshot + liveview + ONVIF scan + probe | +| `models` | 7 | CRUD + multipart upload + initiate/complete large upload | +| `edges` | 7 | CRUD + health + status | +| `deployment-groups` | 8 | CRUD + status + start/stop | +| `ai-tasks` | 11 | CRUD + status + start/stop + liveview + catalog | +| `events` | 6 | List + summary + SSE stream + image + clip + single | +| `fr` | 14 | Persons + faces + groups + detection config | +| `fr-recording` | 7 | Face-recording tasks + read/assign | +| `alpr` | 8 | Plate + plate-group CRUD | +| `notifications` | 5 | Recipients + groups | +| `triggers` | 2 | Type catalog + test dispatch | +| `system` | 7 | Status, health, info, logs, version, update | +| `jobs` | 1 | Async job polling | +| `composite` | 1 | Convenience endpoint (camera + tasks in one call) | +| **Total** | **102** | | + +## Conventions enforced by `openapi.v1.json` + +- Plural kebab-case resource paths (`/cameras`, `/ai-tasks`, `/deployment-groups`). +- `snake_case` field names. Units in the field name (`time_interval_seconds`, not `time_interval` with `(s)` suffix). +- IDs in the path, never as query-string keys (replaces legacy `?867560018`). +- `GET / POST / PUT / PATCH / DELETE` used semantically. +- State changes via `POST /resource/{id}/start` and `POST /resource/{id}/stop` (pragmatic exception). +- All errors as RFC 7807 problem+json with the matching HTTP status code. +- List responses use a uniform pagination wrapper: `{items, page, page_size, total, next_cursor}`. +- Auth: `Authorization: Bearer ` header, never in URL. +- File uploads up to 10 MB use `multipart/form-data`; larger uploads use the initiate / complete pattern with a presigned PUT URL. +- Live events as SSE; live media via HLS / RTSP / WebRTC behind a descriptor RPC. +- All previously stringified-JSON fields (`Parameters(json)`, `RuleConfig`, `TriggerConfig`, `ModelConfigJson`) are now fully typed nested objects, validated against the schema. + +## Migration from legacy ANSVIS endpoints + +Every v1 endpoint description in the OpenAPI spec ends with `Replaces:` listing the legacy ANSVIS path(s) it supersedes. Examples: + +| Legacy | v1 | +|---|---| +| `GET /Camera` (list mode) | `GET /api/v1/cameras` | +| `GET /Camera?{id}` | `GET /api/v1/cameras/{id}` | +| `DELETE /Camera?{id}` + `POST /delete/Camera?{id}` | `DELETE /api/v1/cameras/{id}` | +| `GET /ControlAITask?ID=&State=true` | `POST /api/v1/ai-tasks/{id}/start` | +| `POST /event/Get` (filter in body) | `GET /api/v1/events?task_id=&from=&to=&...` | +| `POST /FR/AddFace` (base64 in JSON) | `POST /api/v1/fr/persons/{id}/faces` (multipart) | +| `GET /SW/GetSoftwareVersion`, etc. | `GET /api/v1/system/version`, `/health`, `/info`, `/logs`, `/update` | + +Legacy endpoints remain available during one release cycle with `Deprecation:` + `Sunset:` headers (RFC 8594). + +\newpage + +# Part IV — Layer 3 (Qt / QML desktop UI) + +## Architecture + +![Layer 3 internals](diagrams/png/04-l3-internals.png){ width=100% } + +L3 is organized in four layers inside the Qt app: + +1. **App Shell** — main window, navigation router, design system / theme, i18n, auth state + token store, global error toast / dialog. +2. **Network layer** — generated REST client (from `openapi.v1.json`), SSE subscriber (chunked `QNetworkReply`), media client (QtMultimedia or GStreamer), bbox overlay renderer (custom `QQuickItem` with `QSGGeometryNode`), multipart + presigned uploader. +3. **Domain state** — `QObject` + `Q_PROPERTY` + signals models per resource (CamerasModel, ModelsModel, EdgesModel, DeploymentGroupsModel, AITasksModel, EventsModel + LiveBuffer, FRPersonsModel, ALPRPlatesModel, RecipientsModel, SystemHealthModel). +4. **Screens (QML)** — the operator surface: Login, Dashboard, Camera management, Pipeline editor, AI task config, Rules / triggers, Liveview grid, Eventview timeline, FR persons + faces, ALPR plates, Model registry, Users / admin, Settings. + +## Screen → endpoint map + +| Screen | Reads | Mutates | Notes | +|---|---|---|---| +| Login | — | `POST /auth/login` | Stores token in `AuthState` | +| Dashboard | `GET /edges`, `GET /edges/{id}/health`, `GET /system/health` | — | Auto-refresh every 5 s | +| Camera management | `GET /cameras`, `GET /cameras/{id}/snapshot`, `POST /cameras/probe` | `POST/PATCH/DELETE /cameras`, `POST /cameras/scan` (async job) | ONVIF discovery + calibration | +| Pipeline editor | `GET /deployment-groups/{id}`, `GET /ai-tasks/catalog`, `GET /models` | `PUT /deployment-groups/{id}` | Highest-risk feature; QGraphicsView | +| AI task config | `GET /ai-tasks/{id}`, `GET /ai-tasks/catalog` | `POST/PATCH/DELETE /ai-tasks`, `POST /ai-tasks/{id}/{start,stop}` | Schema-driven forms | +| Rules / triggers | `GET /triggers/types` | Embedded in DG / task body | `POST /triggers/test` | +| Liveview | `GET /cameras/{id}/liveview` | — | HLS v1, WebRTC v2; overlay sync to PTS | +| Eventview | `GET /events?...`, `GET /events/stream` (SSE), `/events/{id}/{image,clip}` | — | Virtualized list for 100k+ events | +| FR persons + faces | `GET /fr/persons`, `GET /fr/persons/{id}/faces` | `POST/PATCH/DELETE /fr/persons`, `POST /fr/persons/{id}/faces` (multipart) | Image upload | +| ALPR plates | `GET /alpr/plates`, `GET /alpr/plate-groups` | `POST/DELETE /alpr/plates`, `PATCH /alpr/plate-groups/{id}` | Bulk register / deregister | +| Model registry | `GET /models` | `POST /models` (multipart) or initiate / complete pattern for >100 MB | Upload progress | +| Users / admin | `GET /users` | `POST/PATCH/DELETE /users/{id}` | Admin role only | +| Settings | `GET /system/info`, `GET /system/version`, `GET /system/update` | `POST /system/update` | | + +## Engineer ownership + +![L3 engineer ownership](diagrams/png/11-l3-engineer-ownership.png){ width=100% } + +\ + +Six engineers, each owning a vertical slice: + +| # | Role | Owns | +|---|---|---| +| **E1** | UI Lead / Shell Architect | Qt 6 + CMake monorepo, generated REST client, auth state, design system, navigation router, packaging (Win/Mac/Linux signing, notarize, auto-update), CI matrix | +| **E2** | Pipeline Editor Specialist | Visual DAG editor (`QGraphicsView` in `QQuickWidget`), node library, connection validation, schema-driven param panels, undo / redo, save / version | +| **E3** | Liveview / Media | QtMultimedia HLS player (v1), multi-stream grid, bbox overlay (`QQuickItem` + `QSGGeometryNode`), clip player, WebRTC via GStreamer (v2) | +| **E4** | Config Forms | Schema-driven QML forms from `openapi.v1.json`, camera + ONVIF discovery flow, camera calibration UI (ROI / zones / homography), model + plugin + trigger forms | +| **E5** | Dashboard / Eventview | Target dashboard cards + charts, virtualized event timeline, SSE subscriber + LiveBuffer, filter / search / evidence viewer, multi-target monitoring | +| **E6** | UX / Cross-platform QA | Design polish, accessibility, i18n, install / upgrade testing on Win / Mac / Linux, crash reporting, QML Profiler perf passes, user docs surface | + +**Critical-path order for week 1–2:** E1 alone delivers the shell that unblocks E2–E6. E2 runs a node-editor spike in parallel to de-risk the hardest feature early. Once E1's shell lands, E3 / E4 / E5 work in parallel against the mock CL; E6 starts cross-platform validation. + +\newpage + +# Part V — L2 ↔ L3 communication + +## 1. REST control plane + +Every CRUD operation, every state change, every configuration push. JSON in, JSON out, RFC 7807 problem+json on error. + +### Request envelope + +```http +GET /api/v1/cameras?page=1&page_size=50 HTTP/1.1 +Host: cms.example.com +Authorization: Bearer eyJhbGc… +Accept: application/json +``` + +### Success list response + +```json +{ + "items": [ + { "id": 123, "name": "Front gate", "driver": "rtsp", "active": true, ... } + ], + "page": 1, + "page_size": 50, + "total": 247, + "next_cursor": null +} +``` + +### Error response + +```json +{ + "type": "https://anscenter.com/errors/validation", + "title": "Validation failed", + "status": 422, + "detail": "One or more fields are invalid", + "instance": "/api/v1/cameras", + "errors": [ + { "field": "address", "message": "Must be a valid RTSP URL" }, + { "field": "capturing.time_interval_seconds", "message": "Must be > 0" } + ] +} +``` + +### Camera create — body example (clean v1) + +```json +{ + "name": "Front gate", + "driver": "rtsp", + "address": "rtsp://192.168.1.87:554/h264Preview_01_main", + "credentials": { "username": "root", "password": "admin123" }, + "capturing": { "mode": "timer", "time_interval_seconds": 0.1 }, + "active": true, + "logging_enabled": false, + "edge_id": null, + "deployment_group_ids": [] +} +``` + +Note: no more stringified `Parameters(json)`. No more keys with parentheses or apostrophes. Credentials are nested. Units are in the field name. + +## 2. SSE event stream + +For live event tail: + +```http +GET /api/v1/events/stream?task_id=456 HTTP/1.1 +Host: cms.example.com +Authorization: Bearer eyJhbGc… +Accept: text/event-stream +``` + +Each event: + +``` +event: detection +data: {"id":"20260526_181023-3","task_id":456,"camera_id":123, + "timestamp":"2026-05-26T18:10:23Z","object":"car","score":0.91, + "bbox":{"x":340,"y":210,"w":120,"h":80}} +``` + +Qt side: `QNetworkAccessManager` with chunked reads, parse newline-delimited frames, drive `EventsModel.LiveBuffer`. + +## 3. Live media + +`GET /api/v1/cameras/{id}/liveview?transport=hls` returns a stream descriptor: + +```json +{ + "url": "https://cms.example.com/relay/cam123.m3u8", + "transport": "hls", + "auth_token": "tkn_short_lived_…", + "expires_at": "2026-05-26T18:15:00Z", + "overlay_stream": "/api/v1/events/stream?task_id=456" +} +``` + +Qt side: hand the URL to QtMultimedia for HLS playback (v1). For sub-second latency in v2, switch transport to `webrtc` and use GStreamer `webrtcbin`. + +\newpage + +# Part VI — Key sequence flows + +## 6.1 Operator configures a camera + AI task and deploys + +![Configure & deploy sequence](diagrams/png/05-seq-configure-deploy.png){ width=92% } + +Walk-through: + +1. UI lists cameras via `GET /cameras?page=1`. +2. Operator submits the new-camera form. UI sends `POST /cameras` with the *clean* body (nested credentials, capturing, image_size — no stringified JSON). +3. UI creates an AI task for the new camera via `POST /ai-tasks`. +4. Operator clicks "Start". UI calls `POST /ai-tasks/{id}/start` — returns `202 Accepted` with `{state: starting}`. +5. UI polls `GET /ai-tasks/{id}/status` until `state=running`. (Will be replaced by SSE in a later iteration so polling is optional.) + +## 6.2 Live event tail with evidence + +![Live event tail sequence](diagrams/png/06-seq-live-events.png){ width=92% } + +Walk-through: + +1. UI fetches historical events via `GET /events?task_id=&page=1` and renders the timeline. +2. UI opens an SSE stream `GET /events/stream?task_id=` for live tail. +3. Edge produces an event → L2 ingests → SSE broadcaster pushes the `EventRecord` to all subscribed UIs (filtered by their query). +4. Operator clicks an event. UI fetches `GET /events/{id}/image?width=640` for the snapshot. +5. Operator plays the clip. UI fetches `GET /events/{id}/clip` to get a presigned URL, then GETs the MP4 directly from the object store. The CL process never touches the video bytes — they flow client ↔ S3/MinIO. + +## 6.3 Liveview with bbox overlay + +![Liveview sequence](diagrams/png/07-seq-liveview.png){ width=92% } + +Walk-through: + +1. UI requests a liveview descriptor for camera 123: `GET /cameras/123/liveview?transport=hls`. +2. L2's media relay ensures an HLS endpoint is running for that camera (pulling RTSP from the edge in the background). +3. L2 returns `{url, transport:hls, auth_token, expires_at}`. +4. UI plays the HLS URL in QtMultimedia. +5. Simultaneously the UI subscribes to `/events/stream?task_id=456` (SSE) for the AI task's detections. +6. The Qt overlay layer (custom `QQuickItem`) renders bounding boxes synced to the video PTS. + +For v2 with WebRTC, the descriptor returns `transport:webrtc` and a signaling URL; GStreamer's `webrtcbin` handles negotiation. + +## 6.4 Async camera scan via job queue + +![Async scan sequence](diagrams/png/08-seq-async-scan.png){ width=92% } + +Walk-through: + +1. Operator triggers an ONVIF scan of a subnet. UI calls `POST /cameras/scan` with `{ip_range, credentials, timeout_seconds}`. +2. L2 enqueues the work and immediately returns `202 Accepted` with `{job_id, status:queued, links:{self:"/jobs/j1"}}`. +3. The job worker performs the scan asynchronously. +4. UI polls `GET /jobs/{id}` until `status` becomes `succeeded` or `failed`. The terminal response includes `result` with the discovered cameras. + +This pattern is used for every potentially-long operation: ONVIF scan, large model upload, deploy-to-many-targets, software update. + +## 6.5 Large model upload (presigned URL) + +![Large model upload sequence](diagrams/png/09-seq-large-upload.png){ width=92% } + +Walk-through: + +1. UI calls `POST /models:initiate-upload` with `{filename, size_bytes, checksum}`. L2 returns `{upload_id, presigned_url, expires_at}`. +2. UI PUTs the bytes directly to the object store using the presigned URL. The CL process never sees the bytes — saves CPU and avoids HTTP-body-size limits. +3. UI calls `POST /models:complete-upload` with `{upload_id, metadata}`. L2 verifies the checksum and registers the model. + +For files under 10 MB, the simple `POST /models` multipart endpoint can be used instead. + +\newpage + +# Part VII — Deployment topology + +![Deployment topology](diagrams/png/10-deployment-topology.png){ width=100% } + +## Hosts + +| Host | Runs | Notes | +|---|---|---| +| Operator workstation (Win / Mac / Linux) | Qt UI application | One per concurrent operator | +| ANSVIS server host | Reverse proxy (nginx / caddy) + ANSVIS app (adapter + legacy core) + Media relay + Object store + Config / Event DBs | One per customer site (can be HA later) | +| Edge target | L1 runtime | One per physical capture site | + +## Customer network rules + +| Direction | Port | Purpose | +|---|---|---| +| Workstation → ANSVIS server | TCP 443 | REST + SSE + HLS over TLS | +| ANSVIS server → workstation | — (response only) | | +| ANSVIS server ↔ edges | TBD per deployment | Existing ANSVIS protocol | +| Workstation → edges | **None** | Workstations never reach edges directly. Media relay proxies. | + +## Why workstations don't reach edges + +- Edges typically sit behind customer firewalls / NAT. +- One TLS endpoint (ANSVIS) is easier to firewall, monitor, and authenticate against than dozens of edges. +- Token rotation happens centrally. +- The media relay can transcode, cache, or split streams. + +\newpage + +# Part VIII — Delivery plan + +## Mock-first development + +The contract `openapi.v1.json` is the only artifact both teams block on. Once it is published: + +- **UI team** runs Stoplight Prism (`prism mock contracts/openapi.v1.json`) as a local mock CL and develops against it from day 1. No need to wait for the real adapter. +- The **backend core team** implements the adapter resource-by-resource in parallel, validating each endpoint against the same OpenAPI schema. +- **Integration** is the joining point. UI tests run against both mock and real to detect drift. + +## Critical path + +![Dependency chain](diagrams/png/12-dependency-chain.png){ width=100% } + +## Sequencing + +| Phase | Week | Activities | +|---|---|---| +| **Contract freeze** | 1 | Lock `openapi.v1.json` v1.0.0 (3 small decisions outstanding — see Part IX) | +| **Foundations** | 1–2 | E1: Qt 6 + CMake monorepo, generated REST client, Prism mock wired up, design system stub, app shell.
E2: node-editor spike (de-risk).
Core team: cameras / models / edges / system adapters in parallel. | +| **Vertical slices** | 3–6 | E3 (Liveview), E4 (Config forms), E5 (Dashboard / Eventview) build full features against the mock.
Core team: ai-tasks / deployment-groups / events / fr / alpr / notifications adapters. | +| **Real integration** | 7–8 | UI cuts over from mock to real `/api/v1` per screen as adapters land. E6 runs cross-platform install / upgrade testing on Win / Mac / Linux. | +| **Hardening** | 9–10 | Performance passes (QML Profiler, REST tracing), security review (architect-led), crash reporting, packaging signing / notarization. | +| **Ship v1** | 11–12 | Pilot deployment, customer training, feedback loop. | + +\newpage + +# Part IX — Open decisions + +These need to be locked before contract v1.0.0 publishes. + +| # | Decision | Default in spec | Notes | +|---|---|---|---| +| 1 | Field naming | `snake_case` | Could switch to `camelCase` — match Qt/C++ style. One find-replace pass on `openapi.v1.json` either way. | +| 2 | Auth scheme | Bearer (existing ANSVIS token) | v1 keeps Bearer; OAuth2/OIDC for v2. | +| 3 | Mock server tool | Stoplight Prism (free) | Alternative: build a richer custom mock with scenarios. Recommend Prism. | +| 4 | Liveview transport for v1 | HLS via QtMultimedia | Easiest. Add WebRTC in v2 if sub-second latency is needed. | +| 5 | Object store | S3 / MinIO / local FS | Choose per deployment; behind a generic `ObjectStore` interface. | +| 6 | Auto-update mechanism | Sparkle (Mac), MSIX / custom (Win), AppImage (Linux) | Confirm budget for code signing per platform. | +| 7 | Contract repo location | `ANSCORE/contracts/` (current) | Separate `anscore-contracts` repo if teams diverge. | + +\newpage + +# Appendix A — Full endpoint catalog + +Complete list of v1 operations. See `contracts/openapi.v1.json` for full request / response schemas. + +## auth + +| Method | Path | Purpose | +|---|---|---| +| POST | `/auth/login` | Log in (returns `access_token`, `expires_at`, `user`) | +| POST | `/auth/logout` | Invalidate token | +| POST | `/auth/refresh` | Exchange refresh token for new access token | + +## users + +| Method | Path | Purpose | +|---|---|---| +| GET | `/users` | List users (paginated) | +| POST | `/users` | Create user | +| GET | `/users/{id}` | Get user | +| PATCH | `/users/{id}` | Update user | +| DELETE | `/users/{id}` | Delete user | + +## cameras + +| Method | Path | Purpose | +|---|---|---| +| GET | `/cameras` | List cameras (filters: driver, active, edge_id, deployment_group_id) | +| POST | `/cameras` | Create camera | +| GET | `/cameras/{id}` | Get camera | +| PUT | `/cameras/{id}` | Replace camera | +| PATCH | `/cameras/{id}` | Patch camera | +| DELETE | `/cameras/{id}` | Delete camera | +| GET | `/cameras/{id}/snapshot` | Get JPEG snapshot (or presigned URL) | +| GET | `/cameras/{id}/liveview` | Get liveview descriptor (`{url, transport, token, expires_at}`) | +| POST | `/cameras/scan` | Async ONVIF scan (returns job) | +| POST | `/cameras/probe` | Probe single IP for ONVIF profiles | + +## models + +| Method | Path | Purpose | +|---|---|---| +| GET | `/models` | List models (filter by type) | +| POST | `/models` | Upload + register (multipart, ≤10 MB) | +| GET | `/models/{id}` | Get model | +| PATCH | `/models/{id}` | Update model metadata | +| DELETE | `/models/{id}` | Delete model | +| POST | `/models:initiate-upload` | Begin large upload (returns presigned PUT URL) | +| POST | `/models:complete-upload` | Finalize large upload | + +## edges + +| Method | Path | Purpose | +|---|---|---| +| GET | `/edges` | List edges | +| POST | `/edges` | Register edge | +| GET | `/edges/{id}` | Get edge | +| PATCH | `/edges/{id}` | Update edge | +| DELETE | `/edges/{id}` | Delete edge | +| GET | `/edges/{id}/health` | Resource / temp / uptime | +| GET | `/edges/{id}/status` | State (online/offline/degraded) + counts | + +## deployment-groups + +| Method | Path | Purpose | +|---|---|---| +| GET | `/deployment-groups` | List groups | +| POST | `/deployment-groups` | Create group | +| GET | `/deployment-groups/{id}` | Get group | +| PUT | `/deployment-groups/{id}` | Replace group | +| DELETE | `/deployment-groups/{id}` | Delete group | +| GET | `/deployment-groups/{id}/status` | Runtime status | +| POST | `/deployment-groups/{id}/start` | Start group | +| POST | `/deployment-groups/{id}/stop` | Stop group | + +## ai-tasks + +| Method | Path | Purpose | +|---|---|---| +| GET | `/ai-tasks` | List tasks | +| POST | `/ai-tasks` | Create task | +| GET | `/ai-tasks/{id}` | Get task | +| PUT | `/ai-tasks/{id}` | Replace task | +| PATCH | `/ai-tasks/{id}` | Patch task | +| DELETE | `/ai-tasks/{id}` | Delete task | +| GET | `/ai-tasks/{id}/status` | Get task runtime status | +| POST | `/ai-tasks/{id}/start` | Start task | +| POST | `/ai-tasks/{id}/stop` | Stop task | +| GET | `/ai-tasks/{id}/liveview` | Liveview descriptor for annotated stream | +| GET | `/ai-tasks/catalog` | List supported task types | + +## events + +| Method | Path | Purpose | +|---|---|---| +| GET | `/events` | List events (filters: task_id, camera_id, object, from, to) | +| GET | `/events/summary` | Analytics rollup | +| GET | `/events/stream` | Live event tail (Server-Sent Events) | +| GET | `/events/{id}` | Get one event | +| GET | `/events/{id}/image` | JPEG snapshot | +| GET | `/events/{id}/clip` | Presigned URL for evidence clip | + +## fr (face recognition) + +| Method | Path | Purpose | +|---|---|---| +| GET | `/fr/persons` | List persons | +| POST | `/fr/persons` | Create person | +| GET | `/fr/persons/{id}` | Get person | +| PATCH | `/fr/persons/{id}` | Update person | +| DELETE | `/fr/persons/{id}` | Delete person | +| GET | `/fr/persons/{id}/faces` | List faces for person | +| POST | `/fr/persons/{id}/faces` | Add face (multipart, no base64) | +| DELETE | `/fr/faces/{face_id}` | Delete face | +| GET | `/fr/person-groups` | List person groups | +| POST | `/fr/person-groups` | Create group | +| PATCH | `/fr/person-groups/{id}` | Update group | +| DELETE | `/fr/person-groups/{id}` | Delete group | +| GET | `/fr/config` | Get FR detection config | +| PATCH | `/fr/config` | Update FR detection config | + +## fr-recording + +| Method | Path | Purpose | +|---|---|---| +| GET | `/fr/recording-tasks` | List tasks | +| POST | `/fr/recording-tasks` | Create task | +| DELETE | `/fr/recording-tasks/{id}` | Delete task | +| POST | `/fr/recording-tasks/{id}/start` | Start task | +| POST | `/fr/recording-tasks/{id}/stop` | Stop task | +| GET | `/fr/recording-tasks/{id}/faces` | Read recorded faces | +| PATCH | `/fr/recording-tasks/{id}/faces` | Assign recorded faces to a person (bulk) | + +## alpr + +| Method | Path | Purpose | +|---|---|---| +| GET | `/alpr/plates` | List plates | +| POST | `/alpr/plates` | Register plates (bulk) | +| DELETE | `/alpr/plates/{plate}` | Deregister single plate | +| POST | `/alpr/plates:bulk-delete` | Deregister bulk | +| GET | `/alpr/plate-groups` | List plate groups | +| POST | `/alpr/plate-groups` | Create group | +| PATCH | `/alpr/plate-groups/{id}` | Update group | +| DELETE | `/alpr/plate-groups/{id}` | Delete group | + +## notifications + +| Method | Path | Purpose | +|---|---|---| +| GET | `/notifications/recipients` | List recipients | +| POST | `/notifications/recipients` | Create recipient | +| PATCH | `/notifications/recipients/{id}` | Update recipient | +| DELETE | `/notifications/recipients/{id}` | Delete recipient | +| GET | `/notifications/recipient-groups` | List recipient groups | + +## triggers + +| Method | Path | Purpose | +|---|---|---| +| GET | `/triggers/types` | List supported trigger types + config schemas | +| POST | `/triggers/test` | Dispatch a test trigger (HTTP / MQTT / Email / etc.) | + +## system + +| Method | Path | Purpose | +|---|---|---| +| GET | `/system/status` | Liveness probe | +| GET | `/system/health` | Resources + counts | +| GET | `/system/info` | Hostname / OS / hardware | +| GET | `/system/logs` | Paginated logs | +| GET | `/system/version` | Version + build date + commit | +| GET | `/system/update` | Update status | +| POST | `/system/update` | Trigger update (async job) | + +## jobs + +| Method | Path | Purpose | +|---|---|---| +| GET | `/jobs/{id}` | Get async job status / result | + +## composite + +| Method | Path | Purpose | +|---|---|---| +| POST | `/composite/camera-with-tasks` | Create camera + deployment groups in one call | + +\newpage + +# Appendix B — Artifacts in the repository + +``` +ANSCORE/ +├── contracts/ +│ └── openapi.v1.json # The single source of truth for L2 ↔ L3 +│ +├── docs/ +│ ├── ANSCORE-system-architecture.md # This document (source) +│ ├── ANSCORE-system-architecture.pdf # This document (rendered) +│ ├── L2-L3-architecture.md # Same content with Mermaid diagrams +│ └── diagrams/ +│ ├── 01-system-context.puml # PlantUML sources +│ ├── 02-l2-internals.puml +│ ├── 03-l2-ownership.puml +│ ├── 04-l3-internals.puml +│ ├── 05-seq-configure-deploy.puml +│ ├── 06-seq-live-events.puml +│ ├── 07-seq-liveview.puml +│ ├── 08-seq-async-scan.puml +│ ├── 09-seq-large-upload.puml +│ ├── 10-deployment-topology.puml +│ ├── 11-l3-engineer-ownership.puml +│ ├── 12-dependency-chain.puml +│ ├── README.md +│ ├── PREVIEW.md # Clickable plantuml.com URLs +│ └── png/ # Pre-rendered PNGs (used in this PDF) +│ +└── modules/ # Existing C++ building blocks (L1 ingredients) + ├── ANSCV/ ANSODEngine/ ANSFR/ ANSLPR/ ANSOCR/ + ├── ANSMOT/ ANSPulsar/ ANSRabbitMQ/ ANSONVIF/ + └── ... +``` + +# Appendix C — Glossary + +| Term | Meaning | +|---|---| +| **L1** | Layer 1 — edge runtime (per target) | +| **L2** | Layer 2 — ANSVIS CL (per customer) | +| **L3** | Layer 3 — Qt/QML desktop UI (per operator workstation) | +| **Adapter (v1)** | The L2 module that translates `/api/v1` requests to legacy ANSVIS calls | +| **Edge / target** | A physical device running L1 (Windows/Linux on x86 or NVIDIA Jetson) | +| **Deployment group** | A bundle of cameras + models + rules + triggers deployed to a target | +| **AI task** | A configured pipeline (camera + model + rules + triggers) ready to run | +| **Event** | A detection emitted by an AI task, with evidence (snapshot + optional clip) | +| **Liveview** | Real-time video from a camera, with optional bbox overlay | +| **Trigger** | An outbound action when a rule fires (HTTP, MQTT, email, push, broker) | +| **ONVIF** | Camera-discovery and control protocol used by IP cameras | +| **SSE** | Server-Sent Events — one-way push from server to client over HTTPS | +| **RFC 7807** | The `application/problem+json` standard error format | +| **Prism** | Stoplight's CLI for spinning up a mock REST server from an OpenAPI spec | +| **OpenAPI 3.1** | The contract format used in `openapi.v1.json` | + +--- + +*End of document.* diff --git a/docs/ANSCORE-system-architecture.pdf b/docs/ANSCORE-system-architecture.pdf new file mode 100644 index 0000000..ba8819d Binary files /dev/null and b/docs/ANSCORE-system-architecture.pdf differ diff --git a/docs/L2-L3-architecture.md b/docs/L2-L3-architecture.md new file mode 100644 index 0000000..9ee4f20 --- /dev/null +++ b/docs/L2-L3-architecture.md @@ -0,0 +1,600 @@ +# ANSCORE — Layer 2 & Layer 3 Architecture + +> Scope: Layer 2 (ANSVIS Communication Layer (CL), REST `/api/v1` surface, supporting services) and Layer 3 (Qt/QML cross-platform desktop UI). Layer 1 is summarized only where it interacts. +> +> Contract of record: [`contracts/openapi.v1.json`](../contracts/openapi.v1.json). All UI ↔ CL communication conforms to it. +> +> Transports: +> 1. **REST / HTTPS** — control, CRUD, configuration, deploy +> 2. **SSE (`text/event-stream`)** — live event tail +> 3. **HLS / RTSP / WebRTC** — live video (descriptor obtained via REST) + +--- + +## 1. System context — L1 / L2 / L3 + +```mermaid +graph TB + subgraph L3["Layer 3 — Qt/QML Desktop UI (Win / Mac / Linux)"] + UI[Qt/QML application] + end + + subgraph L2["Layer 2 — ANSVIS CL"] + APIV1["/api/v1 REST surface"] + LEGACY["Legacy ANSVIS core
(reused as-is)"] + RELAY["Media relay
HLS / RTSP / WebRTC"] + SSE["SSE event broadcaster"] + STORE["Event DB
+ clip object store"] + JOBS["Async job queue"] + AUTH["Auth + RBAC"] + end + + subgraph L1["Layer 1 — ANSCORE Edge Runtime
(one per target)"] + EDGE["Camera + Inference + Triggers"] + end + + UI -- "① REST / HTTPS
control + CRUD" --> APIV1 + UI -- "② SSE / HTTPS
live event tail" --> SSE + UI -- "③ HLS / RTSP / WebRTC
live video" --> RELAY + + APIV1 --> AUTH + APIV1 --> LEGACY + APIV1 --> JOBS + APIV1 --> STORE + LEGACY --> STORE + STORE --> SSE + RELAY <--> EDGE + LEGACY <--> EDGE +``` + +**Key idea:** L3 only ever talks to L2. L1 ↔ L2 is a separate protocol (existing ANSVIS behavior, plus new edge work later). The UI team is fully decoupled from L1 velocity. + +--- + +## 2. Layer 2 — internal architecture + +```mermaid +graph TB + subgraph CLIENTS["Clients"] + QT["Qt/QML UI"] + EXT["3rd-party integrations
(optional)"] + end + + subgraph EDGE_API["L2 / api / v1 surface"] + ROUTER["REST router"] + AUTHMW["Auth middleware
(Bearer)"] + VALID["Request validation
(OpenAPI schemas)"] + ERR["Error mapper
→ RFC 7807"] + RATE["Rate limiter"] + SSE_HUB["SSE broadcaster
(per-subscription filter)"] + end + + subgraph ADAPTER["v1 Adapter Layer
(per-resource modules)"] + CAM_AD["cameras"] + MOD_AD["models"] + EDGE_AD["edges"] + DG_AD["deployment-groups"] + TASK_AD["ai-tasks"] + EV_AD["events"] + FR_AD["fr"] + ALPR_AD["alpr"] + NOTIF_AD["notifications"] + SYS_AD["system"] + JOB_AD["jobs"] + end + + subgraph LEGACY["Legacy ANSVIS server
(reused as-is)"] + LEG_CFG["Config store"] + LEG_TASKS["AI task engine"] + LEG_FR["FR engine"] + LEG_ALPR["ALPR engine"] + end + + subgraph INFRA["Infrastructure"] + AUTH_SVC["Auth + token store"] + JOBS_Q["Job queue
(scans, uploads, deploys, updates)"] + EVENTS_DB["Event metadata DB"] + CLIPS["Clip / image object store
(S3 / MinIO / FS)"] + LOGS["Logs + metrics + health"] + RELAY["Media relay
HLS / RTSP / WebRTC"] + end + + subgraph L1["Layer 1 edges"] + E1["Edge target(s)"] + end + + QT --> ROUTER + EXT --> ROUTER + ROUTER --> AUTHMW --> VALID --> RATE + RATE --> ADAPTER + ADAPTER --> ERR + ADAPTER -.-> ROUTER + + AUTHMW --> AUTH_SVC + + CAM_AD --> LEG_CFG + MOD_AD --> LEG_CFG + MOD_AD --> CLIPS + EDGE_AD --> LEG_CFG + DG_AD --> LEG_TASKS + TASK_AD --> LEG_TASKS + EV_AD --> EVENTS_DB + EV_AD --> CLIPS + FR_AD --> LEG_FR + ALPR_AD --> LEG_ALPR + SYS_AD --> LOGS + JOB_AD --> JOBS_Q + CAM_AD -. "scan / probe" .-> JOBS_Q + MOD_AD -. "large upload" .-> JOBS_Q + + LEG_TASKS --> EVENTS_DB + EVENTS_DB --> SSE_HUB + SSE_HUB --> ROUTER + + LEGACY <--> E1 + RELAY <--> E1 +``` + +**Responsibilities by module:** + +| Module | Owns | +|---|---| +| REST router | URL → handler, content negotiation | +| Auth middleware | Bearer validation, principal injection, RBAC checks | +| Request validation | OpenAPI schema-based body/query validation | +| Error mapper | Translates legacy errors / exceptions to `application/problem+json` | +| Rate limiter | Per-token / per-IP throttling | +| SSE broadcaster | Subscribes to event bus, fans out to UI clients with filter + auth | +| v1 adapter (per resource) | Translates v1 request → legacy call(s), reshapes response | +| Job queue | Async ops (camera scan, model upload, software update, large deploy) | +| Event DB | Indexed event metadata for `/events?...` queries | +| Clip / object store | Snapshots and evidence video (presigned URLs) | +| Media relay | Brokers live video from edge to UI (HLS now, WebRTC later) | +| Auth + token store | Login, refresh, RBAC | + +**Build ownership inside L2** (AI coders managed by you): + +```mermaid +graph TB + subgraph HUMAN["Human-owned (architect — you)"] + H1["REST router + auth middleware"] + H2["RFC 7807 error mapper"] + H3["OpenAPI validation pipeline"] + H4["Auth flow + token store"] + H5["RBAC + security review"] + H6["L2 ↔ L1 tunnel + signing"] + end + + subgraph AI["AI-coder-built (modular adapters)"] + A1["cameras adapter"] + A2["models adapter + upload pipeline"] + A3["edges adapter"] + A4["deployment-groups adapter"] + A5["ai-tasks adapter"] + A6["events adapter + SSE broadcaster"] + A7["fr adapter"] + A8["alpr adapter"] + A9["notifications adapter"] + A10["system / health / logs adapter"] + A11["job queue + workers"] + A12["media relay"] + end + + subgraph EXIST["Existing ANSVIS (reused as-is)"] + L1["Task engine"] + L2["FR engine"] + L3["ALPR engine"] + L4["Config store"] + end + + HUMAN --> AI + AI --> EXIST +``` + +--- + +## 3. Layer 3 — Qt/QML internal architecture + +```mermaid +graph TB + subgraph QT["Qt 6 + QML — Layer 3"] + subgraph SHELL["App Shell"] + MAIN["Main window"] + ROUTE["Navigation router"] + THEME["Design system / theme"] + I18N["i18n (qsTr / Linguist)"] + AUTH_ST["Auth state + token store"] + ERR_UI["Error toast / dialog"] + end + + subgraph NET["Network layer"] + REST["Generated REST client
(openapi.v1.json → C++/Qt)"] + SSE_CL["SSE subscriber
(QNetworkReply chunked)"] + MEDIA["Media client
QtMultimedia / GStreamer"] + OVERLAY["Bbox overlay renderer
(custom QQuickItem)"] + UPLOAD["Multipart + presigned uploader"] + end + + subgraph STATE["Domain state (QObject + Q_PROPERTY + signals)"] + ST_CAM["CamerasModel"] + ST_MOD["ModelsModel"] + ST_EDGE["EdgesModel"] + ST_DG["DeploymentGroupsModel"] + ST_TASK["AITasksModel"] + ST_EV["EventsModel + LiveBuffer"] + ST_FR["FRPersonsModel"] + ST_ALPR["ALPRPlatesModel"] + ST_NOTIF["RecipientsModel"] + ST_SYS["SystemHealthModel"] + end + + subgraph SCREENS["Screens (QML)"] + LOGIN["Login"] + DASH["Dashboard / targets overview"] + CAM_S["Camera management
+ ONVIF discovery
+ calibration"] + DG_EDIT["Pipeline editor
(visual DAG)"] + TASK_EDIT["AI Task config"] + RULE_S["Rules / triggers"] + LIVE["Liveview grid"] + EV_S["Eventview timeline"] + FR_S["FR persons + faces"] + ALPR_S["ALPR plates"] + MODEL_S["Model registry"] + USERS["Users / admin"] + SETTINGS["Settings"] + end + end + + subgraph L2["ANSVIS / api / v1"] + BACKEND["REST + SSE + media"] + end + + SCREENS --> STATE + STATE --> NET + NET <--> BACKEND + OVERLAY -.-> MEDIA + AUTH_ST -.-> REST + AUTH_ST -.-> SSE_CL +``` + +**Module → screen map** (for tasking): + +| Screen | Reads from | Writes via | Notes | +|---|---|---|---| +| Login | — | `POST /auth/login` | Stores token in `AuthState` | +| Dashboard | `GET /edges`, `GET /edges/{id}/health`, `GET /system/health` | — | Auto-refresh every 5s | +| Camera management | `GET /cameras`, `GET /cameras/{id}/snapshot`, `POST /cameras/probe` | `POST/PATCH/DELETE /cameras`, `POST /cameras/scan` (async job) | ONVIF discovery + calibration overlay | +| Pipeline editor | `GET /deployment-groups/{id}`, `GET /ai-tasks/catalog`, `GET /models` | `PUT /deployment-groups/{id}` | Highest-risk feature; QGraphicsView | +| AI Task config | `GET /ai-tasks/{id}`, `GET /ai-tasks/catalog` | `POST/PATCH/DELETE /ai-tasks`, `POST /ai-tasks/{id}/start|stop` | Schema-driven forms | +| Rules / triggers | `GET /triggers/types` | embedded in deployment-group / task body | `POST /triggers/test` | +| Liveview | `GET /cameras/{id}/liveview` | — | HLS in v1, WebRTC later; overlay sync to PTS | +| Eventview | `GET /events?filters`, `GET /events/stream` (SSE), `GET /events/{id}/image`, `GET /events/{id}/clip` | — | Virtualized list for 100k+ events | +| FR persons + faces | `GET /fr/persons`, `GET /fr/persons/{id}/faces` | `POST/PATCH/DELETE /fr/persons`, `POST /fr/persons/{id}/faces` (multipart) | Multipart image upload | +| ALPR plates | `GET /alpr/plates`, `GET /alpr/plate-groups` | `POST/DELETE /alpr/plates`, `PATCH /alpr/plate-groups/{id}` | Bulk register/deregister | +| Model registry | `GET /models` | `POST /models` (multipart), `POST /models:initiate-upload` for big files | Upload progress UI | +| Users / admin | `GET /users` | `POST/PATCH/DELETE /users/{id}` | Admin role only | +| Settings | `GET /system/info`, `GET /system/version`, `GET /system/update` | `POST /system/update` | | + +--- + +## 4. Sequence flows + +### 4.1 Configure & deploy — typical operator workflow + +```mermaid +sequenceDiagram + actor User as Operator + participant UI as Qt UI + participant API as ANSVIS /api/v1 + participant LEG as ANSVIS core + participant EDGE as L1 edge + + User->>UI: Open Cameras screen + UI->>API: GET /cameras?page=1 + API->>LEG: legacy list + LEG-->>API: cameras + API-->>UI: 200 {items, page, total} + + User->>UI: Add RTSP camera (form) + UI->>API: POST /cameras + Note right of UI: body has nested credentials,
capturing, image_size — no
stringified JSON + API->>LEG: legacy add + LEG-->>API: id=123 + API-->>UI: 201 Location: /cameras/123 + + User->>UI: Configure AI task + UI->>API: POST /ai-tasks {camera_id:123, ...} + API->>LEG: legacy create + LEG-->>API: id=456 + API-->>UI: 201 {id:456} + + User->>UI: Start task + UI->>API: POST /ai-tasks/456/start + API->>LEG: dispatch + LEG->>EDGE: config + start + EDGE-->>LEG: running + API-->>UI: 202 {state:starting} + + loop status poll (or SSE later) + UI->>API: GET /ai-tasks/456/status + API-->>UI: 200 {state:running, fps:14.2} + end +``` + +### 4.2 Live event tail + clicking into evidence + +```mermaid +sequenceDiagram + actor User + participant UI + participant API as /api/v1 + participant SSE as SSE broadcaster + participant CLIPS as Clip store + participant EDGE + + User->>UI: Open Eventview (task=456) + UI->>API: GET /events?task_id=456&page=1 + API-->>UI: 200 historical events + UI->>API: GET /events/stream?task_id=456 + API-->>UI: text/event-stream (open) + + EDGE->>API: event arrives (via L1↔L2) + API->>SSE: push EventRecord + SSE-->>UI: data: {id:E1, ts, object:car, bbox, ...} + + User->>UI: Click event E1 + UI->>API: GET /events/E1 + API-->>UI: 200 EventRecord (full) + UI->>API: GET /events/E1/image?width=640 + API-->>UI: image/jpeg bytes + + User->>UI: Play clip + UI->>API: GET /events/E1/clip + API->>CLIPS: presign GET + CLIPS-->>API: presigned URL + API-->>UI: 200 {url, expires_at} + UI->>CLIPS: GET + CLIPS-->>UI: MP4 bytes + UI->>UI: play in QtMultimedia +``` + +### 4.3 Liveview with bbox overlay + +```mermaid +sequenceDiagram + actor User + participant UI + participant API + participant RELAY as Media relay + participant EDGE + participant SSE + + User->>UI: Open Liveview (cam 123, task 456) + UI->>API: GET /cameras/123/liveview?transport=hls + API->>RELAY: ensure HLS for cam 123 + RELAY->>EDGE: pull RTSP + RELAY-->>API: hls_url + short-lived token + API-->>UI: 200 {url, transport:hls, auth_token, expires_at} + + UI->>RELAY: GET hls_url (token) + RELAY-->>UI: m3u8 + segments + UI->>UI: Render video (QtMultimedia) + + UI->>API: GET /events/stream?task_id=456 (SSE) + API-->>UI: text/event-stream + loop per event + SSE-->>UI: bbox + ts + UI->>UI: overlay synced to PTS + end +``` + +### 4.4 Async job — camera network scan + +```mermaid +sequenceDiagram + actor User + participant UI + participant API + participant JOBS as Job queue + participant SCAN as ONVIF scanner + + User->>UI: Scan 192.168.1.0/24 + UI->>API: POST /cameras/scan + API->>JOBS: enqueue + JOBS-->>API: job_id=j1 + API-->>UI: 202 {job_id:j1, status:queued, links:{self:/jobs/j1}} + + JOBS->>SCAN: run + loop poll until terminal + UI->>API: GET /jobs/j1 + API-->>UI: 200 {status:running, progress:0.4} + end + SCAN-->>JOBS: results + UI->>API: GET /jobs/j1 + API-->>UI: 200 {status:succeeded, result:{discovered:[...]}} +``` + +### 4.5 Large model upload — initiate / complete pattern + +```mermaid +sequenceDiagram + actor User + participant UI + participant API + participant OBJ as Object store + + User->>UI: Pick model.zip (500 MB) + UI->>API: POST /models:initiate-upload {filename, size_bytes, checksum} + API->>OBJ: presign PUT + OBJ-->>API: presigned_url + API-->>UI: 200 {upload_id, presigned_url, expires_at} + + UI->>OBJ: PUT (binary stream, with progress) + OBJ-->>UI: 200 OK + + UI->>API: POST /models:complete-upload {upload_id, metadata} + API->>OBJ: verify checksum + OBJ-->>API: ok + API-->>UI: 201 Model +``` + +--- + +## 5. Deployment topology + +```mermaid +graph LR + subgraph CUSTOMER["Customer site / cloud"] + subgraph DESKTOPS["Operator workstations"] + D1["Win desktop
Qt UI"] + D2["Mac desktop
Qt UI"] + D3["Linux desktop
Qt UI"] + end + + subgraph SERVER["ANSVIS server host"] + NGINX["Reverse proxy
TLS terminator"] + APP["ANSVIS app
(adapter + legacy core)"] + RELAY["Media relay"] + OBJ["Object store
(S3/MinIO/FS)"] + DB["DBs
(config / events)"] + end + + subgraph EDGES["Edge targets"] + E1["Linux x86 + NV"] + E2["Win x86 + NV"] + E3["Jetson Orin"] + end + end + + D1 -- "TLS 443
REST + SSE + HLS" --> NGINX + D2 -- "TLS 443" --> NGINX + D3 -- "TLS 443" --> NGINX + NGINX --> APP + NGINX --> RELAY + APP --> DB + APP --> OBJ + RELAY <--> EDGES + APP <--> EDGES +``` + +**Network rules to communicate to the customer:** +- Outbound TCP 443 from each operator workstation to ANSVIS server. +- Inbound 443 on ANSVIS server. +- Whatever protocol L1 ↔ L2 needs (TCP 443 if everything tunneled; or per-edge ports if direct). +- No need for the workstation to reach edges directly — Media relay proxies. + +--- + +## 6. L3 — engineer ownership (6 engineers) + +```mermaid +graph TB + subgraph E1["E1 — UI Lead / Shell Architect"] + E1A["Qt 6 + CMake monorepo"] + E1B["Generated REST client from openapi.v1.json"] + E1C["Auth state + token store"] + E1D["Design system / theme"] + E1E["Navigation router"] + E1F["Packaging Win/Mac/Linux
signing, notarize, auto-update"] + E1G["CI matrix"] + end + + subgraph E2["E2 — Pipeline Editor Specialist"] + E2A["Visual DAG editor
QGraphicsView in QQuickWidget"] + E2B["Node library + connections"] + E2C["Schema-driven param panels"] + E2D["Undo / redo, save / version"] + end + + subgraph E3["E3 — Liveview / Media"] + E3A["QtMultimedia HLS player
(v1)"] + E3B["Multi-stream grid"] + E3C["Bbox overlay (QQuickItem + QSGGeometryNode)"] + E3D["Clip player (evidence)"] + E3E["WebRTC via GStreamer (v2)"] + end + + subgraph E4["E4 — Config Forms"] + E4A["Schema-driven QML forms
(from openapi.v1.json)"] + E4B["Camera + ONVIF discovery flow"] + E4C["Camera calibration UI
(ROI / zones / homography)"] + E4D["Model + plugin + trigger forms"] + end + + subgraph E5["E5 — Dashboard / Eventview"] + E5A["Target dashboard cards + charts"] + E5B["Event timeline (virtualized)"] + E5C["SSE subscriber + LiveBuffer"] + E5D["Filter / search / evidence viewer"] + E5E["Multi-target monitoring"] + end + + subgraph E6["E6 — UX / Cross-platform QA"] + E6A["Design polish, a11y, i18n"] + E6B["Install / upgrade testing
Win + Mac + Linux"] + E6C["Crash reporting (Sentry/Crashpad)"] + E6D["QML Profiler perf passes"] + E6E["User docs surface"] + end + + CONTRACT[(openapi.v1.json
frozen contract)] + E1 -.-> CONTRACT + E2 -.-> CONTRACT + E3 -.-> CONTRACT + E4 -.-> CONTRACT + E5 -.-> CONTRACT +``` + +**Critical-path order:** + +1. **Week 1–2 (E1 only)**: monorepo, generated REST client, auth, design system stub, `make dev` brings up Prism mock. This unblocks everyone else. +2. **Week 1–2 (E2 in parallel)**: node-editor spike. Highest schedule risk → de-risk early. +3. **Week 2+ (E3, E4, E5 in parallel)**: each owns a vertical against the mock CL. E6 starts integration testing. +4. **Week 4+**: cut from mock CL to real ANSVIS `/api/v1` as adapter endpoints land. + +--- + +## 7. What gates what (dependency chain) + +```mermaid +graph LR + CONTRACT["openapi.v1.json
(frozen)"] + MOCK["Prism mock server"] + ADAPT["ANSVIS /api/v1 adapter
(AI coders, per-resource)"] + LEGACY["Legacy ANSVIS"] + UI_SHELL["L3 shell + REST client (E1)"] + UI_FEAT["L3 screens (E2-E6)"] + REAL["Real backend integration"] + SHIP["Ship v1"] + + CONTRACT --> MOCK + CONTRACT --> ADAPT + ADAPT --> LEGACY + MOCK --> UI_SHELL --> UI_FEAT + UI_FEAT --> REAL + ADAPT --> REAL + REAL --> SHIP +``` + +- The contract is the *only* thing both sides block on. +- UI does not wait for the adapter — develops against Prism. +- Adapter team does not wait for UI — implements per-resource modules in parallel. +- Integration is the joining point. + +--- + +## 8. Open decisions that affect this architecture + +These are unchanged from earlier conversations; capturing here so the team has them in one place: + +1. **Field naming** — `snake_case` (current default in `openapi.v1.json`) or `camelCase`? +2. **Auth scheme** — keep Bearer (current) or move to OAuth2/OIDC for v1? +3. **Mock-server pinning** — Prism for free, or build a richer custom mock? +4. **Liveview transport for v1** — HLS only (recommended), or RTSP-direct on LAN, or jump straight to WebRTC? +5. **Object store choice** — local FS (single host), MinIO (single host scalable), or S3 (cloud)? +6. **Auto-update** for the Qt client — Sparkle on Mac, Squirrel/MSIX on Windows, AppImage on Linux. Confirm budget for each. +7. **Contract repo** — co-located in `ANSCORE/contracts/` (current) or split into a separate `anscore-contracts` repo? + +--- + +*Last updated: 2026-05-26 — diagrams reflect `openapi.v1.json` v1.0.0 draft.* diff --git a/docs/diagrams/01-system-context.puml b/docs/diagrams/01-system-context.puml new file mode 100644 index 0000000..372f34d --- /dev/null +++ b/docs/diagrams/01-system-context.puml @@ -0,0 +1,48 @@ +@startuml 01-system-context +title ANSCORE — System Context (L1 / L2 / L3) + +skinparam componentStyle rectangle +skinparam packageStyle rectangle + +package "Layer 3 — Qt/QML Desktop UI\n(Windows / macOS / Linux)" as L3 { + component "Qt/QML application" as UI +} + +package "Layer 2 — ANSVIS Communication Layer (CL)" as L2 { + component "/api/v1\nREST surface" as APIV1 + component "Legacy ANSVIS core\n(reused as-is)" as LEGACY + component "Media relay\nHLS / RTSP / WebRTC" as RELAY + component "SSE event\nbroadcaster" as SSEHUB + database "Event DB\n+ clip object store" as STORE + queue "Async job queue" as JOBS + component "Auth + RBAC" as AUTH +} + +package "Layer 1 — ANSCORE Edge Runtime\n(one per target)" as L1 { + component "Camera + Inference\n+ Triggers" as EDGE +} + +UI --> APIV1 : (1) REST / HTTPS\ncontrol + CRUD +UI --> SSEHUB : (2) SSE / HTTPS\nlive event tail +UI --> RELAY : (3) HLS / RTSP / WebRTC\nlive video + +APIV1 --> AUTH +APIV1 --> LEGACY +APIV1 --> JOBS +APIV1 --> STORE +LEGACY --> STORE +STORE --> SSEHUB +RELAY <--> EDGE +LEGACY <--> EDGE + +note bottom of L3 + L3 only talks to L2 — never directly to edges. +end note + +note bottom of L2 + All three UI transports are brokered by the REST API: + the URL + token for live media and the SSE filter for + events are obtained via REST calls first. +end note + +@enduml diff --git a/docs/diagrams/02-l2-internals.puml b/docs/diagrams/02-l2-internals.puml new file mode 100644 index 0000000..3c551c3 --- /dev/null +++ b/docs/diagrams/02-l2-internals.puml @@ -0,0 +1,84 @@ +@startuml 02-l2-internals +title Layer 2 — ANSVIS internal architecture + +skinparam componentStyle rectangle +skinparam packageStyle rectangle + +actor "Qt / QML UI" as QT +actor "3rd-party\nintegrations" as EXT + +package "L2 /api/v1 surface" as EDGE_API { + component "REST router" as ROUTER + component "Auth middleware\n(Bearer)" as AUTHMW + component "Request validation\n(OpenAPI schemas)" as VALID + component "Error mapper\n(RFC 7807)" as ERR + component "Rate limiter" as RATE + component "SSE broadcaster\n(per-subscription filter)" as SSEHUB +} + +package "v1 Adapter Layer\n(per-resource modules)" as ADAPTER { + component "cameras" as CAM_AD + component "models" as MOD_AD + component "edges" as EDGE_AD + component "deployment-groups" as DG_AD + component "ai-tasks" as TASK_AD + component "events" as EV_AD + component "fr" as FR_AD + component "alpr" as ALPR_AD + component "notifications" as NOTIF_AD + component "system" as SYS_AD + component "jobs" as JOB_AD +} + +package "Legacy ANSVIS server\n(reused as-is)" as LEGACY { + component "Config store" as LEG_CFG + component "AI task engine" as LEG_TASKS + component "FR engine" as LEG_FR + component "ALPR engine" as LEG_ALPR +} + +package "Infrastructure" as INFRA { + component "Auth + token store" as AUTH_SVC + queue "Job queue\n(scans, uploads, deploys, updates)" as JOBS_Q + database "Event metadata DB" as EVENTS_DB + database "Clip / image object store\n(S3 / MinIO / FS)" as CLIPS + component "Logs + metrics + health" as LOGS + component "Media relay\nHLS / RTSP / WebRTC" as RELAY +} + +actor "L1 edge target(s)" as E1 + +QT --> ROUTER +EXT --> ROUTER +ROUTER --> AUTHMW +AUTHMW --> VALID +VALID --> RATE +RATE --> ADAPTER +ADAPTER --> ERR +ADAPTER ..> ROUTER : response + +AUTHMW --> AUTH_SVC + +CAM_AD --> LEG_CFG +MOD_AD --> LEG_CFG +MOD_AD --> CLIPS +EDGE_AD --> LEG_CFG +DG_AD --> LEG_TASKS +TASK_AD --> LEG_TASKS +EV_AD --> EVENTS_DB +EV_AD --> CLIPS +FR_AD --> LEG_FR +ALPR_AD --> LEG_ALPR +SYS_AD --> LOGS +JOB_AD --> JOBS_Q +CAM_AD ..> JOBS_Q : scan / probe +MOD_AD ..> JOBS_Q : large upload + +LEG_TASKS --> EVENTS_DB +EVENTS_DB --> SSEHUB +SSEHUB --> ROUTER + +LEGACY <--> E1 +RELAY <--> E1 + +@enduml diff --git a/docs/diagrams/03-l2-ownership.puml b/docs/diagrams/03-l2-ownership.puml new file mode 100644 index 0000000..7baa52a --- /dev/null +++ b/docs/diagrams/03-l2-ownership.puml @@ -0,0 +1,51 @@ +@startuml 03-l2-ownership +title Layer 2 — Build ownership + +skinparam componentStyle rectangle +skinparam packageStyle rectangle + +package "Architect-owned\n(lead review)" as HUMAN #LightYellow { + component "REST router\n+ auth middleware" as H1 + component "RFC 7807\nerror mapper" as H2 + component "OpenAPI validation\npipeline" as H3 + component "Auth flow\n+ token store" as H4 + component "RBAC\n+ security review" as H5 + component "L2 ↔ L1 tunnel\n+ signing" as H6 +} + +package "Core team\n(modular adapters)" as AI #LightBlue { + component "cameras adapter" as A1 + component "models adapter\n+ upload pipeline" as A2 + component "edges adapter" as A3 + component "deployment-groups\nadapter" as A4 + component "ai-tasks adapter" as A5 + component "events adapter\n+ SSE broadcaster" as A6 + component "fr adapter" as A7 + component "alpr adapter" as A8 + component "notifications adapter" as A9 + component "system / health /\nlogs adapter" as A10 + component "job queue + workers" as A11 + component "media relay" as A12 +} + +package "Existing ANSVIS\n(reused as-is)" as EXIST #LightGray { + component "Task engine" as L_TASKS + component "FR engine" as L_FR + component "ALPR engine" as L_ALPR + component "Config store" as L_CFG +} + +HUMAN --> AI +AI --> EXIST + +note bottom of HUMAN + Cross-cutting concerns kept under direct architect review: + request validation, errors, auth, RBAC, tunnel security. +end note + +note bottom of AI + Highly modular by resource — the core team works in parallel + on independent adapters without colliding. +end note + +@enduml diff --git a/docs/diagrams/04-l3-internals.puml b/docs/diagrams/04-l3-internals.puml new file mode 100644 index 0000000..28da01c --- /dev/null +++ b/docs/diagrams/04-l3-internals.puml @@ -0,0 +1,65 @@ +@startuml 04-l3-internals +title Layer 3 — Qt 6 / QML internal architecture + +skinparam componentStyle rectangle +skinparam packageStyle rectangle + +package "Qt 6 + QML — Layer 3" as QT { + + package "App Shell" as SHELL { + component "Main window" as MAIN + component "Navigation router" as ROUTE + component "Design system / theme" as THEME + component "i18n (qsTr / Linguist)" as I18N + component "Auth state + token store" as AUTH_ST + component "Error toast / dialog" as ERR_UI + } + + package "Network layer" as NET { + component "Generated REST client\n(openapi.v1.json → C++/Qt)" as REST + component "SSE subscriber\n(QNetworkReply chunked)" as SSE_CL + component "Media client\nQtMultimedia / GStreamer" as MEDIA + component "Bbox overlay renderer\n(custom QQuickItem)" as OVERLAY + component "Multipart + presigned\nuploader" as UPLOAD + } + + package "Domain state (QObject + signals)" as STATE { + component "CamerasModel" as ST_CAM + component "ModelsModel" as ST_MOD + component "EdgesModel" as ST_EDGE + component "DeploymentGroupsModel" as ST_DG + component "AITasksModel" as ST_TASK + component "EventsModel + LiveBuffer" as ST_EV + component "FRPersonsModel" as ST_FR + component "ALPRPlatesModel" as ST_ALPR + component "RecipientsModel" as ST_NOTIF + component "SystemHealthModel" as ST_SYS + } + + package "Screens (QML)" as SCREENS { + component "Login" as LOGIN + component "Dashboard /\ntargets overview" as DASH + component "Camera management\n+ ONVIF discovery\n+ calibration" as CAM_S + component "Pipeline editor\n(visual DAG)" as DG_EDIT + component "AI Task config" as TASK_EDIT + component "Rules / triggers" as RULE_S + component "Liveview grid" as LIVE + component "Eventview timeline" as EV_S + component "FR persons + faces" as FR_S + component "ALPR plates" as ALPR_S + component "Model registry" as MODEL_S + component "Users / admin" as USERS + component "Settings" as SETTINGS + } +} + +actor "ANSVIS /api/v1" as BACKEND + +SCREENS --> STATE : reads / mutates +STATE --> NET : calls +NET <--> BACKEND +OVERLAY ..> MEDIA : sync to PTS +AUTH_ST ..> REST : injects Bearer +AUTH_ST ..> SSE_CL : injects Bearer + +@enduml diff --git a/docs/diagrams/05-seq-configure-deploy.puml b/docs/diagrams/05-seq-configure-deploy.puml new file mode 100644 index 0000000..ed9dbcf --- /dev/null +++ b/docs/diagrams/05-seq-configure-deploy.puml @@ -0,0 +1,45 @@ +@startuml 05-seq-configure-deploy +title Sequence — Operator configures camera + AI task and deploys + +actor "Operator" as User +participant "Qt UI" as UI +participant "ANSVIS\n/api/v1" as API +participant "ANSVIS core" as LEG +participant "L1 edge" as EDGE + +User -> UI : Open Cameras screen +UI -> API : GET /cameras?page=1 +API -> LEG : legacy list +LEG --> API : cameras +API --> UI : 200 {items, page, total} + +User -> UI : Add RTSP camera (form) +UI -> API : POST /cameras +note right of UI + body has nested credentials, + capturing, image_size — + no stringified JSON +end note +API -> LEG : legacy add +LEG --> API : id=123 +API --> UI : 201 Location: /cameras/123 + +User -> UI : Configure AI task +UI -> API : POST /ai-tasks\n{camera_id:123, ...} +API -> LEG : legacy create +LEG --> API : id=456 +API --> UI : 201 {id:456} + +User -> UI : Start task +UI -> API : POST /ai-tasks/456/start +API -> LEG : dispatch +LEG -> EDGE : config + start +EDGE --> LEG : running +API --> UI : 202 {state:starting} + +loop status poll (or SSE later) + UI -> API : GET /ai-tasks/456/status + API --> UI : 200 {state:running, fps:14.2} +end + +@enduml diff --git a/docs/diagrams/06-seq-live-events.puml b/docs/diagrams/06-seq-live-events.puml new file mode 100644 index 0000000..fb5a83b --- /dev/null +++ b/docs/diagrams/06-seq-live-events.puml @@ -0,0 +1,36 @@ +@startuml 06-seq-live-events +title Sequence — Live event tail + clicking into evidence + +actor "Operator" as User +participant "Qt UI" as UI +participant "ANSVIS\n/api/v1" as API +participant "SSE broadcaster" as SSE +participant "Clip store\n(S3 / MinIO / FS)" as CLIPS +participant "L1 edge" as EDGE + +User -> UI : Open Eventview (task=456) +UI -> API : GET /events?task_id=456&page=1 +API --> UI : 200 historical events +UI -> API : GET /events/stream?task_id=456 +API --> UI : text/event-stream (open) + +EDGE -> API : event arrives (via L1↔L2) +API -> SSE : push EventRecord +SSE --> UI : data: {id:E1, ts, object:car, bbox, ...} + +User -> UI : Click event E1 +UI -> API : GET /events/E1 +API --> UI : 200 EventRecord (full) +UI -> API : GET /events/E1/image?width=640 +API --> UI : image/jpeg bytes + +User -> UI : Play clip +UI -> API : GET /events/E1/clip +API -> CLIPS : presign GET +CLIPS --> API : presigned URL +API --> UI : 200 {url, expires_at} +UI -> CLIPS : GET +CLIPS --> UI : MP4 bytes +UI -> UI : play in QtMultimedia + +@enduml diff --git a/docs/diagrams/07-seq-liveview.puml b/docs/diagrams/07-seq-liveview.puml new file mode 100644 index 0000000..85b757c --- /dev/null +++ b/docs/diagrams/07-seq-liveview.puml @@ -0,0 +1,30 @@ +@startuml 07-seq-liveview +title Sequence — Liveview with bbox overlay + +actor "Operator" as User +participant "Qt UI" as UI +participant "ANSVIS\n/api/v1" as API +participant "Media relay" as RELAY +participant "L1 edge" as EDGE +participant "SSE broadcaster" as SSE + +User -> UI : Open Liveview (cam 123, task 456) +UI -> API : GET /cameras/123/liveview?transport=hls +API -> RELAY : ensure HLS for cam 123 +RELAY -> EDGE : pull RTSP +RELAY --> API : hls_url + short-lived token +API --> UI : 200 {url, transport:hls,\nauth_token, expires_at} + +UI -> RELAY : GET hls_url (token) +RELAY --> UI : m3u8 + segments +UI -> UI : Render video\n(QtMultimedia) + +UI -> API : GET /events/stream?task_id=456 (SSE) +API --> UI : text/event-stream + +loop per event + SSE --> UI : bbox + ts + UI -> UI : overlay synced to PTS +end + +@enduml diff --git a/docs/diagrams/08-seq-async-scan.puml b/docs/diagrams/08-seq-async-scan.puml new file mode 100644 index 0000000..7a5b208 --- /dev/null +++ b/docs/diagrams/08-seq-async-scan.puml @@ -0,0 +1,27 @@ +@startuml 08-seq-async-scan +title Sequence — Async camera network scan (job pattern) + +actor "Operator" as User +participant "Qt UI" as UI +participant "ANSVIS\n/api/v1" as API +participant "Job queue" as JOBS +participant "ONVIF scanner" as SCAN + +User -> UI : Scan 192.168.1.0/24 +UI -> API : POST /cameras/scan +API -> JOBS : enqueue +JOBS --> API : job_id=j1 +API --> UI : 202 {job_id:j1,\n status:queued,\n links:{self:/jobs/j1}} + +JOBS -> SCAN : run + +loop poll until terminal + UI -> API : GET /jobs/j1 + API --> UI : 200 {status:running, progress:0.4} +end + +SCAN --> JOBS : results +UI -> API : GET /jobs/j1 +API --> UI : 200 {status:succeeded,\n result:{discovered:[...]}} + +@enduml diff --git a/docs/diagrams/09-seq-large-upload.puml b/docs/diagrams/09-seq-large-upload.puml new file mode 100644 index 0000000..43c6815 --- /dev/null +++ b/docs/diagrams/09-seq-large-upload.puml @@ -0,0 +1,23 @@ +@startuml 09-seq-large-upload +title Sequence — Large model upload (initiate / complete pattern) + +actor "Operator" as User +participant "Qt UI" as UI +participant "ANSVIS\n/api/v1" as API +participant "Object store\n(S3 / MinIO / FS)" as OBJ + +User -> UI : Pick model.zip (500 MB) +UI -> API : POST /models:initiate-upload\n{filename, size_bytes, checksum} +API -> OBJ : presign PUT +OBJ --> API : presigned_url +API --> UI : 200 {upload_id, presigned_url, expires_at} + +UI -> OBJ : PUT \n(binary stream, with progress) +OBJ --> UI : 200 OK + +UI -> API : POST /models:complete-upload\n{upload_id, metadata} +API -> OBJ : verify checksum +OBJ --> API : ok +API --> UI : 201 Model + +@enduml diff --git a/docs/diagrams/10-deployment-topology.puml b/docs/diagrams/10-deployment-topology.puml new file mode 100644 index 0000000..138f5ab --- /dev/null +++ b/docs/diagrams/10-deployment-topology.puml @@ -0,0 +1,51 @@ +@startuml 10-deployment-topology +title Deployment Topology + +skinparam componentStyle rectangle + +node "Customer site / cloud" { + + node "Operator workstations" { + component "Windows desktop\nQt UI" as D1 + component "macOS desktop\nQt UI" as D2 + component "Linux desktop\nQt UI" as D3 + } + + node "ANSVIS server host" { + component "Reverse proxy\nTLS terminator\n(nginx / caddy)" as NGINX + component "ANSVIS app\n(adapter + legacy core)" as APP + component "Media relay" as RELAY + database "Object store\n(S3 / MinIO / FS)" as OBJ + database "Config + Event DBs" as DB + } + + node "Edge targets" { + node "Linux x86 + NVIDIA" as E1 + node "Windows x86 + NVIDIA" as E2 + node "Jetson Orin" as E3 + } +} + +D1 --> NGINX : TLS 443\nREST + SSE + HLS +D2 --> NGINX : TLS 443 +D3 --> NGINX : TLS 443 +NGINX --> APP +NGINX --> RELAY +APP --> DB +APP --> OBJ +RELAY <--> E1 +RELAY <--> E2 +RELAY <--> E3 +APP <--> E1 +APP <--> E2 +APP <--> E3 + +note bottom + Network rules for the customer: + - Outbound TCP 443 from each workstation → ANSVIS host + - Inbound TCP 443 on ANSVIS host + - L2 ↔ L1 protocol per edge (port + tunnel TBD) + - Workstations never reach edges directly — Media relay proxies +end note + +@enduml diff --git a/docs/diagrams/11-l3-engineer-ownership.puml b/docs/diagrams/11-l3-engineer-ownership.puml new file mode 100644 index 0000000..a062ccf --- /dev/null +++ b/docs/diagrams/11-l3-engineer-ownership.puml @@ -0,0 +1,71 @@ +@startuml 11-l3-engineer-ownership +title Layer 3 — Engineer ownership (6 engineers) + +skinparam componentStyle rectangle +skinparam packageStyle rectangle + +package "E1 — UI Lead / Shell Architect" as E1 #LightYellow { + component "Qt 6 + CMake monorepo" as E1A + component "Generated REST client\nfrom openapi.v1.json" as E1B + component "Auth state + token store" as E1C + component "Design system / theme" as E1D + component "Navigation router" as E1E + component "Packaging Win/Mac/Linux\nsigning, notarize,\nauto-update" as E1F + component "CI matrix" as E1G +} + +package "E2 — Pipeline Editor Specialist" as E2 #LightBlue { + component "Visual DAG editor\n(QGraphicsView in QQuickWidget)" as E2A + component "Node library +\nconnection validation" as E2B + component "Schema-driven param panels" as E2C + component "Undo / redo,\nsave / version" as E2D +} + +package "E3 — Liveview / Media" as E3 #LightGreen { + component "QtMultimedia HLS player\n(v1)" as E3A + component "Multi-stream grid" as E3B + component "Bbox overlay\n(QQuickItem + QSGGeometryNode)" as E3C + component "Clip player (evidence)" as E3D + component "WebRTC via GStreamer\n(v2)" as E3E +} + +package "E4 — Config Forms" as E4 #LightPink { + component "Schema-driven QML forms\n(from openapi.v1.json)" as E4A + component "Camera + ONVIF discovery flow" as E4B + component "Camera calibration UI\n(ROI / zones / homography)" as E4C + component "Model + plugin +\ntrigger forms" as E4D +} + +package "E5 — Dashboard / Eventview" as E5 #LightCoral { + component "Target dashboard\ncards + charts" as E5A + component "Event timeline\n(virtualized)" as E5B + component "SSE subscriber + LiveBuffer" as E5C + component "Filter / search /\nevidence viewer" as E5D + component "Multi-target monitoring" as E5E +} + +package "E6 — UX / Cross-platform QA" as E6 #Lavender { + component "Design polish,\na11y, i18n" as E6A + component "Install / upgrade testing\nWin + Mac + Linux" as E6B + component "Crash reporting\n(Sentry / Crashpad)" as E6C + component "QML Profiler perf passes" as E6D + component "User docs surface" as E6E +} + +artifact "openapi.v1.json\n(frozen contract)" as CONTRACT + +E1 ..> CONTRACT +E2 ..> CONTRACT +E3 ..> CONTRACT +E4 ..> CONTRACT +E5 ..> CONTRACT + +note bottom of E1 + Week 1–2: E1 alone delivers the shell that unblocks E2–E6. +end note + +note bottom of E2 + Week 1–2 spike in parallel — de-risks the hardest UI feature. +end note + +@enduml diff --git a/docs/diagrams/12-dependency-chain.puml b/docs/diagrams/12-dependency-chain.puml new file mode 100644 index 0000000..fa11268 --- /dev/null +++ b/docs/diagrams/12-dependency-chain.puml @@ -0,0 +1,43 @@ +@startuml 12-dependency-chain +title Dependency chain — what gates what + +skinparam componentStyle rectangle + +artifact "openapi.v1.json\n(frozen)" as CONTRACT +component "Prism mock server" as MOCK +component "ANSVIS /api/v1 adapter\n(core team, per-resource)" as ADAPT +component "Legacy ANSVIS" as LEGACY +component "L3 shell + REST client\n(E1)" as UI_SHELL +component "L3 screens\n(E2 – E6)" as UI_FEAT +component "Real backend integration" as REAL +component "Ship v1" as SHIP + +CONTRACT --> MOCK +CONTRACT --> ADAPT +ADAPT --> LEGACY +MOCK --> UI_SHELL +UI_SHELL --> UI_FEAT +UI_FEAT --> REAL +ADAPT --> REAL +REAL --> SHIP + +note bottom of CONTRACT + Only artifact that BOTH sides block on. + Frozen once published; additive changes only. +end note + +note bottom of MOCK + UI develops here from day 1. +end note + +note bottom of ADAPT + Built in parallel by the core team. + Per-resource modularity = independent progress. +end note + +note bottom of REAL + Joining point. UI tests run against both mock and real + to detect drift. +end note + +@enduml diff --git a/docs/diagrams/PREVIEW.md b/docs/diagrams/PREVIEW.md new file mode 100644 index 0000000..9a2b7cb --- /dev/null +++ b/docs/diagrams/PREVIEW.md @@ -0,0 +1,19 @@ +# ANSCORE — L2 & L3 diagrams (preview) + +Click each PNG link to view the rendered diagram in your browser. +SVG links are higher-quality (vector). Both come from plantuml.com. + +| # | Diagram | What it shows | PNG | SVG | +|---|---|---|---|---| +| 01 | **system context** | L1 / L2 / L3 with the 3 transports (REST / SSE / HLS-RTSP-WebRTC). | [PNG](https://www.plantuml.com/plantuml/png/RLJRRjf047ttLupo51HH2dchgYe6h43bD8alYIhnihO7ic6zw-wkQL1LgH_HB-oNT7ODWf2y6E_ud3ENiyELiKpRjXRmSTWtMsEnxfTAMdonWULM88JVqibj4i6_FtyXzG2OT00uZuSmW7Za7fUz831hBXkcMGsbgXibKThKRab3OscPN0ayWZIiNBCLdWA2NHpEOhP53PS-yRqTtD_4C4Mpjgg1VBwGvuzSLkgdeUGrAszJLmINxKll39YXUk1N08Swu6mdmPf6y99PhgG7vlFWzvka8v-KEd-Ofp2vIJl9qQdaW3Lyi1akP1Ab6PXMBrc97XlUpH-6hy4nhbYvtOkMIYFreB4rM16ZpyskyEWwd7n_JRt1YZEQaM3RXPp5hjKaI-_evn6B99juOXB5uGalJIF03RqkPA4Lgqf6zccFfa-pV4pmYbbMC4EjHmu9q_52Na0fU0EgU2PRm5YgjIDbT168ywF5bWYXsSeIdbNH1Jpaw-quVLr4sDedk81a77PrXdasUsVam_t8_MMBAlgIjDBoses9fA0X4DtL5ThTe8QdTanOZPfHhhbSeaPPecibqtorGcqyAPfUHovvFeT-_qjd4to2ys4Fl8S3c6NPNRgGRWUq4YGsIVBf7jzDpH56FNSuu0NVO3ThAfABFS6Rul2NFNZ7k1rlmojKGT1Lu-joCpeSTtVY4F1JFXmxNphKKS0_Z-eEkce-kuWVn8vn20HIMOH2MQjgK4lQ8femhPAIOajzYRK1gzmYEAyajQkXucvttMS5IAwP3m7A2fpGMxaHoOL2W7tIYBHwO3MJfb7Q6c2Qe5gjoRaA2j9xmiuJwlCJyTmvJs9on198mb9fyDEh_NOmIkeWpfKb5tJF7O9utfHENXNaZIJv3H6yTic4C8JNnXxNVKMlz9yO_0S0) | [SVG](https://www.plantuml.com/plantuml/svg/RLJRRjf047ttLupo51HH2dchgYe6h43bD8alYIhnihO7ic6zw-wkQL1LgH_HB-oNT7ODWf2y6E_ud3ENiyELiKpRjXRmSTWtMsEnxfTAMdonWULM88JVqibj4i6_FtyXzG2OT00uZuSmW7Za7fUz831hBXkcMGsbgXibKThKRab3OscPN0ayWZIiNBCLdWA2NHpEOhP53PS-yRqTtD_4C4Mpjgg1VBwGvuzSLkgdeUGrAszJLmINxKll39YXUk1N08Swu6mdmPf6y99PhgG7vlFWzvka8v-KEd-Ofp2vIJl9qQdaW3Lyi1akP1Ab6PXMBrc97XlUpH-6hy4nhbYvtOkMIYFreB4rM16ZpyskyEWwd7n_JRt1YZEQaM3RXPp5hjKaI-_evn6B99juOXB5uGalJIF03RqkPA4Lgqf6zccFfa-pV4pmYbbMC4EjHmu9q_52Na0fU0EgU2PRm5YgjIDbT168ywF5bWYXsSeIdbNH1Jpaw-quVLr4sDedk81a77PrXdasUsVam_t8_MMBAlgIjDBoses9fA0X4DtL5ThTe8QdTanOZPfHhhbSeaPPecibqtorGcqyAPfUHovvFeT-_qjd4to2ys4Fl8S3c6NPNRgGRWUq4YGsIVBf7jzDpH56FNSuu0NVO3ThAfABFS6Rul2NFNZ7k1rlmojKGT1Lu-joCpeSTtVY4F1JFXmxNphKKS0_Z-eEkce-kuWVn8vn20HIMOH2MQjgK4lQ8femhPAIOajzYRK1gzmYEAyajQkXucvttMS5IAwP3m7A2fpGMxaHoOL2W7tIYBHwO3MJfb7Q6c2Qe5gjoRaA2j9xmiuJwlCJyTmvJs9on198mb9fyDEh_NOmIkeWpfKb5tJF7O9utfHENXNaZIJv3H6yTic4C8JNnXxNVKMlz9yO_0S0) | +| 02 | **l2 internals** | L2 adapter modules in front of legacy ANSVIS + infrastructure. | [PNG](https://www.plantuml.com/plantuml/png/TLPVRzis47_NfpZagSFcfaaVEWp3KDcM7NLoR4jAkW0535ewosmaIYEf34PHO1zYdt2VP4TIScmPUp6fkzyTx-yl-QWqaxgjIdXtEoflHrneb8ALojDSbmWHEw24M_Ztxt_0lqyUmmHw232PxRd6JBSIFKyzSz4moIh8wggf1GgTw0Eva8HWeYZn1DAmx9aLE0HuBDErXAkrXcjOBo9u2A-0ALYdlUQzp4VaGX--21D78PdcjL0M5VoHUbxd6QwYMxXc3Rz-kG7LoXtBq86cys3ZhqBuvi5hf70L1qaAicufDukBbmzf49zZ_5RleU9vNk9VJE8NyMQCTCeVh8N_aDujFW-yufyjAWqlhEIv3PMCbWqA4u7AzbWnvQmV_IYSdXi7KbBA5MiQb6GMpoRmuUTt7nm-Y0V1nKmZbBpYnmpyD3Y794a0MrcpF6DAMv_aUQJQhSeaRqnqiEEbxXCY-Dt3sFj-KbGgff-pXY1kCZeN4bNToWoXglEsn2ubV-glg8R3IcUiGibSooR-OkCFqYOVM3hrOZczK6DUe3ffvK2TOrFMXuhkeuBQsJZeT7u1P7oacNfs-jHFVhzywOMExgd72-tELNaMNtek6wVpezMbLjIQxtXsChVtopISNU3KWNfKkKOy9HVgh_NMMNzQZetoj4iH5YmxzFkgKBxOJabi5UPaC-9TXw9Wxa-UXWsQr6B72r2qSDZ3DfFPVB0C8PZw0Og2YrUSgMHoZfp5Gz1ik5XKg276oCwo2iMEnaRBrXAEnONtizWVXc-tz4VGzJEAaoJCUcwInmc1QITRSlYfthehrKPbJAYVeANXOJbTt1XP2UrjFz5KwsIp9WyaOrkco4bWXWGgrCp8O3hkvYMuJvFDT7o6dPIy8MBZbScdtdubtdC1KW39Uz8ik0YNTCuIzzua2bU3OaPreIWxUb3opDpso4gzTsLRpWVe1UQS4S6MZ0ZpBah8TvmcApe-upPE9uueWiX_CgNkE3Qw0RDar5vPe7xJvHxSUDuwXT7ejvuRYMzFFzrX9HqLkiDA7BtPNsTZoCdyEBnZ2gzd32Cp1DT_lttRlmA_K3QAqbFqr-B4_x6xdgCKA-pdrj78_ubSaJioEGDPrZXAt6HtJ36GMdvmOHyx_ofpBrYcEDhH2dJqS1JPYNUxxcIcdMwzxNStVLs2fYPEGZKnuqjDRMIznJwtCq1fUjcDj-ST0xy8kRjPUSV_xZZjjDVnng_M-iQp0tJyyZwYoEa_2ky_) | [SVG](https://www.plantuml.com/plantuml/svg/TLPVRzis47_NfpZagSFcfaaVEWp3KDcM7NLoR4jAkW0535ewosmaIYEf34PHO1zYdt2VP4TIScmPUp6fkzyTx-yl-QWqaxgjIdXtEoflHrneb8ALojDSbmWHEw24M_Ztxt_0lqyUmmHw232PxRd6JBSIFKyzSz4moIh8wggf1GgTw0Eva8HWeYZn1DAmx9aLE0HuBDErXAkrXcjOBo9u2A-0ALYdlUQzp4VaGX--21D78PdcjL0M5VoHUbxd6QwYMxXc3Rz-kG7LoXtBq86cys3ZhqBuvi5hf70L1qaAicufDukBbmzf49zZ_5RleU9vNk9VJE8NyMQCTCeVh8N_aDujFW-yufyjAWqlhEIv3PMCbWqA4u7AzbWnvQmV_IYSdXi7KbBA5MiQb6GMpoRmuUTt7nm-Y0V1nKmZbBpYnmpyD3Y794a0MrcpF6DAMv_aUQJQhSeaRqnqiEEbxXCY-Dt3sFj-KbGgff-pXY1kCZeN4bNToWoXglEsn2ubV-glg8R3IcUiGibSooR-OkCFqYOVM3hrOZczK6DUe3ffvK2TOrFMXuhkeuBQsJZeT7u1P7oacNfs-jHFVhzywOMExgd72-tELNaMNtek6wVpezMbLjIQxtXsChVtopISNU3KWNfKkKOy9HVgh_NMMNzQZetoj4iH5YmxzFkgKBxOJabi5UPaC-9TXw9Wxa-UXWsQr6B72r2qSDZ3DfFPVB0C8PZw0Og2YrUSgMHoZfp5Gz1ik5XKg276oCwo2iMEnaRBrXAEnONtizWVXc-tz4VGzJEAaoJCUcwInmc1QITRSlYfthehrKPbJAYVeANXOJbTt1XP2UrjFz5KwsIp9WyaOrkco4bWXWGgrCp8O3hkvYMuJvFDT7o6dPIy8MBZbScdtdubtdC1KW39Uz8ik0YNTCuIzzua2bU3OaPreIWxUb3opDpso4gzTsLRpWVe1UQS4S6MZ0ZpBah8TvmcApe-upPE9uueWiX_CgNkE3Qw0RDar5vPe7xJvHxSUDuwXT7ejvuRYMzFFzrX9HqLkiDA7BtPNsTZoCdyEBnZ2gzd32Cp1DT_lttRlmA_K3QAqbFqr-B4_x6xdgCKA-pdrj78_ubSaJioEGDPrZXAt6HtJ36GMdvmOHyx_ofpBrYcEDhH2dJqS1JPYNUxxcIcdMwzxNStVLs2fYPEGZKnuqjDRMIznJwtCq1fUjcDj-ST0xy8kRjPUSV_xZZjjDVnng_M-iQp0tJyyZwYoEa_2ky_) | +| 03 | **l2 ownership** | Human-owned vs AI-coder-built vs reused legacy modules in L2. | [PNG](https://www.plantuml.com/plantuml/png/PLNRRXCn47tVhnYL5r2xj0tG5XvGjo5f8qAfkWM15AborfEDYTTUR6_32Y7nn1Vq2_aIPYzfO_CKQtNE-FZCcScfTSougf1my2AMWrYl5Hgx56NaX9C8KrQZWG7y_NqFPvMG71uHaLq9LJB32iXqKMg5ogMk9fR1p36LIzo2b2nRiHn3GDH_XvsBgc2g5S1dwYapsL8uWZtR0MRXujE7v1AUJ4M-T5zHIhs6dn4ytWixrwFq1eok79gPsWLMkIKKWdE9QsQmAt8OKCP3E3uvE9xHYumsKB2oHDD11pxqOuagkPh07PE2CoUqcgbIb2Y5wck_y0b9S_-2T3PYd5wX0klqHiZBGCXPCcnm5hFA25UJFtS2rntsbO-TKZF-tCFq45ob5CgM9t8bLDxXZw9VMwucapZJ74qyf-uvChRGl9BC0EEi9AzivsyowSqzanM6rcQiG4EWdj8H0Y-fBCe7I2EgAgLc73oNai1Mv3a6TGCVELAPkg1pd5DtIpjJ7ZnmaedOCRiAQWOMuXtzU5hJT0HpGt8pPXzOHpvhOVoYny7DiWm09pv0QISM8cl34-XxxIDjJI8As8SbCaansfyfgVFG_mEVz4tFuNk5rBrTM6kpejRsmB1Jo0MZX4bMzu21bvZH3s4TfGcIo_Jp9AN86AmiSiB6ee_BwCk4fgrBpBbXTPYO6-e1eCetVP_UtYJf-zG7ZQzzoFWw6A7fLO1ellYOeLOBaM-DrlHsE3vltjDjZ3X-IzcEADxDgPKTHTG9XBbsJXUW5zrkeRBlQ2CXPSp2N50yt1A1tcrWXLXQg1HD4N3HhAv-FjyGoI2PRjtMOjY3TflOlNO7xK5cjBLnLhdMrCs8FuzGSMYK_AU7z09SaBMoXisqpfkTO7LbCcntCJse7MiB6LDjlq4eQ3Qjb2Y9hnLzeE6XMngZDjCEQ-6Mj2I9BKamATeMSaf7-Y-8_W40) | [SVG](https://www.plantuml.com/plantuml/svg/PLNRRXCn47tVhnYL5r2xj0tG5XvGjo5f8qAfkWM15AborfEDYTTUR6_32Y7nn1Vq2_aIPYzfO_CKQtNE-FZCcScfTSougf1my2AMWrYl5Hgx56NaX9C8KrQZWG7y_NqFPvMG71uHaLq9LJB32iXqKMg5ogMk9fR1p36LIzo2b2nRiHn3GDH_XvsBgc2g5S1dwYapsL8uWZtR0MRXujE7v1AUJ4M-T5zHIhs6dn4ytWixrwFq1eok79gPsWLMkIKKWdE9QsQmAt8OKCP3E3uvE9xHYumsKB2oHDD11pxqOuagkPh07PE2CoUqcgbIb2Y5wck_y0b9S_-2T3PYd5wX0klqHiZBGCXPCcnm5hFA25UJFtS2rntsbO-TKZF-tCFq45ob5CgM9t8bLDxXZw9VMwucapZJ74qyf-uvChRGl9BC0EEi9AzivsyowSqzanM6rcQiG4EWdj8H0Y-fBCe7I2EgAgLc73oNai1Mv3a6TGCVELAPkg1pd5DtIpjJ7ZnmaedOCRiAQWOMuXtzU5hJT0HpGt8pPXzOHpvhOVoYny7DiWm09pv0QISM8cl34-XxxIDjJI8As8SbCaansfyfgVFG_mEVz4tFuNk5rBrTM6kpejRsmB1Jo0MZX4bMzu21bvZH3s4TfGcIo_Jp9AN86AmiSiB6ee_BwCk4fgrBpBbXTPYO6-e1eCetVP_UtYJf-zG7ZQzzoFWw6A7fLO1ellYOeLOBaM-DrlHsE3vltjDjZ3X-IzcEADxDgPKTHTG9XBbsJXUW5zrkeRBlQ2CXPSp2N50yt1A1tcrWXLXQg1HD4N3HhAv-FjyGoI2PRjtMOjY3TflOlNO7xK5cjBLnLhdMrCs8FuzGSMYK_AU7z09SaBMoXisqpfkTO7LbCcntCJse7MiB6LDjlq4eQ3Qjb2Y9hnLzeE6XMngZDjCEQ-6Mj2I9BKamATeMSaf7-Y-8_W40) | +| 04 | **l3 internals** | Qt/QML layers: app shell, network, domain state, screens. | [PNG](https://www.plantuml.com/plantuml/png/RPRTQkD65CVlzHI7NAM4n0rRoXBAieebEsBbBqasB0J2M3gHPosDr9cHiwOKUjK7A7t2VPAU6IcXzYGtiSU_cVFrdx_qMMacTLTNyFClrzM7QouqIi4gvMckAuIO7L721_Znrx-mql0hZ60rY-4L0oRp7TUOwqwYvwaz5osJh8QygTj6eD2fFj8naWWcoWh_XxGitxCIpm5lM8SB6-_AnZFXXrGkW2bOPV27vm6yiNxRGhh3gh8_fmzX71C1zFUM2LpC61VmmaNHl5XivaVpSsRE3hnacZS2PDDHbPPC5kiiF4S3LBmKe8vAOqsDqJkiqUBPGpXpS7xxKS3bxogJnCPSb1rN-YVBHxSVdKJyJk-0fgEHUg2RFL8atSW-WB_E7fxIx7nFA6KZ2MPAKuo2iwefBHycoTCw8lpFawxDKRyqSW-LQQq5vs7czcsA0YKbKa0IfXda5QVbHt7Pj2XOosyEjpVV53Ninz__mFZgQhGQoZBq-Lbf6eBgjYgNV8kI3baDIIJOLaV8TvtOOz7l9_Pf73jJH2hiBOcLddMLvhLT7C4qrH9PFLGp2uF8Fzz_lss-GtD0ILMJxaI1qYQITzJV6bQhZkVxY4RQ9x7OX4diVtMoC559o9gcqqgh12mUHTTM3Ik6yEjblF03f-j1KniXzhEzN2sstqZyT8mvWsxUK7lcPw4xYh6fZQbPK-0WzUnfxC-SxCplfzHi4JXoAKeyXS9W-exCgQPZJP-dT2FQqmt1rD5jb36rFwKoF_tY13_GlnwZscD-mFlk-Nded4bbSxvZaYnHaivEpvuaJWRnCbbMrDnJq2oVemdclELlYRoYyqKMJHpbsdl-WApIknCw_PewCqvpYIWKZNSM3mCT9s4uJzsHnat9XKNYnTGrf82ftRPXie3Heo2pBb4hAzy3nzx60ZzzU5ydK3D1wTJsfbp1Ohw99cGBAZVxZsOfPnNVIkjtzYpIqbDwVjYIjrXnWK2NZ2o8xig1guxSF_2dVN71bAGJEPVTZy28WPR4C--To4ZXNJRfAbJ6HIKlIvfpxo3hE7JpCM8nrKCfUT5tBjeukhK2ivYn1vD_RuKRzy190cqlBPBYCyknZpv9NDIe25ghhjw9wRjBzRAMM9B5osFlHOiWZ5rohIWmbSsAUb31EWqJ1qjHQtfaz37JCCkY-RHN7UcEvJGLIcsURg8KHcJ9eyEj9U_zyPTm7dZUg_gkhpyDrd97wR72XAuxuqJAwzSDOPu2TqORz1vWFlzc5b_F6WmHRcu-zGPBg3gAd9uxiCnIRtWssT_jy-AENXUCnL4woCXhJuZUurt6-qpEJEybtdy0) | [SVG](https://www.plantuml.com/plantuml/svg/RPRTQkD65CVlzHI7NAM4n0rRoXBAieebEsBbBqasB0J2M3gHPosDr9cHiwOKUjK7A7t2VPAU6IcXzYGtiSU_cVFrdx_qMMacTLTNyFClrzM7QouqIi4gvMckAuIO7L721_Znrx-mql0hZ60rY-4L0oRp7TUOwqwYvwaz5osJh8QygTj6eD2fFj8naWWcoWh_XxGitxCIpm5lM8SB6-_AnZFXXrGkW2bOPV27vm6yiNxRGhh3gh8_fmzX71C1zFUM2LpC61VmmaNHl5XivaVpSsRE3hnacZS2PDDHbPPC5kiiF4S3LBmKe8vAOqsDqJkiqUBPGpXpS7xxKS3bxogJnCPSb1rN-YVBHxSVdKJyJk-0fgEHUg2RFL8atSW-WB_E7fxIx7nFA6KZ2MPAKuo2iwefBHycoTCw8lpFawxDKRyqSW-LQQq5vs7czcsA0YKbKa0IfXda5QVbHt7Pj2XOosyEjpVV53Ninz__mFZgQhGQoZBq-Lbf6eBgjYgNV8kI3baDIIJOLaV8TvtOOz7l9_Pf73jJH2hiBOcLddMLvhLT7C4qrH9PFLGp2uF8Fzz_lss-GtD0ILMJxaI1qYQITzJV6bQhZkVxY4RQ9x7OX4diVtMoC559o9gcqqgh12mUHTTM3Ik6yEjblF03f-j1KniXzhEzN2sstqZyT8mvWsxUK7lcPw4xYh6fZQbPK-0WzUnfxC-SxCplfzHi4JXoAKeyXS9W-exCgQPZJP-dT2FQqmt1rD5jb36rFwKoF_tY13_GlnwZscD-mFlk-Nded4bbSxvZaYnHaivEpvuaJWRnCbbMrDnJq2oVemdclELlYRoYyqKMJHpbsdl-WApIknCw_PewCqvpYIWKZNSM3mCT9s4uJzsHnat9XKNYnTGrf82ftRPXie3Heo2pBb4hAzy3nzx60ZzzU5ydK3D1wTJsfbp1Ohw99cGBAZVxZsOfPnNVIkjtzYpIqbDwVjYIjrXnWK2NZ2o8xig1guxSF_2dVN71bAGJEPVTZy28WPR4C--To4ZXNJRfAbJ6HIKlIvfpxo3hE7JpCM8nrKCfUT5tBjeukhK2ivYn1vD_RuKRzy190cqlBPBYCyknZpv9NDIe25ghhjw9wRjBzRAMM9B5osFlHOiWZ5rohIWmbSsAUb31EWqJ1qjHQtfaz37JCCkY-RHN7UcEvJGLIcsURg8KHcJ9eyEj9U_zyPTm7dZUg_gkhpyDrd97wR72XAuxuqJAwzSDOPu2TqORz1vWFlzc5b_F6WmHRcu-zGPBg3gAd9uxiCnIRtWssT_jy-AENXUCnL4woCXhJuZUurt6-qpEJEybtdy0) | +| 05 | **seq configure deploy** | Operator workflow: add camera → AI task → deploy → start. | [PNG](https://www.plantuml.com/plantuml/png/XLJHRjem57ttLrpnr6e98QpT0rAxeWuX9bHOq-wfKkN59bWpTchVJA88QH-nBzoNz3efJ0IalUJ1vvnxp_6zper7xh1QQUXTnbw-nBar2rLKJiP2bjgk6IhK4ZBvKacJI_Zx-m_CIkauMWTxieUSh-WGFi1m0iZzJ-16G5F2CyRpGE_iX1tW7XwzTAoaxYfN9JS8dMy8ZvC6cnmYmxli-oHxCWalLV8hhJd3-KaIcNAo9an7uqF2D0KfYWOSVHcF60iU8BwcVZ08iGpSrZay-Dn9QHW115ChmiUZ1qYQdFvpoGjvbRA0485Q4K7BWkThqCeZ2oVnNlgkQkYxVlrU3pOAvSf74Cf5W1QvthPi3OM0-uTilhlYiuLrg_C3P_DPziyQCnObE5Ki4UmYN2N03olMiAHOHdgK0YYSa0OLrpuYEESbLawP8WAr8YVFNhtMeoRCMF0OCBLGfFoQpUwOfDc6BYVZSo5QwPMuIliVs-5JcDgSex9ciFUU1DvX_DlTZkqswqHohkA0-2UpQGezAp6WKX5qkztjIPTq0vm271czkFnqR7H3vGXeJoOBR-T_dX8I9lKhE_GXb2yvvil6mdMza65JwhZqZXf9VHhlHQuoXaRHTjY73T5H3ceH4SYfjhOCHR3oK5gjuOnUO9QDG1FHdTDaZtQxRPcaH3lUsQRNkvS85gKVf1VT_ZRi1MCtzAKV2di3) | [SVG](https://www.plantuml.com/plantuml/svg/XLJHRjem57ttLrpnr6e98QpT0rAxeWuX9bHOq-wfKkN59bWpTchVJA88QH-nBzoNz3efJ0IalUJ1vvnxp_6zper7xh1QQUXTnbw-nBar2rLKJiP2bjgk6IhK4ZBvKacJI_Zx-m_CIkauMWTxieUSh-WGFi1m0iZzJ-16G5F2CyRpGE_iX1tW7XwzTAoaxYfN9JS8dMy8ZvC6cnmYmxli-oHxCWalLV8hhJd3-KaIcNAo9an7uqF2D0KfYWOSVHcF60iU8BwcVZ08iGpSrZay-Dn9QHW115ChmiUZ1qYQdFvpoGjvbRA0485Q4K7BWkThqCeZ2oVnNlgkQkYxVlrU3pOAvSf74Cf5W1QvthPi3OM0-uTilhlYiuLrg_C3P_DPziyQCnObE5Ki4UmYN2N03olMiAHOHdgK0YYSa0OLrpuYEESbLawP8WAr8YVFNhtMeoRCMF0OCBLGfFoQpUwOfDc6BYVZSo5QwPMuIliVs-5JcDgSex9ciFUU1DvX_DlTZkqswqHohkA0-2UpQGezAp6WKX5qkztjIPTq0vm271czkFnqR7H3vGXeJoOBR-T_dX8I9lKhE_GXb2yvvil6mdMza65JwhZqZXf9VHhlHQuoXaRHTjY73T5H3ceH4SYfjhOCHR3oK5gjuOnUO9QDG1FHdTDaZtQxRPcaH3lUsQRNkvS85gKVf1VT_ZRi1MCtzAKV2di3) | +| 06 | **seq live events** | Eventview: SSE event tail + click into evidence (image + clip). | [PNG](https://www.plantuml.com/plantuml/png/VLJ1Rjf04BtlLumuLA1YZ5FA0HMIYBeHacb8N7gA52ts52PPR6TtJOYYI3tr2_A5-PBksawAQUd9gtblthnvk_A9qbpgV2sWstSKtZc2DkZW1XEjc2Oj44Ayop6945v-FaDWO2XWq9m4l8T8K7HBoH8eqQc1ABPandYaKmcDymmbDwS6S0LpXP9bPY15b76ZqRZGC9-KsAIEd7uDlq_2gyJb6RaRh-2SplP8OUZ3GgOyZhZIM0unjJffB2W3PJpWLT8CFu0BKqecv-Rx9MmLBUDWCWlhJO4762-nWFtFPpvZrZmu8sCK1c3MIi2tEMm8xw6fkReTzZxsMyp0XcIS6jQP_mtSCinZoxYcs9BUPNo9GuzPalEgUDJjmegiJOguWEeA3gYvIalawrtHkfh6hIwvJac5PceijnYpo_pHBA-IIsdkLK5pGnm2x-NNSt3KAWL7Daz3p7ArAXU-n2YLCRFbjt4nrtm0ZnGFVAyDMhKXNTnWf0SHbsrOBD9j6pgTpjDUYcFxTYeFldTmMVyVKUrOWUQFN8Y3oPjsbzOcyUDxYlLgsEzrwt85wDvak8J5WqQrPt8c-8DzvTd_1XHu5LZnccna4XKj4qjbPSrvQwymZ65-6VoztMCkHHjmcv7XNNFzLCr-bRRJFzKqHZiZ2fdfh5UjKxOMnSpkGWbSw6akDAqn9ixO2IQn-GMmtm00) | [SVG](https://www.plantuml.com/plantuml/svg/VLJ1Rjf04BtlLumuLA1YZ5FA0HMIYBeHacb8N7gA52ts52PPR6TtJOYYI3tr2_A5-PBksawAQUd9gtblthnvk_A9qbpgV2sWstSKtZc2DkZW1XEjc2Oj44Ayop6945v-FaDWO2XWq9m4l8T8K7HBoH8eqQc1ABPandYaKmcDymmbDwS6S0LpXP9bPY15b76ZqRZGC9-KsAIEd7uDlq_2gyJb6RaRh-2SplP8OUZ3GgOyZhZIM0unjJffB2W3PJpWLT8CFu0BKqecv-Rx9MmLBUDWCWlhJO4762-nWFtFPpvZrZmu8sCK1c3MIi2tEMm8xw6fkReTzZxsMyp0XcIS6jQP_mtSCinZoxYcs9BUPNo9GuzPalEgUDJjmegiJOguWEeA3gYvIalawrtHkfh6hIwvJac5PceijnYpo_pHBA-IIsdkLK5pGnm2x-NNSt3KAWL7Daz3p7ArAXU-n2YLCRFbjt4nrtm0ZnGFVAyDMhKXNTnWf0SHbsrOBD9j6pgTpjDUYcFxTYeFldTmMVyVKUrOWUQFN8Y3oPjsbzOcyUDxYlLgsEzrwt85wDvak8J5WqQrPt8c-8DzvTd_1XHu5LZnccna4XKj4qjbPSrvQwymZ65-6VoztMCkHHjmcv7XNNFzLCr-bRRJFzKqHZiZ2fdfh5UjKxOMnSpkGWbSw6akDAqn9ixO2IQn-GMmtm00) | +| 07 | **seq liveview** | Liveview: HLS player + bbox overlay synced to PTS. | [PNG](https://www.plantuml.com/plantuml/png/PLFHQjj047o_hrZyP1CRsKdRb42Q62fIWzCwbbCe6CnPsiP7JYVbRgKub48_8b_OB-dUIMhYzaK8pUpEpExgqf6qLEKQngSZXmyZhMgi5JuAKgGH4doeqAG8ltyzmxp5u57H3hRROWz5ZLRB9o5aIeM5tfSIhUIt7aW7jmwjABc_IbKf3K7lXk1src2pGsJwEVawIzOcagMAwadWJ1V_aAunKn8iic8WBEFvzDiXPJu1pEummF77g_WGJP8OjhQGMIeTOUEIlmdXhSBe0zk2C-0GvYLiFvKvJ8vFXa3ItSERj-y6WcbCPd_ClefN4367Wxk8UL4tmWkoqhYoi7I-qqvuDXS5pro6nbKMuTCyWUyykLP4D33pl7ccbPNMi5mbYmxvgyizDvNLS0HknnfXSnbGSO-cqUhY78_7y8EP7A0pTCR5mxMH5UqseM88k2-LHRUHz5Eq-JghFc6drW_qmIitGIC_gTvx9tYNeo7NDWZG4at6mwrLXiNQz6_ekjAaSh_AWVX_abZx1f4ZYpA_y2FVgEoSfmvztjJWC1hXdfgAKLCWX2wA4lWA8NmMuFVxKX2EzWZO8S0hZ-qPWtlYM_T3XCKg4MnSY4j-ylyX_W00) | [SVG](https://www.plantuml.com/plantuml/svg/PLFHQjj047o_hrZyP1CRsKdRb42Q62fIWzCwbbCe6CnPsiP7JYVbRgKub48_8b_OB-dUIMhYzaK8pUpEpExgqf6qLEKQngSZXmyZhMgi5JuAKgGH4doeqAG8ltyzmxp5u57H3hRROWz5ZLRB9o5aIeM5tfSIhUIt7aW7jmwjABc_IbKf3K7lXk1src2pGsJwEVawIzOcagMAwadWJ1V_aAunKn8iic8WBEFvzDiXPJu1pEummF77g_WGJP8OjhQGMIeTOUEIlmdXhSBe0zk2C-0GvYLiFvKvJ8vFXa3ItSERj-y6WcbCPd_ClefN4367Wxk8UL4tmWkoqhYoi7I-qqvuDXS5pro6nbKMuTCyWUyykLP4D33pl7ccbPNMi5mbYmxvgyizDvNLS0HknnfXSnbGSO-cqUhY78_7y8EP7A0pTCR5mxMH5UqseM88k2-LHRUHz5Eq-JghFc6drW_qmIitGIC_gTvx9tYNeo7NDWZG4at6mwrLXiNQz6_ekjAaSh_AWVX_abZx1f4ZYpA_y2FVgEoSfmvztjJWC1hXdfgAKLCWX2wA4lWA8NmMuFVxKX2EzWZO8S0hZ-qPWtlYM_T3XCKg4MnSY4j-ylyX_W00) | +| 08 | **seq async scan** | ONVIF camera scan via async job queue (poll /jobs/{id}). | [PNG](https://www.plantuml.com/plantuml/png/TPBTJjj048Nlvob6kMeb_1UXYbe24Qgs2XS9oC0DL6XP3sZ3PcnsrrHL58c7u0dx98pNuLVYRktlUCuvuzttGRdGBItcEucdkqJvVwmJhnL3CC4ILdJN4Ml2_m-FEEafQhKafv0f_6tSBVPY_B9ehh1L8P3Zhm1AXyRXQDwAK4uZL1vFFJbenSveqoeEE3eEU3eTsFGzcSogisbrmPbgJNPVHCtaw8FeK2mbN4SH7yuFglTyFZkR_ehnc8O8rO_93A0FWicUc6A9LP---3vEYsyxQP7csNWR10WMF-57y-e4iw6op-9YUY2yDnG1SSm0yJ5v-KxsSMdgtKKno9_jnlaOLmCh5yNM1QFyWT3vCWwf-nVMyAqlLvxiTPc9r6UBOhs6ZS5UB26JNCS0jcbQR1jhiUDWBChwbuQL1SIt9Nx_b0wRKO8-9CfnjGaXCzdmpHQshhbnv7sPfzjh8Au1ectosbjmPuE7Jtq-TV6TraJrq7OOKwvgutLpJuxgyZnDqpzzutqnbhi9Jm00) | [SVG](https://www.plantuml.com/plantuml/svg/TPBTJjj048Nlvob6kMeb_1UXYbe24Qgs2XS9oC0DL6XP3sZ3PcnsrrHL58c7u0dx98pNuLVYRktlUCuvuzttGRdGBItcEucdkqJvVwmJhnL3CC4ILdJN4Ml2_m-FEEafQhKafv0f_6tSBVPY_B9ehh1L8P3Zhm1AXyRXQDwAK4uZL1vFFJbenSveqoeEE3eEU3eTsFGzcSogisbrmPbgJNPVHCtaw8FeK2mbN4SH7yuFglTyFZkR_ehnc8O8rO_93A0FWicUc6A9LP---3vEYsyxQP7csNWR10WMF-57y-e4iw6op-9YUY2yDnG1SSm0yJ5v-KxsSMdgtKKno9_jnlaOLmCh5yNM1QFyWT3vCWwf-nVMyAqlLvxiTPc9r6UBOhs6ZS5UB26JNCS0jcbQR1jhiUDWBChwbuQL1SIt9Nx_b0wRKO8-9CfnjGaXCzdmpHQshhbnv7sPfzjh8Au1ectosbjmPuE7Jtq-TV6TraJrq7OOKwvgutLpJuxgyZnDqpzzutqnbhi9Jm00) | +| 09 | **seq large upload** | Large model upload: initiate → presigned PUT → complete. | [PNG](https://www.plantuml.com/plantuml/png/TPB1Jjj048Rl-nIZd1B9RWA80wX2mA5I2i519Zr5YYRs4AQnrylkc3OW91wYJzWdwJXEqYPIJxlQ-NU-V_xToo3efIuB69p5WPxZ0ls2ujeL5UP6M0g2b9vhiXd1xuzVSDlKeQnoAg1LGPSj2wCGz26hIbUGRXsAaBSzOp2JoaCdSUHHTnt009D0tZWbSyOEhK3dNc0oR6l3_ShLNVfjc4vj7nttNuxMcglnWIYPVwTC82Y0fhQRdgYN4TjXekkNjBU-b5n_DQOXGtoX53Y7CMVBTfPFh-oWUpeOmEYwPxIe4eKqcYHzWFvQ5Cwtasu2cjgtHox8OaaH17wbsNmb52B8dYXRXhfyDqqJxQLixUKy1LvO64yUJ7CIxoYR2kMpsXVjfQt9OpNrrl9cd4VxqWZefsCzcQ6ycutn5gOG-Bmdlj1avcpHhpGeJrX6y8FbIJjM2zM5tixK3fpScF-diNtilsdyOxCamHm53o9u8S-Fgrr01p5KoyFPZs3Km8ov99lhFpL_0000) | [SVG](https://www.plantuml.com/plantuml/svg/TPB1Jjj048Rl-nIZd1B9RWA80wX2mA5I2i519Zr5YYRs4AQnrylkc3OW91wYJzWdwJXEqYPIJxlQ-NU-V_xToo3efIuB69p5WPxZ0ls2ujeL5UP6M0g2b9vhiXd1xuzVSDlKeQnoAg1LGPSj2wCGz26hIbUGRXsAaBSzOp2JoaCdSUHHTnt009D0tZWbSyOEhK3dNc0oR6l3_ShLNVfjc4vj7nttNuxMcglnWIYPVwTC82Y0fhQRdgYN4TjXekkNjBU-b5n_DQOXGtoX53Y7CMVBTfPFh-oWUpeOmEYwPxIe4eKqcYHzWFvQ5Cwtasu2cjgtHox8OaaH17wbsNmb52B8dYXRXhfyDqqJxQLixUKy1LvO64yUJ7CIxoYR2kMpsXVjfQt9OpNrrl9cd4VxqWZefsCzcQ6ycutn5gOG-Bmdlj1avcpHhpGeJrX6y8FbIJjM2zM5tixK3fpScF-diNtilsdyOxCamHm53o9u8S-Fgrr01p5KoyFPZs3Km8ov99lhFpL_0000) | +| 10 | **deployment topology** | Workstations / ANSVIS server / edges + ports + customer network. | [PNG](https://www.plantuml.com/plantuml/png/RLJ1Rjf04BtxAqQSY2hKWgEgYgeg4Bkj8m8qfaahSLdiYREDlMljhXEig59F_O0gNvWlwQmtW25mC3kUDxCpR-RvL1kcJ5Naq7_NIx7CPLsWC3qZIvdBhFOCDpb2iF70VEtnz1qN9LEiW4GMfHJaZKrDQ8M9OIBBqVE4J14wPvKsia05cXk4jv3aiaexyEXv00unBL4n8nKyI7L7DHakXRO8eDycFNIkkKZbWuOKzHtLk13V37oFEi0q1FrzSC6IQNmGEjY7ZhceLWUXFa5_RmiTJkAhA0QDwfxwkPNQ7AZo4icf4KebL_L2pCSn65G55xR5XUYAZ8kLvO6bQNtKt3Fv4ar-xETvkOoLL5ANfQoaBF06SinOKXDGeGiUpcRxeHUOSaQJo5dTG2x3yV1d0qgPOKkcBUdBNpGfeDaef0jYdqgwu2AQql_dsAMUZixteiwakE4PbH7Usvk2aNP4ZNQ92jCCWPOhGxCPfFCuhbSVtbEEoLKKHCCcGTXlOTPpVeqQj53db5iAc2ekdDCDYwe8-j3hVNAimWdO2HmV-mjn6SPpIXZ78Js_ZcCl61m2Ue5_yBMphSTIlhKSk_IkiOYAzT7IrpZXepMfnxOrsB7y9cgDsvu7hRDl9KKQMaf3Yg9k9sYiP41LEMgu8GMPMuJaHN0dbgmUJ2kpb9L8ONusitt0ZP8584jkstg3vx__u6Nbx6Axs4ZiXXBk5MOyeDWd6FVjnXkPo1n8pu1s1RgbL8R8DfKGcCDy51oveEkMqa5OnT2wsf9i62cSsyz8NiFpdoTeRNCZAexQGohASk5vftIaJvZt7m00) | [SVG](https://www.plantuml.com/plantuml/svg/RLJ1Rjf04BtxAqQSY2hKWgEgYgeg4Bkj8m8qfaahSLdiYREDlMljhXEig59F_O0gNvWlwQmtW25mC3kUDxCpR-RvL1kcJ5Naq7_NIx7CPLsWC3qZIvdBhFOCDpb2iF70VEtnz1qN9LEiW4GMfHJaZKrDQ8M9OIBBqVE4J14wPvKsia05cXk4jv3aiaexyEXv00unBL4n8nKyI7L7DHakXRO8eDycFNIkkKZbWuOKzHtLk13V37oFEi0q1FrzSC6IQNmGEjY7ZhceLWUXFa5_RmiTJkAhA0QDwfxwkPNQ7AZo4icf4KebL_L2pCSn65G55xR5XUYAZ8kLvO6bQNtKt3Fv4ar-xETvkOoLL5ANfQoaBF06SinOKXDGeGiUpcRxeHUOSaQJo5dTG2x3yV1d0qgPOKkcBUdBNpGfeDaef0jYdqgwu2AQql_dsAMUZixteiwakE4PbH7Usvk2aNP4ZNQ92jCCWPOhGxCPfFCuhbSVtbEEoLKKHCCcGTXlOTPpVeqQj53db5iAc2ekdDCDYwe8-j3hVNAimWdO2HmV-mjn6SPpIXZ78Js_ZcCl61m2Ue5_yBMphSTIlhKSk_IkiOYAzT7IrpZXepMfnxOrsB7y9cgDsvu7hRDl9KKQMaf3Yg9k9sYiP41LEMgu8GMPMuJaHN0dbgmUJ2kpb9L8ONusitt0ZP8584jkstg3vx__u6Nbx6Axs4ZiXXBk5MOyeDWd6FVjnXkPo1n8pu1s1RgbL8R8DfKGcCDy51oveEkMqa5OnT2wsf9i62cSsyz8NiFpdoTeRNCZAexQGohASk5vftIaJvZt7m00) | +| 11 | **l3 engineer ownership** | L3 engineers 1–6 and the components each owns. | [PNG](https://www.plantuml.com/plantuml/png/RLRRRYet57tdAxRIbnmb194BglfG7K88HI8NGYwjn8kPsGmkWpsoFIJagDBvX_OBpvTqUSOamISl8VQiVLlxvg_M2UFALKxjTZC_QRBAf68sJVsisDY5B1fEkfnf93Piw8H-VF-F-W54Ro3Qxz1Mr7vfDEnIga8OiQ94hmgjMBc9sq2DuSG9bUNy0LA8P2aoZW6DS4zx_NPbzc588nOfjMYou3odhaaMqW6_Hy8IGB-CPBPmV-6RVgPl3NetJdjZHnqweDwLM3AjjDA62nq4kxlG0ICguJYbk_xadf9SudggvaQlI1UiH26FrksZlwrMGS7vhe9kwHO4OXt3ejDBLZZ1O43tTj4NR6K6nCOwNY4uj-3L5dgn2xqMQva99xKYeql79i3wkx3RYZYfCdgIgdKbajP8gl9bghmXN1-IqaYxVEN3gHAbqysoIE5jq7Qvgwqtf9LmHhw4puF6FnzpSrpbvbOMd2Fzr4ybGgL9mOaKkRGXESSXEUTvoN5g7gKjHKuNtG5n9JrL--E14SL29lPHyZD9HUDnAPFbaqmpTb-2pYXlrpfbokNC2BEXWwbAj5Ae3i_M6gwa5N51DChO907fefaQkKQojcMfEBS17-NiGQKQgJASQb1enPfnMgFstorSxD9KTyu8-jS-eXPT8LPHOqy2EGF3iFvJuLwLkPCh3wS_HXCgSj-Au6ZT3aISH4HK0ath32ECpCWqmAAWpsVwXJIyXa9FUSNmq1VX0OqdWm7h5JkpyRHk3KKqz7AqVkqFxIEmb5NoXergzubdT_SzMYEAmQHohGxYU8llxn9sMX7MqsekCxhKPXLISHh8kfLg6NErcyRnrOZcNX1cFclUOFWqOg_dFHFWuERwSNX9gRI99sb3SuoL87B-gKWYgkghAkvX2AjtDqDa-XKeYz-5NkdCb_LcQpcYymfCvp1Sv2MwrvSmsYxBGExyG_nHOPrLF5q8kvXfOVnqx2Duvwki5ZWBXFMqGPT5ZDqBWuQYT2kEhi5V2oUI1HP3i7aMKLHP85-KlkTz5YMM2A9_vJJ4TXPtsAHFjfpPnCWP0ZgeMk6ydC-tG-mi8kDIvXXm2CUomA2drbHjAunyS6zo5vyLlwlZmg3t0mKpBu2Z8klKY-LFcEaPRMqJnUmysJJkrX8Ti8VsLYby-VRfu2uqnjp2Jz9sUtD8ilrh606TYBMXmax0tcfHMQ0ECAmSMmVVfkh9fvimgIjYCAk3XhZE3F94VdEPMcv_WdkKfdSVdmgnfRyJiUbxuTRekSmHHy5cZl5cBOVyTY8E7onGgKuiKcRc8WcReLEnXxAGk0CiwgUwpLxHUPYypW1IEzExkRw_w_Rk6mtiwAEZtzyli1PspoVH-JGwd-sU6zXZJ3FjdE_kEPOJudXYNbBxn_T_Zt_pZmAH8oX2Oqa_d_rs9Liz7zn2E2hLBDV9qWziIFGxHmsasgz7_bdvyOvoieN4KqBMwoBFqRc-bb9k6ccNjI6qK8eK-vVBd8Kh3N_K_nN_ukNL-1y0) | [SVG](https://www.plantuml.com/plantuml/svg/RLRRRYet57tdAxRIbnmb194BglfG7K88HI8NGYwjn8kPsGmkWpsoFIJagDBvX_OBpvTqUSOamISl8VQiVLlxvg_M2UFALKxjTZC_QRBAf68sJVsisDY5B1fEkfnf93Piw8H-VF-F-W54Ro3Qxz1Mr7vfDEnIga8OiQ94hmgjMBc9sq2DuSG9bUNy0LA8P2aoZW6DS4zx_NPbzc588nOfjMYou3odhaaMqW6_Hy8IGB-CPBPmV-6RVgPl3NetJdjZHnqweDwLM3AjjDA62nq4kxlG0ICguJYbk_xadf9SudggvaQlI1UiH26FrksZlwrMGS7vhe9kwHO4OXt3ejDBLZZ1O43tTj4NR6K6nCOwNY4uj-3L5dgn2xqMQva99xKYeql79i3wkx3RYZYfCdgIgdKbajP8gl9bghmXN1-IqaYxVEN3gHAbqysoIE5jq7Qvgwqtf9LmHhw4puF6FnzpSrpbvbOMd2Fzr4ybGgL9mOaKkRGXESSXEUTvoN5g7gKjHKuNtG5n9JrL--E14SL29lPHyZD9HUDnAPFbaqmpTb-2pYXlrpfbokNC2BEXWwbAj5Ae3i_M6gwa5N51DChO907fefaQkKQojcMfEBS17-NiGQKQgJASQb1enPfnMgFstorSxD9KTyu8-jS-eXPT8LPHOqy2EGF3iFvJuLwLkPCh3wS_HXCgSj-Au6ZT3aISH4HK0ath32ECpCWqmAAWpsVwXJIyXa9FUSNmq1VX0OqdWm7h5JkpyRHk3KKqz7AqVkqFxIEmb5NoXergzubdT_SzMYEAmQHohGxYU8llxn9sMX7MqsekCxhKPXLISHh8kfLg6NErcyRnrOZcNX1cFclUOFWqOg_dFHFWuERwSNX9gRI99sb3SuoL87B-gKWYgkghAkvX2AjtDqDa-XKeYz-5NkdCb_LcQpcYymfCvp1Sv2MwrvSmsYxBGExyG_nHOPrLF5q8kvXfOVnqx2Duvwki5ZWBXFMqGPT5ZDqBWuQYT2kEhi5V2oUI1HP3i7aMKLHP85-KlkTz5YMM2A9_vJJ4TXPtsAHFjfpPnCWP0ZgeMk6ydC-tG-mi8kDIvXXm2CUomA2drbHjAunyS6zo5vyLlwlZmg3t0mKpBu2Z8klKY-LFcEaPRMqJnUmysJJkrX8Ti8VsLYby-VRfu2uqnjp2Jz9sUtD8ilrh606TYBMXmax0tcfHMQ0ECAmSMmVVfkh9fvimgIjYCAk3XhZE3F94VdEPMcv_WdkKfdSVdmgnfRyJiUbxuTRekSmHHy5cZl5cBOVyTY8E7onGgKuiKcRc8WcReLEnXxAGk0CiwgUwpLxHUPYypW1IEzExkRw_w_Rk6mtiwAEZtzyli1PspoVH-JGwd-sU6zXZJ3FjdE_kEPOJudXYNbBxn_T_Zt_pZmAH8oX2Oqa_d_rs9Liz7zn2E2hLBDV9qWziIFGxHmsasgz7_bdvyOvoieN4KqBMwoBFqRc-bb9k6ccNjI6qK8eK-vVBd8Kh3N_K_nN_ukNL-1y0) | +| 12 | **dependency chain** | Critical path: contract → mock → UI + adapter → integration → ship. | [PNG](https://www.plantuml.com/plantuml/png/VLFRRjD047ttLnpb2GH9bIBnWa1rKvS6GXF50Ga92MtiYRDqlMljJeB24_y0NyYNC5utQG9INxoxupDdRcSk0YlFczfWUDulgI5RaYrs_MAjj4rOio5S7So8Plpv-HlVrufHAQOGhqaIxhHjb5Sr2bStpfBbd7VYxgbWPIj3IIAXz4eLZ9uJIjNemNOu-1QS_MAVhBpxGVPf3ofWDBrTpDFH8ZbGeJVpEjIeNN67G7vBFY8_J4VlZr7fRVvfdEDCkC-sGwXIDKnUwDEnv5MI3y_HaEzx2cxZ2-hYfLVfx2JOX2ebvNPi4JB9tgQZpoUO5mXhCWRFCC_o1GgZnIwXic77-d7yDR_99fD_dGfFP4CBF9TM_aBsye2_pjAJFEQa39Qgk9C1G5kcoYlMpaRyF4jFkFErRh0Tnd_vpNYM9Fi-ejz_qxNgnDAL7R_nVLzZ2uplGm7xozuQqxm_eoscya0Kd-qdlhfSh6F2qZ6x6cxrC69WQiqE1sbmAwpBwU86GPUYhgLfH-xiG93NKIFoA0ZDPccq3A1y9LCkDUijjVAqbVWuOHmaRS_QgF_5Zfs058AIjcHS4x0cJn09rYZL3iD7dBkc0PSRRLXcWbRqnf3CIGIpLrcRxUn8PoBSScEKrxp3Q_7QhngZyQuIL7WaP6mdyCvfgss5HauUjEdBzd60trYeIXOpSEkqxfP42PiN-OWZEocKPGrHUhtYuqWNSfNjJ_u2) | [SVG](https://www.plantuml.com/plantuml/svg/VLFRRjD047ttLnpb2GH9bIBnWa1rKvS6GXF50Ga92MtiYRDqlMljJeB24_y0NyYNC5utQG9INxoxupDdRcSk0YlFczfWUDulgI5RaYrs_MAjj4rOio5S7So8Plpv-HlVrufHAQOGhqaIxhHjb5Sr2bStpfBbd7VYxgbWPIj3IIAXz4eLZ9uJIjNemNOu-1QS_MAVhBpxGVPf3ofWDBrTpDFH8ZbGeJVpEjIeNN67G7vBFY8_J4VlZr7fRVvfdEDCkC-sGwXIDKnUwDEnv5MI3y_HaEzx2cxZ2-hYfLVfx2JOX2ebvNPi4JB9tgQZpoUO5mXhCWRFCC_o1GgZnIwXic77-d7yDR_99fD_dGfFP4CBF9TM_aBsye2_pjAJFEQa39Qgk9C1G5kcoYlMpaRyF4jFkFErRh0Tnd_vpNYM9Fi-ejz_qxNgnDAL7R_nVLzZ2uplGm7xozuQqxm_eoscya0Kd-qdlhfSh6F2qZ6x6cxrC69WQiqE1sbmAwpBwU86GPUYhgLfH-xiG93NKIFoA0ZDPccq3A1y9LCkDUijjVAqbVWuOHmaRS_QgF_5Zfs058AIjcHS4x0cJn09rYZL3iD7dBkc0PSRRLXcWbRqnf3CIGIpLrcRxUn8PoBSScEKrxp3Q_7QhngZyQuIL7WaP6mdyCvfgss5HauUjEdBzd60trYeIXOpSEkqxfP42PiN-OWZEocKPGrHUhtYuqWNSfNjJ_u2) | diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md new file mode 100644 index 0000000..258f67b --- /dev/null +++ b/docs/diagrams/README.md @@ -0,0 +1,78 @@ +# ANSCORE — L2 & L3 Architecture Diagrams (PlantUML) + +12 PlantUML diagrams covering Layer 2 (ANSVIS Communication Layer (CL)) and Layer 3 (Qt/QML UI). + +## Files + +| # | File | Type | Purpose | +|---|---|---|---| +| 01 | `01-system-context.puml` | Component | L1 / L2 / L3 overview with the 3 transports | +| 02 | `02-l2-internals.puml` | Component | L2 adapter layer + legacy + infrastructure | +| 03 | `03-l2-ownership.puml` | Component | Human-owned vs AI-coder vs reused legacy modules | +| 04 | `04-l3-internals.puml` | Component | Qt/QML shell / network / state / screens | +| 05 | `05-seq-configure-deploy.puml` | Sequence | Operator adds camera → AI task → deploys | +| 06 | `06-seq-live-events.puml` | Sequence | SSE event tail + evidence image/clip | +| 07 | `07-seq-liveview.puml` | Sequence | Liveview with bbox overlay sync | +| 08 | `08-seq-async-scan.puml` | Sequence | Async ONVIF scan via job queue | +| 09 | `09-seq-large-upload.puml` | Sequence | Large model upload via presigned URL | +| 10 | `10-deployment-topology.puml` | Deployment | Workstations / server / edges + ports | +| 11 | `11-l3-engineer-ownership.puml` | Component | 6-engineer L3 task allocation | +| 12 | `12-dependency-chain.puml` | Component | What gates what, critical path | + +--- + +## How to view these in StarUML + +StarUML doesn't render `.puml` natively, but the official **PlantUML extension** does: + +1. In StarUML: `Tools → Extension Manager → search "PlantUML" → Install` +2. Restart StarUML. +3. `File → Open` → pick any `.puml` file from this folder, **or** use `Tools → PlantUML → Preview Diagram`. +4. To get an editable StarUML diagram (`.mdj`), use the extension's "Generate Diagram from PlantUML" feature, then save as `.mdj`. + +Caveat: the extension renders accurately but the auto-generated StarUML elements may need light layout cleanup. If you want fully native StarUML diagrams, use these `.puml` files as the specification and recreate in StarUML — they're small enough that this takes ~10 min each. + +--- + +## Alternative viewers (no install needed) + +| Tool | How | +|---|---| +| **PlantUML web server** | → paste any `.puml` content → get PNG/SVG/PDF | +| **VS Code** | Install the "PlantUML" extension by jebbs → `Alt+D` to preview | +| **JetBrains (CLion / IntelliJ / Rider)** | Install the "PlantUML Integration" plugin → preview on the side panel | +| **PlantUML CLI** (batch export) | `brew install plantuml` then `plantuml -tpng docs/diagrams/*.puml -o ../out/` | +| **PlantUML CLI** (SVG for slides) | `plantuml -tsvg docs/diagrams/*.puml -o ../out/` | + +The web server is the fastest path if you just want to grab images for a slide deck or PDF. + +--- + +## Render all to PNG in one shot + +```bash +# from the repo root +brew install plantuml # macOS; or: apt install plantuml +mkdir -p out/diagrams +plantuml -tpng -o "$(pwd)/out/diagrams" docs/diagrams/*.puml +``` + +Output: one PNG per diagram in `out/diagrams/`. + +For high-DPI presentations use `-tsvg` instead of `-tpng`. + +--- + +## Editing tips + +- Diagrams use only stable PlantUML features — should render in any PlantUML version ≥ 1.2022.0. +- Colors used: `#LightYellow` (human/lead), `#LightBlue` (AI/E2), `#LightGreen` (E3), `#LightPink` (E4), `#LightCoral` (E5), `#Lavender` (E6), `#LightGray` (reused legacy). Change consistently if you want a different palette. +- Each file declares its own `@startuml NAME` so multiple files can render to predictable filenames. +- Notes (`note bottom of ...`) are intentional — leave them in; they explain non-obvious decisions. + +--- + +## Related + +- `docs/L2-L3-architecture.md` — same diagrams in Mermaid + accompanying prose. +- `contracts/openapi.v1.json` — the REST contract these diagrams reference. diff --git a/docs/diagrams/png/01-system-context.png b/docs/diagrams/png/01-system-context.png new file mode 100644 index 0000000..77cd466 Binary files /dev/null and b/docs/diagrams/png/01-system-context.png differ diff --git a/docs/diagrams/png/02-l2-internals.png b/docs/diagrams/png/02-l2-internals.png new file mode 100644 index 0000000..9afc0b7 Binary files /dev/null and b/docs/diagrams/png/02-l2-internals.png differ diff --git a/docs/diagrams/png/03-l2-ownership.png b/docs/diagrams/png/03-l2-ownership.png new file mode 100644 index 0000000..57da025 Binary files /dev/null and b/docs/diagrams/png/03-l2-ownership.png differ diff --git a/docs/diagrams/png/04-l3-internals.png b/docs/diagrams/png/04-l3-internals.png new file mode 100644 index 0000000..556165c Binary files /dev/null and b/docs/diagrams/png/04-l3-internals.png differ diff --git a/docs/diagrams/png/05-seq-configure-deploy.png b/docs/diagrams/png/05-seq-configure-deploy.png new file mode 100644 index 0000000..58f7d0b Binary files /dev/null and b/docs/diagrams/png/05-seq-configure-deploy.png differ diff --git a/docs/diagrams/png/06-seq-live-events.png b/docs/diagrams/png/06-seq-live-events.png new file mode 100644 index 0000000..7cf42de Binary files /dev/null and b/docs/diagrams/png/06-seq-live-events.png differ diff --git a/docs/diagrams/png/07-seq-liveview.png b/docs/diagrams/png/07-seq-liveview.png new file mode 100644 index 0000000..35c7472 Binary files /dev/null and b/docs/diagrams/png/07-seq-liveview.png differ diff --git a/docs/diagrams/png/08-seq-async-scan.png b/docs/diagrams/png/08-seq-async-scan.png new file mode 100644 index 0000000..9b126fd Binary files /dev/null and b/docs/diagrams/png/08-seq-async-scan.png differ diff --git a/docs/diagrams/png/09-seq-large-upload.png b/docs/diagrams/png/09-seq-large-upload.png new file mode 100644 index 0000000..a7a36bd Binary files /dev/null and b/docs/diagrams/png/09-seq-large-upload.png differ diff --git a/docs/diagrams/png/10-deployment-topology.png b/docs/diagrams/png/10-deployment-topology.png new file mode 100644 index 0000000..7289b0b Binary files /dev/null and b/docs/diagrams/png/10-deployment-topology.png differ diff --git a/docs/diagrams/png/11-l3-engineer-ownership.png b/docs/diagrams/png/11-l3-engineer-ownership.png new file mode 100644 index 0000000..8fbbc54 Binary files /dev/null and b/docs/diagrams/png/11-l3-engineer-ownership.png differ diff --git a/docs/diagrams/png/12-dependency-chain.png b/docs/diagrams/png/12-dependency-chain.png new file mode 100644 index 0000000..3b1dccc Binary files /dev/null and b/docs/diagrams/png/12-dependency-chain.png differ diff --git a/docs/print.css b/docs/print.css new file mode 100644 index 0000000..dab3fbd --- /dev/null +++ b/docs/print.css @@ -0,0 +1,191 @@ +@page { + size: A4; + margin: 22mm 18mm 22mm 18mm; + @top-right { + content: "ANSCORE — System Architecture (L2 + L3)"; + font-family: -apple-system, "Helvetica Neue", Arial, sans-serif; + font-size: 8.5pt; + color: #888; + } + @bottom-right { + content: "Page " counter(page) " / " counter(pages); + font-family: -apple-system, "Helvetica Neue", Arial, sans-serif; + font-size: 8.5pt; + color: #888; + } + @bottom-left { + content: "v1.0 • 2026-05-26 • ANSCENTER"; + font-family: -apple-system, "Helvetica Neue", Arial, sans-serif; + font-size: 8.5pt; + color: #888; + } +} + +@page :first { + @top-right { content: ""; } + @bottom-right { content: ""; } + @bottom-left { content: ""; } +} + +html, body { + font-family: -apple-system, "Helvetica Neue", "Segoe UI", Arial, "Apple Symbols", "STIXGeneral", "Lucida Grande", sans-serif; + font-size: 10.5pt; + line-height: 1.45; + color: #222; +} + +h1 { + font-size: 22pt; + color: #102a55; + border-bottom: 2px solid #102a55; + padding-bottom: 4pt; + margin-top: 0; + page-break-before: always; + page-break-after: avoid; +} + +h1:first-of-type { + page-break-before: avoid; +} + +h2 { + font-size: 15pt; + color: #1a4080; + margin-top: 1.4em; + page-break-after: avoid; +} + +h3 { + font-size: 12.5pt; + color: #1a4080; + margin-top: 1.1em; + page-break-after: avoid; +} + +h4 { + font-size: 11pt; + color: #333; + margin-top: 0.9em; + page-break-after: avoid; +} + +p, ul, ol { + margin: 0.5em 0; +} + +ul, ol { + padding-left: 1.4em; +} + +li { + margin: 0.15em 0; +} + +a { + color: #1a4080; + text-decoration: none; +} + +code { + font-family: "SF Mono", "Menlo", Consolas, monospace; + font-size: 9pt; + background: #f4f4f6; + padding: 1px 4px; + border-radius: 3px; + color: #2c2c2c; +} + +pre { + font-family: "SF Mono", "Menlo", Consolas, monospace; + font-size: 9pt; + background: #f6f8fa; + border: 1px solid #e1e4e8; + border-radius: 4px; + padding: 10pt 12pt; + line-height: 1.4; + overflow-x: auto; + page-break-inside: avoid; +} + +pre code { + background: transparent; + padding: 0; + font-size: 9pt; +} + +table { + border-collapse: collapse; + width: 100%; + margin: 0.8em 0; + font-size: 9.5pt; + page-break-inside: avoid; +} + +th, td { + border: 1px solid #d0d4dc; + padding: 5pt 7pt; + text-align: left; + vertical-align: top; +} + +th { + background: #eef2f8; + color: #102a55; + font-weight: 600; +} + +tr:nth-child(even) td { + background: #fafbfd; +} + +img { + max-width: 100%; + display: block; + margin: 0.6em auto; + page-break-inside: avoid; +} + +hr { + border: 0; + border-top: 1px solid #d0d4dc; + margin: 1.5em 0; +} + +blockquote { + border-left: 3px solid #c3cad6; + margin: 0.6em 0; + padding: 0.2em 0.9em; + color: #555; + background: #f7f8fa; + font-style: italic; +} + +/* Title block (pandoc emits a header div) */ +header#title-block-header { + text-align: center; + margin-top: 18%; + padding-bottom: 35%; + border-bottom: none; +} + +header#title-block-header h1.title { + font-size: 30pt; + color: #102a55; + border-bottom: none; + page-break-before: avoid; + margin-bottom: 12pt; +} + +header#title-block-header p.subtitle { + font-size: 14pt; + color: #555; + font-style: italic; + margin: 6pt 0; +} + +header#title-block-header p.author, +header#title-block-header p.date { + font-size: 11pt; + color: #777; + margin: 4pt 0; +}