18 KiB
ANSCORE — Layer 2 & Layer 3 Architecture
Scope: Layer 2 (ANSVIS Communication Layer (CL), REST
/api/v1surface, 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. All UI ↔ CL communication conforms to it.Transports:
- REST / HTTPS — control, CRUD, configuration, deploy
- SSE (
text/event-stream) — live event tail- HLS / RTSP / WebRTC — live video (descriptor obtained via REST)
1. System context — L1 / L2 / L3
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<br/>(reused as-is)"]
RELAY["Media relay<br/>HLS / RTSP / WebRTC"]
SSE["SSE event broadcaster"]
STORE["Event DB<br/>+ clip object store"]
JOBS["Async job queue"]
AUTH["Auth + RBAC"]
end
subgraph L1["Layer 1 — ANSCORE Edge Runtime<br/>(one per target)"]
EDGE["Camera + Inference + Triggers"]
end
UI -- "① REST / HTTPS<br/>control + CRUD" --> APIV1
UI -- "② SSE / HTTPS<br/>live event tail" --> SSE
UI -- "③ HLS / RTSP / WebRTC<br/>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
graph TB
subgraph CLIENTS["Clients"]
QT["Qt/QML UI"]
EXT["3rd-party integrations<br/>(optional)"]
end
subgraph EDGE_API["L2 / api / v1 surface"]
ROUTER["REST router"]
AUTHMW["Auth middleware<br/>(Bearer)"]
VALID["Request validation<br/>(OpenAPI schemas)"]
ERR["Error mapper<br/>→ RFC 7807"]
RATE["Rate limiter"]
SSE_HUB["SSE broadcaster<br/>(per-subscription filter)"]
end
subgraph ADAPTER["v1 Adapter Layer<br/>(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<br/>(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<br/>(scans, uploads, deploys, updates)"]
EVENTS_DB["Event metadata DB"]
CLIPS["Clip / image object store<br/>(S3 / MinIO / FS)"]
LOGS["Logs + metrics + health"]
RELAY["Media relay<br/>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):
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
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<br/>(openapi.v1.json → C++/Qt)"]
SSE_CL["SSE subscriber<br/>(QNetworkReply chunked)"]
MEDIA["Media client<br/>QtMultimedia / GStreamer"]
OVERLAY["Bbox overlay renderer<br/>(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<br/>+ ONVIF discovery<br/>+ calibration"]
DG_EDIT["Pipeline editor<br/>(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` |
| 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
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,<br/>capturing, image_size — no<br/>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
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 <presigned URL>
CLIPS-->>UI: MP4 bytes
UI->>UI: play in QtMultimedia
4.3 Liveview with bbox overlay
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
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
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 <presigned_url> (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
graph LR
subgraph CUSTOMER["Customer site / cloud"]
subgraph DESKTOPS["Operator workstations"]
D1["Win desktop<br/>Qt UI"]
D2["Mac desktop<br/>Qt UI"]
D3["Linux desktop<br/>Qt UI"]
end
subgraph SERVER["ANSVIS server host"]
NGINX["Reverse proxy<br/>TLS terminator"]
APP["ANSVIS app<br/>(adapter + legacy core)"]
RELAY["Media relay"]
OBJ["Object store<br/>(S3/MinIO/FS)"]
DB["DBs<br/>(config / events)"]
end
subgraph EDGES["Edge targets"]
E1["Linux x86 + NV"]
E2["Win x86 + NV"]
E3["Jetson Orin"]
end
end
D1 -- "TLS 443<br/>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)
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<br/>signing, notarize, auto-update"]
E1G["CI matrix"]
end
subgraph E2["E2 — Pipeline Editor Specialist"]
E2A["Visual DAG editor<br/>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<br/>(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<br/>(from openapi.v1.json)"]
E4B["Camera + ONVIF discovery flow"]
E4C["Camera calibration UI<br/>(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<br/>Win + Mac + Linux"]
E6C["Crash reporting (Sentry/Crashpad)"]
E6D["QML Profiler perf passes"]
E6E["User docs surface"]
end
CONTRACT[(openapi.v1.json<br/>frozen contract)]
E1 -.-> CONTRACT
E2 -.-> CONTRACT
E3 -.-> CONTRACT
E4 -.-> CONTRACT
E5 -.-> CONTRACT
Critical-path order:
- Week 1–2 (E1 only): monorepo, generated REST client, auth, design system stub,
make devbrings up Prism mock. This unblocks everyone else. - Week 1–2 (E2 in parallel): node-editor spike. Highest schedule risk → de-risk early.
- Week 2+ (E3, E4, E5 in parallel): each owns a vertical against the mock CL. E6 starts integration testing.
- Week 4+: cut from mock CL to real ANSVIS
/api/v1as adapter endpoints land.
7. What gates what (dependency chain)
graph LR
CONTRACT["openapi.v1.json<br/>(frozen)"]
MOCK["Prism mock server"]
ADAPT["ANSVIS /api/v1 adapter<br/>(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:
- Field naming —
snake_case(current default inopenapi.v1.json) orcamelCase? - Auth scheme — keep Bearer (current) or move to OAuth2/OIDC for v1?
- Mock-server pinning — Prism for free, or build a richer custom mock?
- Liveview transport for v1 — HLS only (recommended), or RTSP-direct on LAN, or jump straight to WebRTC?
- Object store choice — local FS (single host), MinIO (single host scalable), or S3 (cloud)?
- Auto-update for the Qt client — Sparkle on Mac, Squirrel/MSIX on Windows, AppImage on Linux. Confirm budget for each.
- Contract repo — co-located in
ANSCORE/contracts/(current) or split into a separateanscore-contractsrepo?
Last updated: 2026-05-26 — diagrams reflect openapi.v1.json v1.0.0 draft.