# a73720177-design/facr_recognize architecture

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

- Interactive diagram: https://gitdiagram.com/a73720177-design/facr_recognize
- Repository: https://github.com/a73720177-design/facr_recognize

## Overview

This repository implements a local, camera-based two-factor safe: a user selects one of three numbered compartments, passes face identification, then enrolls or verifies an ordered hand/arm-pose pattern. Face registration is a distinct setup stage; ownership and reset rules govern compartment access, while successful pattern verification unlocks the software state only (no physical lock is connected). Edges reflect the sampled callers and README-documented workflow; some storage and menu relationships are documented rather than shown in complete source excerpts.

Main entry points: [`safe_app.py`](https://github.com/a73720177-design/facr_recognize/blob/main/safe_app.py) (Safe session UI), [`face_identity.py`](https://github.com/a73720177-design/facr_recognize/blob/main/face_identity.py) (Face identification), [`recognition.py`](https://github.com/a73720177-design/facr_recognize/blob/main/recognition.py) (Menu and CLI), [`vision_utils.py`](https://github.com/a73720177-design/facr_recognize/blob/main/vision_utils.py) (Pose and hand detectors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and UI"]
  node_cli["Menu and CLI<br/>[recognition.py]"]
  node_session["Safe session UI<br/>[safe_app.py]"]
end

subgraph group_face["Face authentication"]
  node_faceid["Face identification<br/>[face_identity.py]"]
  node_facedata[("Face enrollment data")]
  node_facegate["Face stability gate<br/>[face_gate.py]"]
end

subgraph group_gesture["Gesture authentication"]
  node_landmarks["Pose and hand detectors<br/>[vision_utils.py]"]
  node_posepattern["Pose descriptors<br/>[safe_pattern.py]"]
  node_pattern["Pattern enrollment and check<br/>[safe_pattern.py]"]
end

subgraph group_state["Ownership and state"]
  node_slotstore[("Compartment ownership<br/>[safe_slot.py]")]
  node_slotdata[("Compartment records")]
end

node_user(("Safe user"))
node_camera["Camera feed"]
node_modelhost["Model hosting"]

node_user -->|"selects task"| node_cli
node_cli -->|"starts session"| node_session
node_user -->|"presents face and pose"| node_camera
node_camera -->|"supplies frames"| node_session
node_cli -->|"enrolls face"| node_faceid
node_faceid -->|"reads and writes"| node_facedata
node_session -->|"identifies face"| node_faceid
node_session -->|"confirms identity"| node_facegate
node_session -->|"creates detectors"| node_landmarks
node_landmarks -->|"provides landmarks"| node_posepattern
node_session -->|"extracts pose"| node_posepattern
node_session -->|"updates pattern"| node_pattern
node_pattern -->|"saves samples"| node_slotstore
node_session -->|"checks ownership"| node_slotstore
node_slotstore -->|"reads and writes"| node_slotdata
node_faceid -.->|"downloads face models"| node_modelhost
node_landmarks -.->|"downloads pose models"| node_modelhost
node_session -->|"displays status"| node_user

click node_cli "https://github.com/a73720177-design/facr_recognize/blob/main/recognition.py"
click node_session "https://github.com/a73720177-design/facr_recognize/blob/main/safe_app.py"
click node_faceid "https://github.com/a73720177-design/facr_recognize/blob/main/face_identity.py"
click node_facegate "https://github.com/a73720177-design/facr_recognize/blob/main/face_gate.py"
click node_landmarks "https://github.com/a73720177-design/facr_recognize/blob/main/vision_utils.py"
click node_posepattern "https://github.com/a73720177-design/facr_recognize/blob/main/safe_pattern.py"
click node_pattern "https://github.com/a73720177-design/facr_recognize/blob/main/safe_pattern.py"
click node_slotstore "https://github.com/a73720177-design/facr_recognize/blob/main/safe_slot.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_cli,node_session,node_user toneBlue
class node_faceid,node_facedata,node_facegate toneAmber
class node_landmarks,node_posepattern,node_pattern toneMint
class node_slotstore,node_slotdata toneRose
class node_camera,node_modelhost toneIndigo
```

## Components

### Entry and UI

- [Menu and CLI](https://github.com/a73720177-design/facr_recognize/blob/main/recognition.py): `recognition.py`
- [Safe session UI](https://github.com/a73720177-design/facr_recognize/blob/main/safe_app.py): `safe_app.py`

### Face authentication

- [Face identification](https://github.com/a73720177-design/facr_recognize/blob/main/face_identity.py): `face_identity.py`
- **Face enrollment data**
- [Face stability gate](https://github.com/a73720177-design/facr_recognize/blob/main/face_gate.py): `face_gate.py`

### Gesture authentication

- [Pose and hand detectors](https://github.com/a73720177-design/facr_recognize/blob/main/vision_utils.py): `vision_utils.py`
- [Pose descriptors](https://github.com/a73720177-design/facr_recognize/blob/main/safe_pattern.py): `safe_pattern.py`
- [Pattern enrollment and check](https://github.com/a73720177-design/facr_recognize/blob/main/safe_pattern.py): `safe_pattern.py`

### Ownership and state

- [Compartment ownership](https://github.com/a73720177-design/facr_recognize/blob/main/safe_slot.py): `safe_slot.py`
- **Compartment records**

### Other components

- **Safe user**
- **Camera feed**
- **Model hosting**

## Connections

- Safe user → Menu and CLI: selects task (evidence: `README.md`)
- Menu and CLI → Safe session UI: starts session (evidence: `recognition.py`)
- Safe user → Camera feed: presents face and pose (evidence: `README.md`)
- Camera feed → Safe session UI: supplies frames (evidence: `safe_app.py`)
- Menu and CLI → Face identification: enrolls face (evidence: `recognition.py`)
- Face identification → Face enrollment data: reads and writes (evidence: `face_identity.py`)
- Safe session UI → Face identification: identifies face (evidence: `safe_app.py`)
- Safe session UI → Face stability gate: confirms identity (evidence: `safe_app.py`)
- Safe session UI → Pose and hand detectors: creates detectors (evidence: `safe_app.py`)
- Pose and hand detectors → Pose descriptors: provides landmarks (evidence: `safe_app.py`)
- Safe session UI → Pose descriptors: extracts pose (evidence: `safe_app.py`)
- Safe session UI → Pattern enrollment and check: updates pattern (evidence: `safe_app.py`)
- Pattern enrollment and check → Compartment ownership: saves samples (evidence: `safe_pattern.py`)
- Safe session UI → Compartment ownership: checks ownership (evidence: `safe_app.py`)
- Compartment ownership → Compartment records: reads and writes (evidence: `README.md`)
- Face identification → Model hosting: downloads face models (evidence: `face_identity.py`)
- Pose and hand detectors → Model hosting: downloads pose models (evidence: `vision_utils.py`)
- Safe session UI → Safe user: displays status (evidence: `safe_app.py`)