Files
ANSCORE/docs/L2-L3-architecture.md
2026-06-12 14:13:26 +10:00

18 KiB
Raw Permalink Blame History

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

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:

  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)

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:

  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.