# lunka81/simsssg architecture

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

- Interactive diagram: https://gitdiagram.com/lunka81/simsssg
- Repository: https://github.com/lunka81/simsssg

## Overview

Smart Access is a prototype face-verification gate: an edge device captures a live face, computes an embedding, asks the backend for an access decision, and actuates a lock. The backend also supports admin authentication, employee enrollment and management, access logs, and a live recognition feed to the React application. The graph includes the separately documented offline model-evaluation capability. Some backend and frontend connections are documented in the README or source index, but their implementation details were not sampled.

Main entry points: [`backend/db/database.py`](https://github.com/lunka81/simsssg/blob/master/backend/db/database.py) (PostgreSQL and pgvector), [`edge-device/services/recognition_service.py`](https://github.com/lunka81/simsssg/blob/master/edge-device/services/recognition_service.py) (Face, liveness, embedding), [`backend/routes/recognition_routes.py`](https://github.com/lunka81/simsssg/blob/master/backend/routes/recognition_routes.py) (Identify endpoint), [`backend/app/app.py`](https://github.com/lunka81/simsssg/blob/master/backend/app/app.py) (API application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge access device"]
  node_camera["Camera capture<br/>[camera.py]"]
  node_face_pipeline["Face, liveness, embedding"]
  node_edge_models["Edge vision models"]
  node_uploader["Decision uploader<br/>[uploader.py]"]
  node_lock["Lock and LEDs<br/>[lock.py]"]
  node_fake_lock["Simulated lock<br/>[fake_lock.py]"]
  node_edge_config["Device configuration<br/>[config.py]"]
end

subgraph group_backend["Backend and recognition"]
  node_backend_app["API application<br/>[app.py]"]
  node_identify["Identify endpoint"]
  node_comparison["Match and decision"]
  node_enrollment["Employee enrollment"]
  node_image_processing["Image embedding<br/>[img_services.py]"]
  node_employee_api["Employee API<br/>[employee_routes.py]"]
  node_auth["Admin authentication<br/>[auth_services.py]"]
  node_admin_api["Admin login API"]
  node_log_api["Access log API"]
  node_log_service["Access log service"]
  node_websocket["Recognition WebSocket"]
  node_database[("PostgreSQL and pgvector<br/>[database.py]")]
  node_employee_model["Employee records<br/>[employee.py]"]
  node_admin_model["Admin records<br/>[admin.py]"]
  node_log_model["Access log records<br/>[employee_log.py]"]
end

subgraph group_admin["Admin web application"]
  node_frontend_app["Web app routes<br/>[App.tsx]"]
  node_access_view["Live access view"]
  node_admin_views["Admin console"]
  node_frontend_auth["Frontend auth<br/>[auth.ts]"]
  node_employee_client["Employee API client<br/>[employees.ts]"]
end

subgraph group_evaluation["Model evaluation"]
  node_evaluation_pipeline["Evaluation pipeline"]
  node_evaluation_models["Evaluation models<br/>[models.py]"]
  node_evaluation_results["Evaluation presentation"]
end

node_visitor(("Gate visitor"))
node_evaluator(("Model evaluator"))

node_visitor -->|"approaches gate"| node_camera
node_camera -->|"supplies frames"| node_face_pipeline
node_face_pipeline -->|"uses models"| node_edge_models
node_face_pipeline -->|"sends embedding"| node_uploader
node_uploader -->|"posts embedding"| node_identify
node_identify -->|"requests decision"| node_comparison
node_comparison -->|"searches matches"| node_database
node_comparison -->|"logs approval"| node_log_service
node_identify -->|"pushes result"| node_websocket
node_identify -->|"loads matched employee"| node_employee_model
node_websocket -->|"streams recognition"| node_access_view
node_identify -->|"returns decision"| node_lock
node_face_pipeline -->|"actuates decision"| node_lock
node_face_pipeline -->|"selects in demo mode"| node_fake_lock
node_edge_config -->|"configures runtime"| node_face_pipeline
node_backend_app -->|"registers route"| node_identify
node_backend_app -->|"registers route"| node_employee_api
node_backend_app -->|"registers route"| node_admin_api
node_backend_app -->|"registers route"| node_log_api
node_employee_api -->|"delegates operations"| node_enrollment
node_enrollment -->|"extracts embedding"| node_image_processing
node_enrollment -->|"stores employees"| node_database
node_image_processing -.->|"uses backend models"| node_edge_models
node_employee_api -->|"requires token"| node_auth
node_admin_api -->|"handles login"| node_auth
node_auth -->|"reads admin"| node_database
node_log_api -->|"delegates log access"| node_log_service
node_log_service -->|"reads and writes logs"| node_database
node_database -->|"stores"| node_employee_model
node_database -->|"stores"| node_admin_model
node_database -->|"stores"| node_log_model
node_frontend_app -->|"routes to"| node_access_view
node_frontend_app -->|"routes to"| node_admin_views
node_admin_views -.->|"uses employee API"| node_employee_client
node_employee_client -.->|"calls REST API"| node_employee_api
node_frontend_auth -.->|"authenticates via REST"| node_admin_api
node_evaluator -->|"runs evaluation"| node_evaluation_pipeline
node_evaluation_pipeline -->|"uses model definitions"| node_evaluation_models
node_evaluation_pipeline -.->|"presents results"| node_evaluation_results

click node_camera "https://github.com/lunka81/simsssg/blob/master/edge-device/camera/camera.py"
click node_face_pipeline "https://github.com/lunka81/simsssg/blob/master/edge-device/services/recognition_service.py"
click node_edge_models "https://github.com/lunka81/simsssg/tree/master/edge-device/recognition"
click node_uploader "https://github.com/lunka81/simsssg/blob/master/edge-device/clients/uploader.py"
click node_lock "https://github.com/lunka81/simsssg/blob/master/edge-device/hardware/lock.py"
click node_fake_lock "https://github.com/lunka81/simsssg/blob/master/edge-device/hardware/fake_lock.py"
click node_edge_config "https://github.com/lunka81/simsssg/blob/master/edge-device/config/config.py"
click node_backend_app "https://github.com/lunka81/simsssg/blob/master/backend/app/app.py"
click node_identify "https://github.com/lunka81/simsssg/blob/master/backend/routes/recognition_routes.py"
click node_comparison "https://github.com/lunka81/simsssg/blob/master/backend/services/comparison_services.py"
click node_enrollment "https://github.com/lunka81/simsssg/blob/master/backend/services/employee_services.py"
click node_image_processing "https://github.com/lunka81/simsssg/blob/master/backend/services/img_services.py"
click node_employee_api "https://github.com/lunka81/simsssg/blob/master/backend/routes/employee_routes.py"
click node_auth "https://github.com/lunka81/simsssg/blob/master/backend/services/auth_services.py"
click node_admin_api "https://github.com/lunka81/simsssg/blob/master/backend/routes/admin_login_routes.py"
click node_log_api "https://github.com/lunka81/simsssg/blob/master/backend/routes/employee_log_routes.py"
click node_log_service "https://github.com/lunka81/simsssg/blob/master/backend/services/employee_log_services.py"
click node_websocket "https://github.com/lunka81/simsssg/blob/master/backend/services/recognition_socket.py"
click node_database "https://github.com/lunka81/simsssg/blob/master/backend/db/database.py"
click node_employee_model "https://github.com/lunka81/simsssg/blob/master/backend/models/employee.py"
click node_admin_model "https://github.com/lunka81/simsssg/blob/master/backend/models/admin.py"
click node_log_model "https://github.com/lunka81/simsssg/blob/master/backend/models/employee_log.py"
click node_frontend_app "https://github.com/lunka81/simsssg/blob/master/frontend/src/App.tsx"
click node_access_view "https://github.com/lunka81/simsssg/tree/master/frontend/src/pages/Home"
click node_admin_views "https://github.com/lunka81/simsssg/tree/master/frontend/src/pages/Admin"
click node_frontend_auth "https://github.com/lunka81/simsssg/blob/master/frontend/src/auth.ts"
click node_employee_client "https://github.com/lunka81/simsssg/blob/master/frontend/src/api/employees.ts"
click node_evaluation_pipeline "https://github.com/lunka81/simsssg/tree/master/model-evaluation/pipeline"
click node_evaluation_models "https://github.com/lunka81/simsssg/blob/master/model-evaluation/pipeline/models.py"
click node_evaluation_results "https://github.com/lunka81/simsssg/tree/master/model-evaluation/presentation"

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_camera,node_face_pipeline,node_edge_models,node_uploader,node_lock,node_fake_lock,node_edge_config toneBlue
class node_backend_app,node_identify,node_comparison,node_enrollment,node_image_processing,node_employee_api,node_auth,node_admin_api,node_log_api,node_log_service,node_websocket,node_database,node_employee_model,node_admin_model,node_log_model toneAmber
class node_frontend_app,node_access_view,node_admin_views,node_frontend_auth,node_employee_client toneMint
class node_evaluation_pipeline,node_evaluation_models,node_evaluation_results toneRose
class node_visitor,node_evaluator toneIndigo
```

## Components

### Edge access device

- [Camera capture](https://github.com/lunka81/simsssg/blob/master/edge-device/camera/camera.py): `edge-device/camera/camera.py`
- [Face, liveness, embedding](https://github.com/lunka81/simsssg/blob/master/edge-device/services/recognition_service.py): `edge-device/services/recognition_service.py`
- [Edge vision models](https://github.com/lunka81/simsssg/tree/master/edge-device/recognition): `edge-device/recognition`
- [Decision uploader](https://github.com/lunka81/simsssg/blob/master/edge-device/clients/uploader.py): `edge-device/clients/uploader.py`
- [Lock and LEDs](https://github.com/lunka81/simsssg/blob/master/edge-device/hardware/lock.py): `edge-device/hardware/lock.py`
- [Simulated lock](https://github.com/lunka81/simsssg/blob/master/edge-device/hardware/fake_lock.py): `edge-device/hardware/fake_lock.py`
- [Device configuration](https://github.com/lunka81/simsssg/blob/master/edge-device/config/config.py): `edge-device/config/config.py`

### Backend and recognition

- [API application](https://github.com/lunka81/simsssg/blob/master/backend/app/app.py): `backend/app/app.py`
- [Identify endpoint](https://github.com/lunka81/simsssg/blob/master/backend/routes/recognition_routes.py): `backend/routes/recognition_routes.py`
- [Match and decision](https://github.com/lunka81/simsssg/blob/master/backend/services/comparison_services.py): `backend/services/comparison_services.py`
- [Employee enrollment](https://github.com/lunka81/simsssg/blob/master/backend/services/employee_services.py): `backend/services/employee_services.py`
- [Image embedding](https://github.com/lunka81/simsssg/blob/master/backend/services/img_services.py): `backend/services/img_services.py`
- [Employee API](https://github.com/lunka81/simsssg/blob/master/backend/routes/employee_routes.py): `backend/routes/employee_routes.py`
- [Admin authentication](https://github.com/lunka81/simsssg/blob/master/backend/services/auth_services.py): `backend/services/auth_services.py`
- [Admin login API](https://github.com/lunka81/simsssg/blob/master/backend/routes/admin_login_routes.py): `backend/routes/admin_login_routes.py`
- [Access log API](https://github.com/lunka81/simsssg/blob/master/backend/routes/employee_log_routes.py): `backend/routes/employee_log_routes.py`
- [Access log service](https://github.com/lunka81/simsssg/blob/master/backend/services/employee_log_services.py): `backend/services/employee_log_services.py`
- [Recognition WebSocket](https://github.com/lunka81/simsssg/blob/master/backend/services/recognition_socket.py): `backend/services/recognition_socket.py`
- [PostgreSQL and pgvector](https://github.com/lunka81/simsssg/blob/master/backend/db/database.py): `backend/db/database.py`
- [Employee records](https://github.com/lunka81/simsssg/blob/master/backend/models/employee.py): `backend/models/employee.py`
- [Admin records](https://github.com/lunka81/simsssg/blob/master/backend/models/admin.py): `backend/models/admin.py`
- [Access log records](https://github.com/lunka81/simsssg/blob/master/backend/models/employee_log.py): `backend/models/employee_log.py`

### Admin web application

- [Web app routes](https://github.com/lunka81/simsssg/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Live access view](https://github.com/lunka81/simsssg/tree/master/frontend/src/pages/Home): `frontend/src/pages/Home`
- [Admin console](https://github.com/lunka81/simsssg/tree/master/frontend/src/pages/Admin): `frontend/src/pages/Admin`
- [Frontend auth](https://github.com/lunka81/simsssg/blob/master/frontend/src/auth.ts): `frontend/src/auth.ts`
- [Employee API client](https://github.com/lunka81/simsssg/blob/master/frontend/src/api/employees.ts): `frontend/src/api/employees.ts`

### Model evaluation

- [Evaluation pipeline](https://github.com/lunka81/simsssg/tree/master/model-evaluation/pipeline): `model-evaluation/pipeline`
- [Evaluation models](https://github.com/lunka81/simsssg/blob/master/model-evaluation/pipeline/models.py): `model-evaluation/pipeline/models.py`
- [Evaluation presentation](https://github.com/lunka81/simsssg/tree/master/model-evaluation/presentation): `model-evaluation/presentation`

### Other components

- **Gate visitor**
- **Model evaluator**

## Connections

- Gate visitor → Camera capture: approaches gate (evidence: `README.md`)
- Camera capture → Face, liveness, embedding: supplies frames (evidence: `edge-device/services/recognition_service.py`)
- Face, liveness, embedding → Edge vision models: uses models (evidence: `edge-device/services/recognition_service.py`)
- Face, liveness, embedding → Decision uploader: sends embedding (evidence: `edge-device/services/recognition_service.py`)
- Decision uploader → Identify endpoint: posts embedding (evidence: `README.md`)
- Identify endpoint → Match and decision: requests decision (evidence: `backend/routes/recognition_routes.py`)
- Match and decision → PostgreSQL and pgvector: searches matches (evidence: `README.md`)
- Match and decision → Access log service: logs approval (evidence: `backend/services/comparison_services.py`)
- Identify endpoint → Recognition WebSocket: pushes result (evidence: `backend/routes/recognition_routes.py`)
- Identify endpoint → Employee records: loads matched employee (evidence: `backend/routes/recognition_routes.py`)
- Recognition WebSocket → Live access view: streams recognition (evidence: `README.md`)
- Identify endpoint → Lock and LEDs: returns decision (evidence: `README.md`)
- Face, liveness, embedding → Lock and LEDs: actuates decision (evidence: `edge-device/services/recognition_service.py`)
- Face, liveness, embedding → Simulated lock: selects in demo mode (evidence: `edge-device/services/recognition_service.py`)
- Device configuration → Face, liveness, embedding: configures runtime (evidence: `edge-device/services/recognition_service.py`)
- API application → Identify endpoint: registers route (evidence: `backend/app/app.py`)
- API application → Employee API: registers route (evidence: `backend/app/app.py`)
- API application → Admin login API: registers route (evidence: `backend/app/app.py`)
- API application → Access log API: registers route (evidence: `backend/app/app.py`)
- Employee API → Employee enrollment: delegates operations (evidence: `backend/routes/employee_routes.py`)
- Employee enrollment → Image embedding: extracts embedding (evidence: `backend/services/employee_services.py`)
- Employee enrollment → PostgreSQL and pgvector: stores employees (evidence: `backend/services/employee_services.py`)
- Image embedding → Edge vision models: uses backend models
- Employee API → Admin authentication: requires token (evidence: `backend/routes/employee_routes.py`)
- Admin login API → Admin authentication: handles login (evidence: `backend/routes/admin_login_routes.py`)
- Admin authentication → PostgreSQL and pgvector: reads admin (evidence: `backend/services/auth_services.py`)
- Access log API → Access log service: delegates log access (evidence: `backend/routes/employee_log_routes.py`)
- Access log service → PostgreSQL and pgvector: reads and writes logs (evidence: `backend/services/employee_log_services.py`)
- PostgreSQL and pgvector → Employee records: stores (evidence: `backend/models/employee.py`)
- PostgreSQL and pgvector → Admin records: stores (evidence: `backend/models/admin.py`)
- PostgreSQL and pgvector → Access log records: stores (evidence: `backend/models/employee_log.py`)
- Web app routes → Live access view: routes to (evidence: `frontend/src/App.tsx`)
- Web app routes → Admin console: routes to (evidence: `frontend/src/App.tsx`)
- Admin console → Employee API client: uses employee API
- Employee API client → Employee API: calls REST API
- Frontend auth → Admin login API: authenticates via REST (evidence: `README.md`)
- Model evaluator → Evaluation pipeline: runs evaluation (evidence: `README.md`)
- Evaluation pipeline → Evaluation models: uses model definitions (evidence: `model-evaluation/pipeline/__main__.py`)
- Evaluation pipeline → Evaluation presentation: presents results
