Sentryface

Perimeter-aware face-matching robot fleet console

Features  •  Quick Start  •  Architecture  •  MQTT Topics  •  Configuration  •  Development

---

Demo

Sentryface fans out camera frames and detection events over MQTT, matches faces against an enrollment roster, and triages alerts on a polled operator console.

---

Features

Feature	Description
Edge → broker → backend pipeline	Camera-equipped patrol robots publish frames and detection events to an MQTT broker; the backend bridges them into a SQLite store and a polled REST API
Face enrollment roster	Operators register known faces (employees, residents, contractors) with clearance level and zone restrictions
Stubbed face matcher	Lightweight perceptual-hash matcher with a tunable threshold — pluggable so a real embedding model can drop in later
Alert triage	Detections are classified into info, warning, or critical based on identity, clearance, and zone
Patrol scheduling	Per-robot zone-coverage planner that rotates patrol assignments through the day
Operator console	Live camera mosaic, detection overlay, alert feed, fleet status, zone floor plan, enrollment panel, and shift histograms — all served from REST + short-polling
One-command setup	docker compose up --build brings up the broker, backend, edge simulator, and frontend

---

Quick Start

Prerequisites

• Docker Desktop or Docker Engine + Compose v2

Run

git clone https://github.com/StrikeRobot/sentryface.git
cd sentryface

cp .env.example .env

docker compose up --build

Open http://localhost:3000 — Sentryface is ready.

The MQTT broker is reachable on localhost:1883 if you want to attach a real mosquitto_sub and watch live traffic.

---

Architecture

┌──────────────┐  MQTT publish   ┌──────────────┐  MQTT subscribe  ┌──────────────────────┐    REST    ┌──────────────┐
│   edge       │ ───────────────►│   broker      │ ────────────────►│   backend             │ ◄────────► │   frontend   │
│   simulator  │                 │   Mosquitto   │                  │   FastAPI + SQLModel  │   poll @   │   Next.js 14 │
│   (patrol-   │                 │   :1883       │                  │   face_engine +       │   1–3 Hz   │   Zustand    │
│   bot fleet) │                 │               │                  │   alert_dispatcher    │            │   Framer     │
└──────────────┘                 └──────────────┘                  └──────────────────────┘            └──────────────┘
                                                                              :8000                          :3000

Data flow for a face detection event:

1. An edge simulator advances a scripted scenario and publishes a camera/<robot>/frame payload (synthetic JPEG-ish blob + bounding boxes) plus a detect/<robot>/event payload (claimed identity, confidence).
2. The MQTT bridge inside the backend subscribes to sentryface/+/frame and sentryface/+/event and queues both into the event bus.
3. The face engine matches the claimed identity hash against the KnownFace table; mismatches become intruder candidates.
4. The alert dispatcher classifies each match into a severity using the clearance level + zone, then persists a Detection row and (if warranted) an Alert row.
5. The frontend polls /alerts/, /detections/recent, /robots/, /patrols/ on a small interval and re-renders.

---

MQTT Topics

Topic	Direction	Payload (JSON)
sentryface/<robot>/frame	edge → backend	{ ts, robot, zone, jpeg_b64, boxes: [{x,y,w,h}] } (jpeg_b64 is a placeholder string in the simulator)
sentryface/<robot>/event	edge → backend	{ ts, robot, zone, claimed_identity_hash, claimed_name?, confidence }
sentryface/<robot>/heartbeat	edge → backend	{ ts, robot, battery_pct, status }
sentryface/<robot>/command	backend → edge	`{ action: "patrol"

---

Configuration

Variable	Default	Description
DB_PATH	/data/sentryface.db	SQLite path inside the backend container
ALLOWED_ORIGINS	http://localhost:3000	CORS allowed origins (comma-separated)
MQTT_HOST	broker	MQTT broker hostname
MQTT_PORT	1883	MQTT broker port
MQTT_TOPIC_FRAMES	sentryface/+/frame	Topic filter for camera frames
MQTT_TOPIC_EVENTS	sentryface/+/event	Topic filter for detection events
FACE_MATCH_THRESHOLD	0.78	Minimum similarity (0–1) to count as a match
FACE_MATCH_COOLDOWN_S	8	Per-identity cooldown to suppress duplicate alerts
ALERT_INTRUDER_SEVERITY	critical	Severity stamped on unknown-face detections
EDGE_TICK_HZ	2	Simulator publish rate per robot
EDGE_ROBOT_COUNT	3	Number of simulated patrol robots

---

Development

Backend

cd backend
pip install -e ".[dev]"
uvicorn app.main:app --reload --port 8000

Edge simulator

cd edge
pip install -e .
python -m simulator.main

Frontend

cd frontend
npm install
cp .env.local.example .env.local
npm run dev

Tests

cd backend
pytest -v

---

Tech Stack

Layer	Technology
Frontend framework	Next.js 14 (App Router)
Language	TypeScript 5
Styling	Tailwind CSS 3
State management	Zustand 4
Animation	Framer Motion 11
Charts	Recharts 2
Backend framework	FastAPI
Backend language	Python 3.12
ORM / DB	SQLModel + SQLite
Messaging	Eclipse Mosquitto (MQTT 5) via paho-mqtt
Container	Docker + Docker Compose

---

License

MIT © 2026 — see LICENSE for details.