# taraneshwer/vizage architecture

> Architecture diagram of the GitHub repository taraneshwer/vizage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/taraneshwer/vizage
- Repository: https://github.com/taraneshwer/vizage

## Overview

#### 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`

Main entry points: [`backend/app/api/v1/routers/recognition.py`](https://github.com/taraneshwer/vizage/blob/main/backend/app/api/v1/routers/recognition.py) (Operational APIs), [`frontend/src/utils/api.ts`](https://github.com/taraneshwer/vizage/blob/main/frontend/src/utils/api.ts) (API & WebSocket Client), [`backend/app/main.py`](https://github.com/taraneshwer/vizage/blob/main/backend/app/main.py) (FastAPI App), [`backend/app/services/orchestrators/enrollment_orchestrator.py`](https://github.com/taraneshwer/vizage/blob/main/backend/app/services/orchestrators/enrollment_orchestrator.py) (Enrollment Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Client"]
  node_electron_main["Electron Main<br/>desktop process<br/>[main.ts]"]
  node_backend_manager["Backend Manager<br/>process manager<br/>[backendManager.ts]"]
  node_preload_ipc["Preload &amp; IPC<br/>privileged bridge<br/>[preload.ts]"]
  node_renderer["React Renderer<br/>UI<br/>[App.tsx]"]
  node_client_transport["API &amp; WebSocket Client<br/>client transport<br/>[api.ts]"]
end

subgraph group_api["Backend Control Plane"]
  node_fastapi_app["FastAPI App<br/>application boundary<br/>[main.py]"]
  node_api_routers["Operational APIs<br/>REST routers<br/>[recognition.py]"]
  node_event_bridge["Event Bridge<br/>WebSocket publisher<br/>[event_bridge.py]"]
  node_ws_manager["WebSocket Manager<br/>connection manager<br/>[manager.py]"]
  node_enrollment["Enrollment Orchestrator<br/>identity workflow"]
  node_persistence[("Identity &amp; History Persistence<br/>repositories<br/>[identity_repo.py]")]
end

subgraph group_runtime["Runtime Pipeline"]
  node_runtime_startup["Runtime Startup<br/>lifecycle service<br/>[startup.py]"]
  node_camera_runtime["Camera Runtime<br/>session manager<br/>[camera_runtime.py]"]
  node_pipeline["Recognition Pipeline<br/>pipeline executor<br/>[pipeline.py]"]
  node_source_factory["Source Factory<br/>input abstraction<br/>[factory.py]"]
end

subgraph group_ai["Recognition AI"]
  node_inference_engine["Inference Engine<br/>AI inference"]
  node_model_manager["Model Manager<br/>model runtime<br/>[model_manager.py]"]
  node_decision_engine["Decision Engine<br/>recognition decisioning<br/>[decision_engine.py]"]
  node_faiss_index[("FAISS Identity Index<br/>vector index<br/>[faiss_index.bin]")]
  node_model_artifacts["Offline Model Artifacts<br/>ONNX models<br/>[best_yolo.onnx]"]
end

subgraph group_ml["Model Development"]
  node_ml_training["Training &amp; Export<br/>ML workspace<br/>[export_models.py]"]
end

node_electron_main -->|"manages"| node_backend_manager
node_electron_main -->|"loads"| node_preload_ipc
node_preload_ipc -->|"privileged bridge"| node_renderer
node_renderer -->|"uses"| node_client_transport
node_backend_manager -->|"launches"| node_fastapi_app
node_client_transport -->|"HTTP control"| node_api_routers
node_client_transport -->|"event subscription"| node_ws_manager
node_fastapi_app -->|"mounts"| node_api_routers
node_fastapi_app -->|"lifecycle"| node_runtime_startup
node_api_routers -->|"camera control"| node_camera_runtime
node_api_routers -->|"enrollment requests"| node_enrollment
node_camera_runtime -->|"opens source"| node_source_factory
node_camera_runtime -->|"frames"| node_pipeline
node_pipeline -->|"infer"| node_inference_engine
node_model_manager -->|"provides models"| node_inference_engine
node_model_artifacts -->|"loaded by"| node_model_manager
node_inference_engine -->|"detections and embeddings"| node_decision_engine
node_decision_engine -->|"identity search"| node_faiss_index
node_decision_engine -->|"recognition history"| node_persistence
node_enrollment -->|"identity records"| node_persistence
node_enrollment -->|"updates embeddings"| node_faiss_index
node_pipeline -->|"runtime events"| node_event_bridge
node_event_bridge -->|"broadcasts"| node_ws_manager
node_ml_training -.->|"exports"| node_model_artifacts

click node_electron_main "https://github.com/taraneshwer/vizage/blob/main/frontend/electron/main/main.ts"
click node_backend_manager "https://github.com/taraneshwer/vizage/blob/main/frontend/electron/services/backendManager.ts"
click node_preload_ipc "https://github.com/taraneshwer/vizage/blob/main/frontend/electron/preload/preload.ts"
click node_renderer "https://github.com/taraneshwer/vizage/blob/main/frontend/src/App.tsx"
click node_client_transport "https://github.com/taraneshwer/vizage/blob/main/frontend/src/utils/api.ts"
click node_fastapi_app "https://github.com/taraneshwer/vizage/blob/main/backend/app/main.py"
click node_api_routers "https://github.com/taraneshwer/vizage/blob/main/backend/app/api/v1/routers/recognition.py"
click node_event_bridge "https://github.com/taraneshwer/vizage/blob/main/backend/app/api/v1/websockets/event_bridge.py"
click node_ws_manager "https://github.com/taraneshwer/vizage/blob/main/backend/app/api/v1/websockets/manager.py"
click node_runtime_startup "https://github.com/taraneshwer/vizage/blob/main/backend/app/services/runtime/startup.py"
click node_camera_runtime "https://github.com/taraneshwer/vizage/blob/main/backend/app/services/runtime/camera_runtime.py"
click node_pipeline "https://github.com/taraneshwer/vizage/blob/main/backend/app/services/runtime/pipeline.py"
click node_source_factory "https://github.com/taraneshwer/vizage/blob/main/backend/app/sources/factory.py"
click node_inference_engine "https://github.com/taraneshwer/vizage/blob/main/backend/app/services/ai/inference_engine.py"
click node_model_manager "https://github.com/taraneshwer/vizage/blob/main/backend/app/services/ai/model_manager.py"
click node_decision_engine "https://github.com/taraneshwer/vizage/blob/main/backend/app/services/ai/decision/decision_engine.py"
click node_faiss_index "https://github.com/taraneshwer/vizage/blob/main/backend/faiss_index.bin"
click node_enrollment "https://github.com/taraneshwer/vizage/blob/main/backend/app/services/orchestrators/enrollment_orchestrator.py"
click node_persistence "https://github.com/taraneshwer/vizage/blob/main/backend/app/db/repository/identity_repo.py"
click node_model_artifacts "https://github.com/taraneshwer/vizage/blob/main/backend/models/best_yolo.onnx"
click node_ml_training "https://github.com/taraneshwer/vizage/blob/main/maskshield-ai/scripts/export_models.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_electron_main,node_backend_manager,node_preload_ipc,node_renderer,node_client_transport toneBlue
class node_fastapi_app,node_api_routers,node_event_bridge,node_ws_manager,node_enrollment,node_persistence toneAmber
class node_runtime_startup,node_camera_runtime,node_pipeline,node_source_factory toneMint
class node_inference_engine,node_model_manager,node_decision_engine,node_faiss_index,node_model_artifacts toneRose
class node_ml_training toneIndigo
```

## Components

### Desktop Client

- [Electron Main](https://github.com/taraneshwer/vizage/blob/main/frontend/electron/main/main.ts): desktop process · Starts the desktop app and manages backend lifecycle. · `frontend/electron/main/main.ts`
- [Backend Manager](https://github.com/taraneshwer/vizage/blob/main/frontend/electron/services/backendManager.ts): process manager · Launches and supervises the FastAPI backend. · `frontend/electron/services/backendManager.ts`
- [Preload & IPC](https://github.com/taraneshwer/vizage/blob/main/frontend/electron/preload/preload.ts): privileged bridge · Exposes controlled renderer access to Electron capabilities. · `frontend/electron/preload/preload.ts`
- [React Renderer](https://github.com/taraneshwer/vizage/blob/main/frontend/src/App.tsx): UI · Recognition, enrollment, camera, history, settings, and diagnostics views. · `frontend/src/App.tsx`
- [API & WebSocket Client](https://github.com/taraneshwer/vizage/blob/main/frontend/src/utils/api.ts): client transport · Makes HTTP calls and subscribes to runtime events. · `frontend/src/utils/api.ts`

### Backend Control Plane

- [FastAPI App](https://github.com/taraneshwer/vizage/blob/main/backend/app/main.py): application boundary · Backend entry point served as app.main:app. · `backend/app/main.py`
- [Operational APIs](https://github.com/taraneshwer/vizage/blob/main/backend/app/api/v1/routers/recognition.py): REST routers · Versioned recognition and enrollment control endpoints. · `backend/app/api/v1/routers/recognition.py`
- [Event Bridge](https://github.com/taraneshwer/vizage/blob/main/backend/app/api/v1/websockets/event_bridge.py): WebSocket publisher · Broadcasts runtime events and logs to clients. · `backend/app/api/v1/websockets/event_bridge.py`
- [WebSocket Manager](https://github.com/taraneshwer/vizage/blob/main/backend/app/api/v1/websockets/manager.py): connection manager · Tracks connected WebSocket clients. · `backend/app/api/v1/websockets/manager.py`
- [Enrollment Orchestrator](https://github.com/taraneshwer/vizage/blob/main/backend/app/services/orchestrators/enrollment_orchestrator.py): identity workflow · Creates or imports identities and updates embeddings. · `backend/app/services/orchestrators/enrollment_orchestrator.py`
- [Identity & History Persistence](https://github.com/taraneshwer/vizage/blob/main/backend/app/db/repository/identity_repo.py): repositories · Storage boundary for identities and recognition history. · `backend/app/db/repository/identity_repo.py`

### Runtime Pipeline

- [Runtime Startup](https://github.com/taraneshwer/vizage/blob/main/backend/app/services/runtime/startup.py): lifecycle service · Owns backend startup and shutdown services. · `backend/app/services/runtime/startup.py`
- [Camera Runtime](https://github.com/taraneshwer/vizage/blob/main/backend/app/services/runtime/camera_runtime.py): session manager · Owns camera sessions, buffering, recovery, and inspection. · `backend/app/services/runtime/camera_runtime.py`
- [Recognition Pipeline](https://github.com/taraneshwer/vizage/blob/main/backend/app/services/runtime/pipeline.py): pipeline executor · Runs frames through recognition processing. · `backend/app/services/runtime/pipeline.py`
- [Source Factory](https://github.com/taraneshwer/vizage/blob/main/backend/app/sources/factory.py): input abstraction · Creates webcam, IP, stream, video, and image sources. · `backend/app/sources/factory.py`

### Recognition AI

- [Inference Engine](https://github.com/taraneshwer/vizage/blob/main/backend/app/services/ai/inference_engine.py): AI inference · Runs detection, mask analysis, tracking, and embeddings. · `backend/app/services/ai/inference_engine.py`
- [Model Manager](https://github.com/taraneshwer/vizage/blob/main/backend/app/services/ai/model_manager.py): model runtime · Loads models and isolates GPU allocation. · `backend/app/services/ai/model_manager.py`
- [Decision Engine](https://github.com/taraneshwer/vizage/blob/main/backend/app/services/ai/decision/decision_engine.py): recognition decisioning · Fuses confidence, ranks candidates, and detects unknowns. · `backend/app/services/ai/decision/decision_engine.py`
- [FAISS Identity Index](https://github.com/taraneshwer/vizage/blob/main/backend/faiss_index.bin): vector index · Persistent identity embedding search index. · `backend/faiss_index.bin`
- [Offline Model Artifacts](https://github.com/taraneshwer/vizage/blob/main/backend/models/best_yolo.onnx): ONNX models · Detector and embedding models deployed for serving. · `backend/models/best_yolo.onnx`

### Model Development

Separate workspace that produces deployable model artifacts.

- [Training & Export](https://github.com/taraneshwer/vizage/blob/main/maskshield-ai/scripts/export_models.py): ML workspace · Trains YOLO and AdaFace models and exports serving artifacts. · `maskshield-ai/scripts/export_models.py`

## Connections

- Electron Main → Backend Manager: manages
- Electron Main → Preload & IPC: loads
- Preload & IPC → React Renderer: privileged bridge
- React Renderer → API & WebSocket Client: uses
- Backend Manager → FastAPI App: launches
- API & WebSocket Client → Operational APIs: HTTP control
- API & WebSocket Client → WebSocket Manager: event subscription
- FastAPI App → Operational APIs: mounts
- FastAPI App → Runtime Startup: lifecycle
- Operational APIs → Camera Runtime: camera control
- Operational APIs → Enrollment Orchestrator: enrollment requests
- Camera Runtime → Source Factory: opens source
- Camera Runtime → Recognition Pipeline: frames
- Recognition Pipeline → Inference Engine: infer
- Model Manager → Inference Engine: provides models
- Offline Model Artifacts → Model Manager: loaded by
- Inference Engine → Decision Engine: detections and embeddings
- Decision Engine → FAISS Identity Index: identity search
- Decision Engine → Identity & History Persistence: recognition history
- Enrollment Orchestrator → Identity & History Persistence: identity records
- Enrollment Orchestrator → FAISS Identity Index: updates embeddings
- Recognition Pipeline → Event Bridge: runtime events
- Event Bridge → WebSocket Manager: broadcasts
- Training & Export → Offline Model Artifacts: exports