# 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.*