TAA Vision

Overview #

TAA Vision turns camera frames into structured answers to three questions: what is in this photo, what does it say, and who is this. It is multi-tenant, provider-agnostic, and runs the same code in the cloud or on-prem.

You interact with the platform three ways: direct API calls with an API key, the edge apps (a mobile capture app and a headless processor) that stream results to you, and the admin console (this site) for managing tenants, keys, devices, and events.

Architecture #

Four cooperating parts, all speaking the same REST + MQTT contract.

Cloud calls go through provider interfaces (IFaceProvider, IVisionProvider, IStorageProvider) so the same server runs on AWS Rekognition, Azure, or the on-prem processor by flipping an env var. Storage and the data store are abstracted the same way.

Authentication & API keys #

Programmatic access uses per-tenant API keys; the console uses an admin session.

Every API key is prefixed tvk_ and carries a set of scopes. Send it on every request in the X-API-Key header:

# Every API request carries your tenant key
curl https://api.vision.xos.taa.io/api/v1/identity/identify \
  -H "X-API-Key: tvk_live_9f2c…" \
  -H "Content-Type: application/json" \
  -d '{ "faceGroupId": "guests", "imageBase64": "…" }'

Keys are minted per tenant in the console (API Keys) or via the admin API. Available scopes:

• detect, extract, identity — the three scan families.
• faces, enroll, unenroll — manage face groups and enrollments.
• plates — manage plate watchlists and run plate scans.
• events — read and write the tenant event log.

The admin console authenticates people (not machines) with an email/password login that returns a JWT. Admin-only actions — creating tenants, minting keys, managing devices — require an admin role session, not an API key.

Enrollment #

Identity works against face groups — named collections of enrolled subjects. Enroll before you identify.

1. Create a group — POST /api/v1/faces/groups with a name (e.g. guests). Groups are per-tenant.
2. Enroll subjects — POST /api/v1/faces/enroll with a base64 image and your own externalId (an employee id, member number, anything stable).
3. Identify — scans against the group return the matched externalId and a confidence score.

POST /api/v1/faces/enroll
# X-API-Key: tvk_… (scope: enroll)
{
  "faceGroupId": "guests",
  "imageBase64": "/9j/4AAQSk…",
  "externalId": "MEMBER-4471"
}

Enrollment photos (only enrollment photos — never scan images) are archived to object storage keyed on the enrollment, so identities survive a provider switch. Delete a single enrollment with DELETE /api/v1/faces/enrollments/:id, or purge everything for a subject across groups with DELETE /api/v1/faces/subjects/:externalId.

Identity — identify & verify #

Two questions, two endpoints.

POST /api/v1/identity/identify
{
  "faceGroupId": "guests",
  "imageBase64": "/9j/4AAQSk…"
}
→ { "match": true, "externalId": "MEMBER-4471", "confidence": 98.4 }

Scans are ephemeral by design — the probe image is not persisted. Each scan writes an audit event to the tenant log (matched or unmatched) and, when a broker is configured, publishes to MQTT in real time (see Events & MQTT).

Detection & extraction #

Non-identity vision: what’s in the frame, and what does it say.

• Detect — POST /api/v1/detect returns labelled objects (people, vehicles, …) with bounding boxes and confidence.
• Extract — POST /api/v1/extract pulls text / OCR and structured details out of a frame or crop.

POST /api/v1/detect
# X-API-Key: tvk_… (scope: detect)
{ "imageBase64": "/9j/4AAQSk…" }
→ { "objects": [ { "label": "person", "confidence": 96.1, "box": {…} } ] }

Both run through the same provider abstraction as identity, so they honour your VISION_PROVIDER selection (AWS, Azure, or the on-prem processor).

License plates & watchlists #

Plate reading pairs OCR with per-tenant watchlists so a match can trigger an action.

1. Create a watchlist — POST /api/v1/plates/watchlists.
2. Add entries — POST /api/v1/plates/watchlists/:id/entries, each a plate + your own externalId. Matching is fuzzy (normalizes O/0, I/1, spacing).
3. Scan — POST /api/v1/plates/scan reads a plate from an image and checks it against the watchlist, emitting a match/unmatch event.

Enroll plates directly with POST /api/v1/plates/enroll, remove a single entry with DELETE /api/v1/plates/entries/:id, or clear a subject everywhere with DELETE /api/v1/plates/subjects/:externalId.

Edge devices #

Two edge apps put cameras in the field. Both self-register, report a heartbeat, and stream results to your MQTT broker.

Provisioning a device — the console generates an edge config bundle carrying the tenant identity, a scoped API key, and MQTT settings. Deliver it two ways:

1. Scan a QR code — open Settings → Generate Edge Config, pick a location/device id and capture mode, and the device scans the QR to configure itself.
2. Import JSON — download the same bundle as a file and import it on the device’s setup screen.

The generated key is named edge:<location>/<device> so you can revoke a single device independently. Capture can be left as-is, set to browser camera, or a node source (USB / RTSP / WebRTC) with an FPS and downscale (CAPTURE_WIDTH) applied via the pipeline.

Events & MQTT #

Every scan writes an audit event, and — when you configure a broker — publishes to MQTT in real time so your app reacts the instant a camera sees someone.

Point us at your broker (or leave it unset to just poll the event API):

PUT /api/v1/tenants/{tenantId}/mqtt
{
  "mqttBrokerUrl": "mqtts://broker.example.com:8883",
  "mqttUsername": "my-user",
  "mqttPassword": "my-pass",
  "mqttTopicPrefix": "my-app/vision",
  "mqttClientId": "taa-vision-park1"
}

Results publish under your prefix. The core topics:

Admin console #

This site. Everything you can do by API, plus fleet visibility.

• Dashboard — tenants, edges online/total, MQTT + platform status, with sortable tenant tables and live edge counts.
• Tenant detail — activity, history, edge devices (rename/tag/remove), API keys, usage & billing, and settings (external MQTT, edge config & QR).
• Users — console accounts, roles (admin / tenant), and per-tenant access.
• Trash — soft-deleted tenants. A trashed tenant is deactivated and hidden but fully recoverable; Restore brings it back with API keys and enrollments intact.

Deployment & operations #

How the cloud deployment is shaped, and how to ship a change.

• API (api.vision.xos.taa.io) — an autoscaled Express container on ECS Fargate behind an ALB with WAF.
• MQTT (mqtt.vision.xos.taa.io) — AWS IoT Core; edge devices connect with per-device X.509 certs scoped to their tenant.
• Dashboard (vision.xos.taa.io) — this Astro build on S3 + CloudFront.
• Data — shared RDS Postgres with a dedicated vision DB and pgvector; enrollment photos in S3.

Deploying: the Deploy prod (API + Web) GitHub Actions workflow is a manual “Run workflow” button — pick which stacks to deploy (all / api / web / data) and it validates, runs the CDK deploy, applies DB migrations in-VPC, and smoke-tests. Migrations are backward-compatible and run as a one-off ECS task on the RDS security group.

API reference #

All routes live under /api/v1. Scan/identity/plate routes need the matching scope.

New to the platform? Start at Authentication, then Enrollment → Identity. For what changed recently, see the Release Notes →.