# dominic62q/zkteco-localhost-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/dominic62q/zkteco-localhost-bridge
- Repository: https://github.com/dominic62q/zkteco-localhost-bridge

## Overview

This is a local fingerprint test app and reusable localhost bridge: a React UI initiates enrolment or verification, the bridge coordinates the USB reader and vendor SDK, and enrolled users/templates persist in encrypted SQLite storage. The bridge also exposes app-agnostic capture, merge, verify, and identify operations for other authorized clients. The graph follows the documented API and sampled call sites; some route wiring and service internals were not included in the excerpts, so uncertain links are omitted.

Main entry points: [`bridge/Program.cs`](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Program.cs) (HTTP routes), [`bridge/Services/EnrolManager.cs`](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/EnrolManager.cs) (Enrol sessions), [`bridge/Services/VerifyManager.cs`](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/VerifyManager.cs) (Verify sessions), [`bridge/Services/ZkFingerService.cs`](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/ZkFingerService.cs) (SDK service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Test UI"]
  node_app["Test interface<br/>[App.tsx]"]
  node_cards["Enrol / verify UI"]
  node_client["API client<br/>[client.ts]"]
end

subgraph group_api["Bridge API"]
  node_http["HTTP routes<br/>[Program.cs]"]
  node_auth["Token auth<br/>[TokenAuth.cs]"]
end

subgraph group_biometrics["Fingerprint operations"]
  node_enrol["Enrol sessions<br/>[EnrolManager.cs]"]
  node_verify["Verify sessions<br/>[VerifyManager.cs]"]
  node_capture["Generic operations<br/>[CaptureService.cs]"]
  node_gate["Capture gate<br/>[CaptureGate.cs]"]
  node_poller["Device polling<br/>[DevicePoller.cs]"]
  node_zk["SDK service<br/>[ZkFingerService.cs]"]
end

subgraph group_storage["Local data"]
  node_protection["Template protection"]
  node_store["User and template store<br/>[Store.cs]"]
  node_sqlite[("SQLite database")]
end

node_person(("User / app"))
node_sdk["ZKFinger SDK"]
node_reader["USB reader"]

node_person -->|"uses"| node_app
node_app -->|"shows"| node_cards
node_app -->|"polls / requests"| node_client
node_cards -->|"starts / polls"| node_client
node_client -->|"HTTP requests"| node_http
node_http -->|"passes through"| node_auth
node_http -->|"starts / reads"| node_enrol
node_http -->|"starts / reads"| node_verify
node_http -->|"dispatches v1"| node_capture
node_http -->|"reads / deletes"| node_store
node_http -->|"reads status"| node_zk
node_enrol -->|"acquires"| node_gate
node_verify -->|"acquires"| node_gate
node_capture -->|"acquires"| node_gate
node_enrol -->|"uses reader"| node_zk
node_verify -->|"uses reader"| node_zk
node_capture -->|"captures"| node_zk
node_poller -->|"refreshes cache"| node_zk
node_zk -->|"calls"| node_sdk
node_sdk -->|"controls"| node_reader
node_enrol -->|"matches / merges"| node_sdk
node_verify -->|"matches"| node_sdk
node_capture -->|"merges / identifies"| node_sdk
node_enrol -->|"loads / saves"| node_store
node_verify -->|"loads template"| node_store
node_enrol -->|"encrypts template"| node_protection
node_verify -->|"decrypts template"| node_protection
node_store -->|"reads / writes"| node_sqlite

click node_app "https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/frontend/src/App.tsx"
click node_cards "https://github.com/dominic62q/zkteco-localhost-bridge/tree/main/frontend/src/components"
click node_client "https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/frontend/src/api/client.ts"
click node_http "https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Program.cs"
click node_auth "https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Middleware/TokenAuth.cs"
click node_enrol "https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/EnrolManager.cs"
click node_verify "https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/VerifyManager.cs"
click node_capture "https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/CaptureService.cs"
click node_gate "https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/CaptureGate.cs"
click node_poller "https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/DevicePoller.cs"
click node_zk "https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/ZkFingerService.cs"
click node_protection "https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/TemplateProtection.cs"
click node_store "https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Data/Store.cs"
click node_sqlite "https://github.com/dominic62q/zkteco-localhost-bridge/tree/main/data"

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_app,node_cards,node_client,node_person toneBlue
class node_http,node_auth toneAmber
class node_enrol,node_verify,node_capture,node_gate,node_poller,node_zk toneMint
class node_protection,node_store,node_sqlite toneRose
class node_sdk,node_reader toneIndigo
```

## Components

### Test UI

- [Test interface](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Enrol / verify UI](https://github.com/dominic62q/zkteco-localhost-bridge/tree/main/frontend/src/components): `frontend/src/components`
- [API client](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Bridge API

- [HTTP routes](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Program.cs): `bridge/Program.cs`
- [Token auth](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Middleware/TokenAuth.cs): `bridge/Middleware/TokenAuth.cs`

### Fingerprint operations

- [Enrol sessions](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/EnrolManager.cs): `bridge/Services/EnrolManager.cs`
- [Verify sessions](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/VerifyManager.cs): `bridge/Services/VerifyManager.cs`
- [Generic operations](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/CaptureService.cs): `bridge/Services/CaptureService.cs`
- [Capture gate](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/CaptureGate.cs): `bridge/Services/CaptureGate.cs`
- [Device polling](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/DevicePoller.cs): `bridge/Services/DevicePoller.cs`
- [SDK service](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/ZkFingerService.cs): `bridge/Services/ZkFingerService.cs`

### Local data

- [Template protection](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Services/TemplateProtection.cs): `bridge/Services/TemplateProtection.cs`
- [User and template store](https://github.com/dominic62q/zkteco-localhost-bridge/blob/main/bridge/Data/Store.cs): `bridge/Data/Store.cs`
- [SQLite database](https://github.com/dominic62q/zkteco-localhost-bridge/tree/main/data): `data`

### Other components

- **User / app**
- **ZKFinger SDK**
- **USB reader**

## Connections

- User / app → Test interface: uses
- Test interface → Enrol / verify UI: shows
- Test interface → API client: polls / requests
- Enrol / verify UI → API client: starts / polls
- API client → HTTP routes: HTTP requests
- HTTP routes → Token auth: passes through
- HTTP routes → Enrol sessions: starts / reads
- HTTP routes → Verify sessions: starts / reads
- HTTP routes → Generic operations: dispatches v1
- HTTP routes → User and template store: reads / deletes
- HTTP routes → SDK service: reads status
- Enrol sessions → Capture gate: acquires
- Verify sessions → Capture gate: acquires
- Generic operations → Capture gate: acquires
- Enrol sessions → SDK service: uses reader
- Verify sessions → SDK service: uses reader
- Generic operations → SDK service: captures
- Device polling → SDK service: refreshes cache
- SDK service → ZKFinger SDK: calls
- ZKFinger SDK → USB reader: controls
- Enrol sessions → ZKFinger SDK: matches / merges
- Verify sessions → ZKFinger SDK: matches
- Generic operations → ZKFinger SDK: merges / identifies
- Enrol sessions → User and template store: loads / saves
- Verify sessions → User and template store: loads template
- Enrol sessions → Template protection: encrypts template
- Verify sessions → Template protection: decrypts template
- User and template store → SQLite database: reads / writes