# dedsec7522/facegate architecture

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

- Interactive diagram: https://gitdiagram.com/dedsec7522/facegate
- Repository: https://github.com/dedsec7522/facegate

## Overview

FaceGate is a self-hosted facial attendance platform. Employees use a camera kiosk or their portal to start a live verification; the backend evaluates face identity and liveness, then records attendance. Administrators manage employees and enrolment, review attendance and reports, and configure verification and attendance rules. The graph preserves these documented capabilities, but several backend routes and frontend pages were not sampled, so their internal calls are omitted or marked unverified.

Main entry points: [`frontend/src/app/router.tsx`](https://github.com/dedsec7522/facegate/blob/main/frontend/src/app/router.tsx) (Route selection), [`frontend/src/lib/api.ts`](https://github.com/dedsec7522/facegate/blob/main/frontend/src/lib/api.ts) (API client), [`backend/app/db/models.py`](https://github.com/dedsec7522/facegate/blob/main/backend/app/db/models.py) (Domain records), [`frontend/src/components/camera/useVerificationStream.ts`](https://github.com/dedsec7522/facegate/blob/main/frontend/src/components/camera/useVerificationStream.ts) (Verification stream)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_router["Route selection<br/>[router.tsx]"]
  node_auth_ui["Session and roles<br/>[auth.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_kiosk["Kiosk workflow<br/>[Kiosk.tsx]"]
  node_camera_ui["Camera capture<br/>[useCamera.ts]"]
  node_stream_ui["Verification stream"]
  node_portal["Employee portal<br/>[Portal.tsx]"]
  node_admin_ui["Admin workspace"]
end

subgraph group_api["API and security"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_admin_api["Admin and employee API<br/>[admin.py]"]
  node_attendance_api["Attendance API<br/>[attendance.py]"]
  node_verify_api["Verification API<br/>[verify.py]"]
end

subgraph group_vision["Face verification"]
  node_vision_pipeline["Vision pipeline<br/>[pipeline.py]"]
  node_face_models["Face detection and embedding<br/>[embedder.py]"]
  node_face_checks["Matching and liveness<br/>[matcher.py]"]
end

subgraph group_domain["Attendance domain"]
  node_enrolment["Face enrolment<br/>[enrolment.py]"]
  node_verification["Session verification<br/>[verification.py]"]
  node_attendance["Attendance rules<br/>[attendance.py]"]
  node_org_settings["Organization settings<br/>[org_settings.py]"]
  node_audit["Audit log<br/>[audit.py]"]
  node_template_index["Template index<br/>[index.py]"]
end

subgraph group_persistence["Persistence"]
  node_db_models["Domain records<br/>[models.py]"]
  node_database[("PostgreSQL<br/>[base.py]")]
end

node_employee(("Employee"))
node_admin_user(("Admin / HR"))
node_camera["Camera access"]

node_employee -->|"opens portal or kiosk"| node_router
node_admin_user -->|"opens admin console"| node_router
node_router -->|"routes kiosk"| node_kiosk
node_router -->|"routes portal"| node_portal
node_router -->|"routes admin pages"| node_admin_ui
node_router -->|"guards routes"| node_auth_ui
node_auth_ui -->|"requests session"| node_api_client
node_kiosk -->|"starts capture"| node_camera_ui
node_camera -->|"provides video"| node_camera_ui
node_kiosk -->|"starts verification"| node_stream_ui
node_stream_ui -->|"grabs frames"| node_camera_ui
node_stream_ui -->|"creates session"| node_api_client
node_stream_ui -->|"streams frames"| node_verify_api
node_portal -->|"requests portal data"| node_api_client
node_admin_ui -.->|"requests admin data"| node_api_client
node_api_client -->|"calls auth routes"| node_auth_api
node_auth_api -->|"reads and writes accounts"| node_db_models
node_auth_api -->|"records auth events"| node_audit
node_verify_api -.->|"manages sessions"| node_verification
node_verification -->|"analyses frames"| node_vision_pipeline
node_vision_pipeline -->|"detects and embeds"| node_face_models
node_vision_pipeline -->|"matches and checks liveness"| node_face_checks
node_verification -.->|"looks up templates"| node_template_index
node_attendance_api -.->|"applies attendance rules"| node_attendance
node_attendance -->|"loads runtime rules"| node_org_settings
node_admin_api -.->|"manages enrolment"| node_enrolment
node_admin_api -.->|"manages settings"| node_org_settings
node_enrolment -.->|"processes face samples"| node_vision_pipeline
node_attendance -->|"reads and records events"| node_db_models
node_org_settings -->|"loads stored settings"| node_db_models
node_db_models -->|"maps persisted records"| node_database
node_template_index -.->|"loads enrolment templates"| node_db_models

click node_router "https://github.com/dedsec7522/facegate/blob/main/frontend/src/app/router.tsx"
click node_auth_ui "https://github.com/dedsec7522/facegate/blob/main/frontend/src/lib/auth.tsx"
click node_api_client "https://github.com/dedsec7522/facegate/blob/main/frontend/src/lib/api.ts"
click node_kiosk "https://github.com/dedsec7522/facegate/blob/main/frontend/src/pages/kiosk/Kiosk.tsx"
click node_camera_ui "https://github.com/dedsec7522/facegate/blob/main/frontend/src/components/camera/useCamera.ts"
click node_stream_ui "https://github.com/dedsec7522/facegate/blob/main/frontend/src/components/camera/useVerificationStream.ts"
click node_portal "https://github.com/dedsec7522/facegate/blob/main/frontend/src/pages/portal/Portal.tsx"
click node_admin_ui "https://github.com/dedsec7522/facegate/tree/main/frontend/src/pages/admin"
click node_auth_api "https://github.com/dedsec7522/facegate/blob/main/backend/app/api/v1/auth.py"
click node_admin_api "https://github.com/dedsec7522/facegate/blob/main/backend/app/api/v1/admin.py"
click node_attendance_api "https://github.com/dedsec7522/facegate/blob/main/backend/app/api/v1/attendance.py"
click node_verify_api "https://github.com/dedsec7522/facegate/blob/main/backend/app/api/v1/verify.py"
click node_enrolment "https://github.com/dedsec7522/facegate/blob/main/backend/app/services/enrolment.py"
click node_verification "https://github.com/dedsec7522/facegate/blob/main/backend/app/services/verification.py"
click node_attendance "https://github.com/dedsec7522/facegate/blob/main/backend/app/services/attendance.py"
click node_org_settings "https://github.com/dedsec7522/facegate/blob/main/backend/app/services/org_settings.py"
click node_audit "https://github.com/dedsec7522/facegate/blob/main/backend/app/services/audit.py"
click node_vision_pipeline "https://github.com/dedsec7522/facegate/blob/main/backend/app/vision/pipeline.py"
click node_face_models "https://github.com/dedsec7522/facegate/blob/main/backend/app/vision/embedder.py"
click node_face_checks "https://github.com/dedsec7522/facegate/blob/main/backend/app/vision/matcher.py"
click node_template_index "https://github.com/dedsec7522/facegate/blob/main/backend/app/services/index.py"
click node_db_models "https://github.com/dedsec7522/facegate/blob/main/backend/app/db/models.py"
click node_database "https://github.com/dedsec7522/facegate/blob/main/backend/app/db/base.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_router,node_auth_ui,node_api_client,node_kiosk,node_camera_ui,node_stream_ui,node_portal,node_admin_ui toneBlue
class node_auth_api,node_admin_api,node_attendance_api,node_verify_api toneAmber
class node_vision_pipeline,node_face_models,node_face_checks toneMint
class node_enrolment,node_verification,node_attendance,node_org_settings,node_audit,node_template_index toneRose
class node_db_models,node_database,node_employee,node_admin_user,node_camera toneIndigo
```

## Components

### Web application

- [Route selection](https://github.com/dedsec7522/facegate/blob/main/frontend/src/app/router.tsx): `frontend/src/app/router.tsx`
- [Session and roles](https://github.com/dedsec7522/facegate/blob/main/frontend/src/lib/auth.tsx): `frontend/src/lib/auth.tsx`
- [API client](https://github.com/dedsec7522/facegate/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Kiosk workflow](https://github.com/dedsec7522/facegate/blob/main/frontend/src/pages/kiosk/Kiosk.tsx): `frontend/src/pages/kiosk/Kiosk.tsx`
- [Camera capture](https://github.com/dedsec7522/facegate/blob/main/frontend/src/components/camera/useCamera.ts): `frontend/src/components/camera/useCamera.ts`
- [Verification stream](https://github.com/dedsec7522/facegate/blob/main/frontend/src/components/camera/useVerificationStream.ts): `frontend/src/components/camera/useVerificationStream.ts`
- [Employee portal](https://github.com/dedsec7522/facegate/blob/main/frontend/src/pages/portal/Portal.tsx): `frontend/src/pages/portal/Portal.tsx`
- [Admin workspace](https://github.com/dedsec7522/facegate/tree/main/frontend/src/pages/admin): `frontend/src/pages/admin`

### API and security

- [Authentication API](https://github.com/dedsec7522/facegate/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [Admin and employee API](https://github.com/dedsec7522/facegate/blob/main/backend/app/api/v1/admin.py): `backend/app/api/v1/admin.py`
- [Attendance API](https://github.com/dedsec7522/facegate/blob/main/backend/app/api/v1/attendance.py): `backend/app/api/v1/attendance.py`
- [Verification API](https://github.com/dedsec7522/facegate/blob/main/backend/app/api/v1/verify.py): `backend/app/api/v1/verify.py`

### Face verification

- [Vision pipeline](https://github.com/dedsec7522/facegate/blob/main/backend/app/vision/pipeline.py): `backend/app/vision/pipeline.py`
- [Face detection and embedding](https://github.com/dedsec7522/facegate/blob/main/backend/app/vision/embedder.py): `backend/app/vision/embedder.py`
- [Matching and liveness](https://github.com/dedsec7522/facegate/blob/main/backend/app/vision/matcher.py): `backend/app/vision/matcher.py`

### Attendance domain

- [Face enrolment](https://github.com/dedsec7522/facegate/blob/main/backend/app/services/enrolment.py): `backend/app/services/enrolment.py`
- [Session verification](https://github.com/dedsec7522/facegate/blob/main/backend/app/services/verification.py): `backend/app/services/verification.py`
- [Attendance rules](https://github.com/dedsec7522/facegate/blob/main/backend/app/services/attendance.py): `backend/app/services/attendance.py`
- [Organization settings](https://github.com/dedsec7522/facegate/blob/main/backend/app/services/org_settings.py): `backend/app/services/org_settings.py`
- [Audit log](https://github.com/dedsec7522/facegate/blob/main/backend/app/services/audit.py): `backend/app/services/audit.py`
- [Template index](https://github.com/dedsec7522/facegate/blob/main/backend/app/services/index.py): `backend/app/services/index.py`

### Persistence

- [Domain records](https://github.com/dedsec7522/facegate/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [PostgreSQL](https://github.com/dedsec7522/facegate/blob/main/backend/app/db/base.py): `backend/app/db/base.py`

### Other components

- **Employee**
- **Admin / HR**
- **Camera access**

## Connections

- Employee → Route selection: opens portal or kiosk (evidence: `README.md`)
- Admin / HR → Route selection: opens admin console (evidence: `README.md`)
- Route selection → Kiosk workflow: routes kiosk (evidence: `frontend/src/app/router.tsx`)
- Route selection → Employee portal: routes portal (evidence: `frontend/src/app/router.tsx`)
- Route selection → Admin workspace: routes admin pages (evidence: `frontend/src/app/router.tsx`)
- Route selection → Session and roles: guards routes (evidence: `frontend/src/app/router.tsx`)
- Session and roles → API client: requests session (evidence: `frontend/src/lib/auth.tsx`)
- Kiosk workflow → Camera capture: starts capture (evidence: `frontend/src/pages/kiosk/Kiosk.tsx`)
- Camera access → Camera capture: provides video (evidence: `frontend/src/components/camera/useCamera.ts`)
- Kiosk workflow → Verification stream: starts verification (evidence: `frontend/src/pages/kiosk/Kiosk.tsx`)
- Verification stream → Camera capture: grabs frames (evidence: `frontend/src/components/camera/useVerificationStream.ts`)
- Verification stream → API client: creates session (evidence: `frontend/src/components/camera/useVerificationStream.ts`)
- Verification stream → Verification API: streams frames (evidence: `frontend/src/components/camera/useVerificationStream.ts`)
- Employee portal → API client: requests portal data (evidence: `frontend/src/pages/portal/Portal.tsx`)
- Admin workspace → API client: requests admin data (evidence: `frontend/src/pages/admin/Attendance.tsx`)
- API client → Authentication API: calls auth routes (evidence: `frontend/src/lib/api.ts`)
- Authentication API → Domain records: reads and writes accounts (evidence: `backend/app/api/v1/auth.py`)
- Authentication API → Audit log: records auth events (evidence: `backend/app/api/v1/auth.py`)
- Verification API → Session verification: manages sessions
- Session verification → Vision pipeline: analyses frames (evidence: `backend/app/services/verification.py`)
- Vision pipeline → Face detection and embedding: detects and embeds (evidence: `backend/app/vision/pipeline.py`)
- Vision pipeline → Matching and liveness: matches and checks liveness (evidence: `backend/app/vision/pipeline.py`)
- Session verification → Template index: looks up templates
- Attendance API → Attendance rules: applies attendance rules
- Attendance rules → Organization settings: loads runtime rules (evidence: `backend/app/services/attendance.py`)
- Admin and employee API → Face enrolment: manages enrolment
- Admin and employee API → Organization settings: manages settings
- Face enrolment → Vision pipeline: processes face samples
- Attendance rules → Domain records: reads and records events (evidence: `backend/app/services/attendance.py`)
- Organization settings → Domain records: loads stored settings (evidence: `backend/app/services/org_settings.py`)
- Domain records → PostgreSQL: maps persisted records (evidence: `backend/app/db/models.py`)
- Template index → Domain records: loads enrolment templates