Administrator guide

For the console release of September 2026. Everything here lives under the Administer group of the sidebar (Cameras & Zones, Users & Roles, Audit Trail, System Health, Settings & Integrations), which only administrators see. The User guide covers the investigative screens.

1. How an organisation is set up

Every customer is an organisation (a tenant). Everything — cameras, footage, findings, users, devices, keys, audit rows — belongs to one organisation, and every query is filtered by it on the server.

An organisation is created by the Suraag platform team (a superadmin) from Settings & Integrations → Create an organization with its first admin:

1. Organization ID — a lowercase slug, e.g. hyd-traffic-north; it never changes.
2. Name — shown in the console.
3. Plan — the vertical: Retail or Law enforcement. It selects the default analysis profile (retail counts people and ignores vehicles; law enforcement runs everything).
4. First admin username and password (8 characters or more; the password policy enforced at sign-in requires 10).

Hand the first admin their credentials through a channel you control and ask them to change the password on first use (an administrator resets it from Users & Roles; there is no self-service password change in this release).

Onboarding checklist for the new administrator:

• Create users and roles (section 2).
• Register cameras and draw zones, tripwires and armed hours (section 3).
• Configure alert channels (section 4).
• Set live-clip retention (section 5).
• Enrol edge devices for live cameras (section 7).
• Issue API keys only if an integration needs them (section 6).

2. Users, roles and invitations

Users & Roles lists every account with its role, camera scope, last activity and status.

Creating a user

+ Add user → username, password (at least 8 characters; the server policy is 10, not the username, not a common password), a Role, and optional gated capabilities — face, weapon, reid. Custom roles bring their own capabilities and tab list, so the checkboxes disappear when one is chosen.

Deliver the initial password out of band. There is no e-mail invitation flow in the console in this release; where an e-mail address is on record, the account routes for invitation and password reset exist on the server and are rate-limited.

Managing a user

Edit opens: change Role (not for superadmins, not for yourself), Enable / Disable (a disabled user is signed out within a minute and cannot sign in until re-enabled), Reset password (takes effect immediately and signs out every session), Delete (not yourself).

Base levels

Custom roles

