taraneshwer/vizage

Purpose and entry points

Vizage is an offline desktop application for masked-face recognition. Its primary runtime is a Python/FastAPI backend launched as uvicorn app.main:app, with a React UI packaged through Electron. The backend application boundary is backend/app/main.py; desktop process startup and backend lifecycle management are in frontend/electron/main/main.ts and frontend/electron/services/backendManager.ts.

Desktop client and API boundary

The React renderer provides recognition, enrollment, camera, history, settings, diagnostics, and system views. It calls backend HTTP APIs and consumes real-time events over WebSocket:

• frontend/src/App.tsx

• frontend/src/utils/api.ts

• frontend/src/hooks/useWebSocket.ts

Electron separates privileged process/IPC functionality from the renderer via its main and preload processes:

• frontend/electron/main/main.ts

• frontend/electron/preload/preload.ts

• frontend/electron/ipc/handlers.ts

Backend API and real-time event delivery

FastAPI exposes versioned operational endpoints for camera control, recognition, enrollment, history, runtime, settings, and system state. API routers are the external control plane, while WebSocket infrastructure broadcasts runtime events and logs to connected clients:

• backend/app/api/v1/routers/recognition.py

• backend/app/api/v1/routers/enrollment.py

• backend/app/api/v1/websockets/event_bridge.py

• backend/app/api/v1/websockets/manager.py

Runtime orchestration and camera pipeline

Runtime services own application startup/shutdown, camera sessions, pipeline execution, recovery, and inspection. Input/source abstractions permit webcams, RTSP/IP cameras, ESP32 streams, video files, and images without coupling recognition to transport:

• backend/app/services/runtime/startup.py

• backend/app/services/runtime/camera_runtime.py

• backend/app/services/runtime/pipeline.py

• backend/app/sources/factory.py

• backend/app/sources/providers/rtsp.py

Control flow is API request → runtime/orchestrator → source session/frame buffering → AI inference and decisioning → history/events → REST/WebSocket response.

AI recognition and decision layer

Recognition combines face detection, mask analysis, tracking, embeddings, vector search, and temporal decision logic. Model loading and GPU allocation are isolated from inference; the decision engine manages candidate ranking, confidence fusion, unknown detection, thresholds, and session state:

• backend/app/services/ai/inference_engine.py

• backend/app/services/ai/model_manager.py

• backend/app/services/ai/faiss_service.py

• backend/app/services/ai/decision/decision_engine.py

• backend/app/services/ai/decision/state_machine.py

Bundled ONNX and PyTorch artifacts provide offline detector/embedding models, while FAISS persists the identity-search index:

• backend/models/best_yolo.onnx

• backend/models/best_adaface.onnx

• backend/faiss_index.bin

Enrollment, identity persistence, and history

Enrollment orchestrates identity creation/import and embedding-index updates. Database repositories isolate persistence access for cameras, identities, and recognition history, keeping API and AI services storage-agnostic:

• backend/app/services/orchestrators/enrollment_orchestrator.py

• backend/app/services/orchestrators/recognition_orchestrator.py

• backend/app/db/models.py

• backend/app/db/repository/identity_repo.py

• backend/app/db/repository/history_repo.py

ML development subsystem

maskshield-ai is a separate model-development workspace, not the desktop serving path. It prepares and augments datasets, trains/evaluates YOLO and AdaFace models, then exports artifacts that can be deployed under backend/models:

• maskshield-ai/dataset_builder/augmentations/pipeline.py

• maskshield-ai/scripts/train_yolo.py

• maskshield-ai/scripts/train_adaface.py

• maskshield-ai/scripts/export_models.py