# saroop7/anti-tamper-vault architecture

> Architecture diagram of the GitHub repository saroop7/anti-tamper-vault, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saroop7/anti-tamper-vault
- Repository: https://github.com/saroop7/anti-tamper-vault

## Overview

This repository implements a Raspberry Pi vault access-control system with a web monitor and registration console, backed by a Node API and PostgreSQL. The main workflow is a person requests access at the device; the Pi checks biometric and time-window conditions, controls the lock, and reports events for the web ledger. A second workflow queues enrollment from the registration page, captures biometrics on the Pi, and records the completed enrollment. Source excerpts and index references support the main links; unsampled hardware-alert and blockchain behavior is shown only where references support it.

Main entry points: [`pi/access_control.py`](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/access_control.py) (Access control loop), [`pi/tamper_monitor.py`](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/tamper_monitor.py) (Tamper monitoring), [`backend/src/index.js`](https://github.com/saroop7/anti-tamper-vault/blob/main/backend/src/index.js) (HTTP API), [`pi/enrollment_worker.py`](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/enrollment_worker.py) (Enrollment worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web console"]
  node_web_monitor["Box monitor<br/>[BoxMonitor.jsx]"]
  node_web_register["User registrations"]
  node_web_live["Live updates<br/>[liveUpdates.js]"]
  node_web_components["Console components"]
end

subgraph group_backend["API and records"]
  node_api["HTTP API<br/>[index.js]"]
  node_event_routes["Event ledger routes<br/>[events.js]"]
  node_user_routes["User routes<br/>[users.js]"]
  node_enroll_routes["Enrollment routes<br/>[enrollments.js]"]
  node_request_routes["Enrollment request routes"]
  node_db[("PostgreSQL records<br/>[db.js]")]
  node_sse["SSE notifications<br/>[sse.js]"]
  node_anchor["Ledger anchoring<br/>[anchor.js]"]
end

subgraph group_device["Vault device"]
  node_access["Access control loop<br/>[access_control.py]"]
  node_auth["Biometric checks"]
  node_face["Face authentication<br/>[face_auth.py]"]
  node_time["Access time window<br/>[time_window.py]"]
  node_gpio["Lock and GPIO<br/>[gpio_io.py]"]
  node_tamper["Tamper monitoring<br/>[tamper_monitor.py]"]
  node_display["Device display<br/>[tft_display.py]"]
  node_rtc["Clock service<br/>[rtc_clock.py]"]
  node_device_config["Device configuration<br/>[config.py]"]
  node_device_client["Event reporting<br/>[backend_client.py]"]
end

subgraph group_enroll["Biometric enrollment"]
  node_enroll_worker["Enrollment worker"]
  node_enroll_logic["Biometric capture"]
  node_enrollment_page["Enrollment console"]
end

node_person(("Vault operator"))
node_sensors["Vault sensors"]
node_sms["SMS alert service"]

node_person -->|"views ledger"| node_web_monitor
node_person -->|"manages enrollment"| node_web_register
node_web_monitor -->|"fetches events"| node_api
node_web_register -->|"requests records"| node_api
node_web_monitor -->|"subscribes"| node_web_live
node_web_register -->|"subscribes"| node_web_live
node_web_monitor -->|"renders"| node_web_components
node_web_register -->|"renders"| node_web_components
node_api -->|"routes to"| node_event_routes
node_api -->|"routes to"| node_user_routes
node_api -->|"routes to"| node_enroll_routes
node_api -->|"routes to"| node_request_routes
node_event_routes -->|"reads and writes"| node_db
node_event_routes -->|"anchors records"| node_anchor
node_event_routes -->|"broadcasts changes"| node_sse
node_user_routes -->|"reads and writes"| node_db
node_enroll_routes -->|"reads and writes"| node_db
node_enroll_routes -->|"broadcasts changes"| node_sse
node_request_routes -->|"queues and updates"| node_db
node_request_routes -->|"broadcasts changes"| node_sse
node_enroll_worker -->|"polls and reports"| node_request_routes
node_enroll_worker -->|"runs capture"| node_enroll_logic
node_enroll_logic -->|"submits enrollment"| node_enroll_routes
node_enrollment_page -->|"queues and cancels"| node_request_routes
node_enrollment_page -->|"loads enrollments"| node_enroll_routes
node_access -->|"checks fingerprint"| node_auth
node_access -->|"checks face"| node_face
node_access -->|"checks schedule"| node_time
node_access -->|"controls lock"| node_gpio
node_access -->|"checks tamper"| node_tamper
node_access -->|"updates display"| node_display
node_auth -.->|"reads biometrics"| node_sensors
node_tamper -.->|"reads tamper state"| node_sensors
node_tamper -->|"logs events"| node_device_client
node_device_client -->|"posts events"| node_event_routes
node_tamper -->|"sends alerts"| node_sms
node_access -->|"reads time"| node_rtc
node_access -->|"uses settings"| node_device_config
node_tamper -->|"reads time"| node_rtc
node_tamper -->|"updates display"| node_display
node_enroll_worker -->|"shows status"| node_display
node_enroll_worker -->|"timestamps status"| node_rtc
node_enroll_worker -->|"uses settings"| node_device_config

click node_web_monitor "https://github.com/saroop7/anti-tamper-vault/blob/main/frontend/src/pages/BoxMonitor.jsx"
click node_web_register "https://github.com/saroop7/anti-tamper-vault/blob/main/frontend/src/pages/UserRegistrations.jsx"
click node_web_live "https://github.com/saroop7/anti-tamper-vault/blob/main/frontend/src/lib/liveUpdates.js"
click node_web_components "https://github.com/saroop7/anti-tamper-vault/tree/main/frontend/src/components"
click node_api "https://github.com/saroop7/anti-tamper-vault/blob/main/backend/src/index.js"
click node_event_routes "https://github.com/saroop7/anti-tamper-vault/blob/main/backend/routes/events.js"
click node_user_routes "https://github.com/saroop7/anti-tamper-vault/blob/main/backend/routes/users.js"
click node_enroll_routes "https://github.com/saroop7/anti-tamper-vault/blob/main/backend/routes/enrollments.js"
click node_request_routes "https://github.com/saroop7/anti-tamper-vault/blob/main/backend/routes/enrollmentRequests.js"
click node_db "https://github.com/saroop7/anti-tamper-vault/blob/main/backend/db.js"
click node_sse "https://github.com/saroop7/anti-tamper-vault/blob/main/backend/sse.js"
click node_anchor "https://github.com/saroop7/anti-tamper-vault/blob/main/backend/anchor.js"
click node_access "https://github.com/saroop7/anti-tamper-vault/blob/main/pi/access_control.py"
click node_auth "https://github.com/saroop7/anti-tamper-vault/blob/main/pi/fingerprint_auth.py"
click node_face "https://github.com/saroop7/anti-tamper-vault/blob/main/pi/face_auth.py"
click node_time "https://github.com/saroop7/anti-tamper-vault/blob/main/pi/time_window.py"
click node_gpio "https://github.com/saroop7/anti-tamper-vault/blob/main/pi/gpio_io.py"
click node_tamper "https://github.com/saroop7/anti-tamper-vault/blob/main/pi/tamper_monitor.py"
click node_display "https://github.com/saroop7/anti-tamper-vault/blob/main/pi/tft_display.py"
click node_rtc "https://github.com/saroop7/anti-tamper-vault/blob/main/pi/rtc_clock.py"
click node_device_config "https://github.com/saroop7/anti-tamper-vault/blob/main/pi/config.py"
click node_device_client "https://github.com/saroop7/anti-tamper-vault/blob/main/pi/backend_client.py"
click node_enroll_worker "https://github.com/saroop7/anti-tamper-vault/blob/main/pi/enrollment_worker.py"
click node_enroll_logic "https://github.com/saroop7/anti-tamper-vault/blob/main/pi/enrollment_logic.py"
click node_enrollment_page "https://github.com/saroop7/anti-tamper-vault/blob/main/frontend/src/pages/UserRegistrations.jsx"

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_web_monitor,node_web_register,node_web_live,node_web_components toneBlue
class node_api,node_event_routes,node_user_routes,node_enroll_routes,node_request_routes,node_db,node_sse,node_anchor toneAmber
class node_access,node_auth,node_face,node_time,node_gpio,node_tamper,node_display,node_rtc,node_device_config,node_device_client toneMint
class node_enroll_worker,node_enroll_logic,node_enrollment_page toneRose
class node_person,node_sensors,node_sms toneIndigo
```

## Components

### Web console

- [Box monitor](https://github.com/saroop7/anti-tamper-vault/blob/main/frontend/src/pages/BoxMonitor.jsx): `frontend/src/pages/BoxMonitor.jsx`
- [User registrations](https://github.com/saroop7/anti-tamper-vault/blob/main/frontend/src/pages/UserRegistrations.jsx): `frontend/src/pages/UserRegistrations.jsx`
- [Live updates](https://github.com/saroop7/anti-tamper-vault/blob/main/frontend/src/lib/liveUpdates.js): `frontend/src/lib/liveUpdates.js`
- [Console components](https://github.com/saroop7/anti-tamper-vault/tree/main/frontend/src/components): `frontend/src/components`

### API and records

- [HTTP API](https://github.com/saroop7/anti-tamper-vault/blob/main/backend/src/index.js): `backend/src/index.js`
- [Event ledger routes](https://github.com/saroop7/anti-tamper-vault/blob/main/backend/routes/events.js): `backend/routes/events.js`
- [User routes](https://github.com/saroop7/anti-tamper-vault/blob/main/backend/routes/users.js): `backend/routes/users.js`
- [Enrollment routes](https://github.com/saroop7/anti-tamper-vault/blob/main/backend/routes/enrollments.js): `backend/routes/enrollments.js`
- [Enrollment request routes](https://github.com/saroop7/anti-tamper-vault/blob/main/backend/routes/enrollmentRequests.js): `backend/routes/enrollmentRequests.js`
- [PostgreSQL records](https://github.com/saroop7/anti-tamper-vault/blob/main/backend/db.js): `backend/db.js`
- [SSE notifications](https://github.com/saroop7/anti-tamper-vault/blob/main/backend/sse.js): `backend/sse.js`
- [Ledger anchoring](https://github.com/saroop7/anti-tamper-vault/blob/main/backend/anchor.js): `backend/anchor.js`

### Vault device

- [Access control loop](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/access_control.py): `pi/access_control.py`
- [Biometric checks](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/fingerprint_auth.py): `pi/fingerprint_auth.py`
- [Face authentication](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/face_auth.py): `pi/face_auth.py`
- [Access time window](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/time_window.py): `pi/time_window.py`
- [Lock and GPIO](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/gpio_io.py): `pi/gpio_io.py`
- [Tamper monitoring](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/tamper_monitor.py): `pi/tamper_monitor.py`
- [Device display](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/tft_display.py): `pi/tft_display.py`
- [Clock service](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/rtc_clock.py): `pi/rtc_clock.py`
- [Device configuration](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/config.py): `pi/config.py`
- [Event reporting](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/backend_client.py): `pi/backend_client.py`

### Biometric enrollment

- [Enrollment worker](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/enrollment_worker.py): `pi/enrollment_worker.py`
- [Biometric capture](https://github.com/saroop7/anti-tamper-vault/blob/main/pi/enrollment_logic.py): `pi/enrollment_logic.py`
- [Enrollment console](https://github.com/saroop7/anti-tamper-vault/blob/main/frontend/src/pages/UserRegistrations.jsx): `frontend/src/pages/UserRegistrations.jsx`

### Other components

- **Vault operator**
- **Vault sensors**
- **SMS alert service**

## Connections

- Vault operator → Box monitor: views ledger (evidence: `frontend/src/pages/BoxMonitor.jsx`)
- Vault operator → User registrations: manages enrollment (evidence: `frontend/src/pages/UserRegistrations.jsx`)
- Box monitor → HTTP API: fetches events (evidence: `frontend/src/pages/BoxMonitor.jsx`)
- User registrations → HTTP API: requests records (evidence: `frontend/src/pages/UserRegistrations.jsx`)
- Box monitor → Live updates: subscribes (evidence: `frontend/src/pages/BoxMonitor.jsx`)
- User registrations → Live updates: subscribes (evidence: `frontend/src/pages/UserRegistrations.jsx`)
- Box monitor → Console components: renders (evidence: `frontend/src/pages/BoxMonitor.jsx`)
- User registrations → Console components: renders (evidence: `frontend/src/pages/UserRegistrations.jsx`)
- HTTP API → Event ledger routes: routes to (evidence: `backend/src/index.js`)
- HTTP API → User routes: routes to (evidence: `backend/src/index.js`)
- HTTP API → Enrollment routes: routes to (evidence: `backend/src/index.js`)
- HTTP API → Enrollment request routes: routes to (evidence: `backend/src/index.js`)
- Event ledger routes → PostgreSQL records: reads and writes (evidence: `backend/routes/events.js`)
- Event ledger routes → Ledger anchoring: anchors records (evidence: `backend/routes/events.js`)
- Event ledger routes → SSE notifications: broadcasts changes (evidence: `backend/routes/events.js`)
- User routes → PostgreSQL records: reads and writes (evidence: `backend/routes/users.js`)
- Enrollment routes → PostgreSQL records: reads and writes (evidence: `backend/routes/enrollments.js`)
- Enrollment routes → SSE notifications: broadcasts changes (evidence: `backend/routes/enrollments.js`)
- Enrollment request routes → PostgreSQL records: queues and updates (evidence: `backend/routes/enrollmentRequests.js`)
- Enrollment request routes → SSE notifications: broadcasts changes (evidence: `backend/routes/enrollmentRequests.js`)
- Enrollment worker → Enrollment request routes: polls and reports (evidence: `pi/enrollment_worker.py`)
- Enrollment worker → Biometric capture: runs capture (evidence: `pi/enrollment_worker.py`)
- Biometric capture → Enrollment routes: submits enrollment (evidence: `pi/enrollment_logic.py`)
- Enrollment console → Enrollment request routes: queues and cancels (evidence: `frontend/src/pages/UserRegistrations.jsx`)
- Enrollment console → Enrollment routes: loads enrollments (evidence: `frontend/src/pages/UserRegistrations.jsx`)
- Access control loop → Biometric checks: checks fingerprint (evidence: `pi/access_control.py`)
- Access control loop → Face authentication: checks face (evidence: `pi/access_control.py`)
- Access control loop → Access time window: checks schedule (evidence: `pi/access_control.py`)
- Access control loop → Lock and GPIO: controls lock (evidence: `pi/access_control.py`)
- Access control loop → Tamper monitoring: checks tamper (evidence: `pi/access_control.py`)
- Access control loop → Device display: updates display (evidence: `pi/access_control.py`)
- Biometric checks → Vault sensors: reads biometrics
- Tamper monitoring → Vault sensors: reads tamper state
- Tamper monitoring → Event reporting: logs events (evidence: `pi/tamper_monitor.py`)
- Event reporting → Event ledger routes: posts events (evidence: `pi/backend_client.py`)
- Tamper monitoring → SMS alert service: sends alerts (evidence: `pi/tamper_monitor.py`)
- Access control loop → Clock service: reads time (evidence: `pi/access_control.py`)
- Access control loop → Device configuration: uses settings (evidence: `pi/access_control.py`)
- Tamper monitoring → Clock service: reads time (evidence: `pi/tamper_monitor.py`)
- Tamper monitoring → Device display: updates display (evidence: `pi/tamper_monitor.py`)
- Enrollment worker → Device display: shows status (evidence: `pi/enrollment_worker.py`)
- Enrollment worker → Clock service: timestamps status (evidence: `pi/enrollment_worker.py`)
- Enrollment worker → Device configuration: uses settings (evidence: `pi/enrollment_worker.py`)