+ New role → a name (e.g. "Traffic Inspector"), a Permission level (officer, investigator or admin — a role can only narrow a level, never exceed it), the gated capabilities it grants, and Visible tabs (leave all unchecked for the level's default). A role with users assigned cannot be deleted — reassign them first.

Roles restrict; servers enforce. Hiding a tab is a convenience; every query is tenant-scoped and camera-scoped on the server regardless.

3. Cameras, zones and armed hours

Cameras & Zones lists every camera the organisation owns — forensic cameras (uploaded footage) and edge-box cameras (live clips) — with a hint of what is configured ("2 zones · tripwire · armed · calibrated").

Zones and tripwire

Pick a camera; its reference frame appears.

• Draw zone → click at least three points → Finish zone. Choose the kind: restricted (intrusion), no_parking, counter, entry. Zones feed the intrusion and parking rules and the zone filter in Search.
• Tripwire → click two points to define a crossing line; it feeds footfall counting.
• Clear geometry removes both. Save writes zones, tripwire and armed hours together. Geometry rules apply on the next analysis of that camera.

Armed hours

Armed hours turn any person seen on a live camera into an after-hours intrusion alert. Each window has a start, an end (a window may cross midnight, e.g. 22:00 → 08:00) and the weekdays it applies to (M T W T F S S). + Add window for split schedules, Remove to drop one, Save armed hours to apply — armed-hours alerts apply to every new live clip from then on. With no window, after-hours alerts are off for that camera and the screen says so.

Profile

Profile per camera: inherit the organisation's vertical, or override with one of the server's profiles. It applies on the next analysis.

Ground calibration (distance and speed)

Calibrate → click four points on the frame and their matching positions on the map (or type latitude/longitude), Save calibration. The console rejects incomplete pairs, out-of-range coordinates and points that lie on one line. Once calibrated, Check a distance measures between two frame points ("Ground distance ≈ 12 m") and the Dossier's travel-feasibility check uses real distances. Clear calibration removes it.

Camera location and map

Set a camera's location so Plates and Dossier can draw routes. The Camera map shows every camera that has one. The Footfall — last 7 days panel summarises visitors, peak hour, average dwell and long stays for cameras with a tripwire.

4. Alert channels

Settings & Integrations → Alert channels (saved with Save alert channels):

WhatsApp and e-mail need provider credentials on the server (Meta token and phone number ID; SMTP host). Until the operator has added them the screen shows a banner: numbers and addresses are saved, but nothing is sent. SMS (MSG91 or Twilio) is supported by the alert dispatcher but is configured on the server, not in this screen — ask support to enable it.

Every dispatch attempt is recorded (channel, target, status, retries — 2, 5, 15 and 60 minutes, five attempts, then dead) and visible in the audit trail. An alert nobody acknowledges in time is marked Escalated in the Alerts inbox. Users can additionally turn on browser push for their own device from Alerts → Notify this device; the push carries no content.

5. Retention and legal hold

Settings & Integrations → Data & retention:

• Live motion clips (days) — clips uploaded by edge devices, and everything derived from them (findings, crops, vectors), are purged daily once older than this. Default 14, range 1–365. Events and alert records are kept.
• Forensic uploads — kept until an administrator deletes them (Library → Delete, or Delete all videos). There is no automatic expiry for investigator uploads.
• Audit trail — kept forever, text only. Not configurable.

Evidence lock. A video referenced by a sealed report cannot be deleted; Delete all videos reports how many were kept as sealed evidence.

Legal hold. A hold pins footage regardless of retention and blocks deletion until it is lifted. Any user in the organisation can place a hold through the API (POST /api/source/{camera_id}/hold); only an administrator can lift one. Holds are audited. In this release the hold is placed via the API or by asking support; the Library shows the evidence-locked state.

6. API keys

Settings & Integrations → API access issues keys for the public /v1 API (see the API reference).

• + Create an API key → a Name (e.g. "CCTNS bridge") and one or more Scopes: plate:read, attrs:read, finding:read, ingest.
• The key is shown once. Copy it into the consuming system immediately; only its SHA-256 is stored and it cannot be recovered.
• The list shows each key's fingerprint, scopes, last use and status. Revoke stops it immediately.
• A key sees only your organisation's cameras and findings; every call is audited as apikey:<org>.

7. Edge devices and enrolment

Live cameras reach Suraag through the edge agent (a Raspberry Pi appliance or any PC on the shop's network) or through the mobile app in capture-only mode. Both authenticate with a device token obtained once from a single-use enrolment code.

1. Settings & Integrations → Edge devices → Add device: a Name, a Platform (edge, windows, android, ios, dashcam) and optionally the Camera it feeds.
2. The console shows the Device ID and Enroll token once. Copy them.
3. On the device run python main.py enroll --server https://suraag.xyz --code <ENROLL TOKEN> --device-id <DEVICE ID> (or scan them from the mobile app). The device receives a long-lived token; only its hash is stored on the server.
4. Done — hide these credentials. A used or expired code is refused; create the device again if needed.

The device list shows platform, camera, status and Last seen (from the heartbeat the agent sends every minute). Revoke stops the device's token immediately. Live Watch derives each tile's status from the same heartbeat: live under 5 minutes, quiet under an hour, otherwise offline.

8. AI provider

Settings & Integrations → AI provider: Platform default (Suraag's configured model via OpenRouter, text only) or Self-hosted / custom endpoint with an endpoint URL, model name and API key (stored, never displayed again). The model is used for question parsing and narration and never for counts, matches or evidence.

9. Plan, quota and usage

Each organisation has a plan tier with limits on cameras, users, devices, storage, videos per month and API keys. An upload that would exceed a limit is refused with Plan limit reached before the file is kept. Usage totals appear in Settings & Integrations (users, cameras, videos, storage, devices) and per-tenant in System Health; limits themselves are changed by the platform team — contact support to move tiers.

10. Audit trail

Audit Trail shows every action, kept forever: who, what, target, time, IP. Filter by user, action prefix and time; Export as CSV for an inquiry. Sign-in failures, lockouts and analysis errors are highlighted. The Activity timeline shows uploads, analysis runs (with duration and frames) and searches in order. Reading a sealed report's custody ledger is itself an audited action.

11. System Health

Dependency status, the GPU engine's state, the model registry (which heads are evidence, lead or gated), storage meters and per-organisation usage. Administrators can Warm the GPU workers and, where a dedicated pod is configured, Start or Stop it (with confirmation). While the engine is stopped, uploads queue.

12. Service levels

The hosted service targets 99.5 % monthly availability for the console and API, support Monday–Saturday 09:00–19:00 IST with Severity 1 monitored outside hours for law-enforcement customers, an RPO of 6 hours (database backups every six hours, verified off-box) and an RTO of 4 hours. Analysis runs on an on-demand GPU engine; uploads queue while it is stopped. The full description, severity table and exclusions are in the Service level description.

13. Getting help

support@suraag.xyz — include the organisation ID, the screen, and the time (IST).