# stephenkhytze/verifigate architecture

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

- Interactive diagram: https://gitdiagram.com/stephenkhytze/verifigate
- Repository: https://github.com/stephenkhytze/verifigate

## Overview

VeriGate is a school gate ID-scanning system. A camera capture worker crops an ID and sends it to Laravel; Laravel calls OCR, matches identity, routes the scan into a gate event, and exposes the result to guard and student-facing monitors. Guards can search, manually identify, and decide pending events. The README documents these capabilities and service boundaries; several internal services are unsampled, so their detailed call relationships are not asserted.

Main entry points: [`web/app/Services/IdScan/ScanProcessor.php`](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Services/IdScan/ScanProcessor.php) (Scan processor), [`web/app/Models/GateEvent.php`](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Models/GateEvent.php) (Gate events), [`web/app/Http/Controllers/Station/GuardActionsController.php`](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Http/Controllers/Station/GuardActionsController.php) (Guard endpoints), [`web/resources/js/pages/gate/guard.tsx`](https://github.com/stephenkhytze/verifigate/blob/master/web/resources/js/pages/gate/guard.tsx) (Guard monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and OCR"]
  node_worker["ID capture worker<br/>[capture.py]"]
  node_ocr["OCR service<br/>[main.py]"]
end

subgraph group_gate["Gate processing"]
  node_station["Station scan endpoint"]
  node_processor["Scan processor<br/>[ScanProcessor.php]"]
  node_ocrclient["OCR client<br/>[OcrClient.php]"]
  node_matcher["Identity matching"]
  node_router["Scan routing<br/>[ScanRouter.php]"]
  node_events[("Gate events<br/>[GateEvent.php]")]
  node_people[("People records<br/>[Student.php]")]
  node_uniform["Uniform provider"]
end

subgraph group_review["Guard operations"]
  node_guard_api["Guard endpoints"]
  node_decision["Guard decisions"]
  node_state["Gate state endpoints"]
  node_image["ID image endpoint"]
end

subgraph group_screens["Gate screens"]
  node_guard_screen["Guard monitor<br/>[guard.tsx]"]
  node_student_screen["Student monitor<br/>[screen.tsx]"]
  node_gate_ui["Gate UI components"]
end

node_camera(("Camera"))
node_guard(("Guard"))
node_database[("Application database")]

node_camera -->|"captures image"| node_worker
node_worker -->|"posts crop"| node_station
node_station -.->|"processes scan"| node_processor
node_processor -.->|"requests OCR"| node_ocrclient
node_ocrclient -->|"sends image"| node_ocr
node_processor -.->|"matches identity"| node_matcher
node_processor -->|"routes scan"| node_router
node_processor -.->|"checks uniform"| node_uniform
node_processor -->|"writes event"| node_events
node_matcher -->|"matches records"| node_people
node_router -->|"decides status"| node_events
node_guard -->|"searches or identifies"| node_guard_api
node_guard_api -->|"searches records"| node_people
node_guard_api -->|"creates or updates"| node_events
node_guard -->|"approves or denies"| node_decision
node_decision -->|"updates status"| node_events
node_guard_screen -->|"polls guard state"| node_state
node_student_screen -->|"polls screen state"| node_state
node_guard_screen -.->|"uses guard actions"| node_guard_api
node_guard_screen -->|"renders components"| node_gate_ui
node_state -->|"reads events"| node_events
node_events -->|"persists events"| node_database
node_people -.->|"stores records"| node_database
node_image -->|"fetches crop"| node_worker

click node_worker "https://github.com/stephenkhytze/verifigate/blob/master/python/services/id-capture/capture.py"
click node_ocr "https://github.com/stephenkhytze/verifigate/blob/master/python/services/id-ocr/app/main.py"
click node_station "https://github.com/stephenkhytze/verifigate/blob/master/web/app/Http/Controllers/Station/StationScanController.php"
click node_processor "https://github.com/stephenkhytze/verifigate/blob/master/web/app/Services/IdScan/ScanProcessor.php"
click node_ocrclient "https://github.com/stephenkhytze/verifigate/blob/master/web/app/Services/IdScan/OcrClient.php"
click node_matcher "https://github.com/stephenkhytze/verifigate/blob/master/web/app/Services/IdScan/IdentityMatcher.php"
click node_router "https://github.com/stephenkhytze/verifigate/blob/master/web/app/Services/IdScan/ScanRouter.php"
click node_events "https://github.com/stephenkhytze/verifigate/blob/master/web/app/Models/GateEvent.php"
click node_people "https://github.com/stephenkhytze/verifigate/blob/master/web/app/Models/Student.php"
click node_uniform "https://github.com/stephenkhytze/verifigate/blob/master/web/app/Services/IdScan/UniformProvider.php"
click node_guard_api "https://github.com/stephenkhytze/verifigate/blob/master/web/app/Http/Controllers/Station/GuardActionsController.php"
click node_decision "https://github.com/stephenkhytze/verifigate/blob/master/web/app/Http/Controllers/Station/GuardDecisionController.php"
click node_state "https://github.com/stephenkhytze/verifigate/blob/master/web/app/Http/Controllers/Station/GateStateController.php"
click node_image "https://github.com/stephenkhytze/verifigate/blob/master/web/app/Http/Controllers/Station/IdImageController.php"
click node_guard_screen "https://github.com/stephenkhytze/verifigate/blob/master/web/resources/js/pages/gate/guard.tsx"
click node_student_screen "https://github.com/stephenkhytze/verifigate/blob/master/web/resources/js/pages/gate/screen.tsx"
click node_gate_ui "https://github.com/stephenkhytze/verifigate/tree/master/web/resources/js/components/gate"

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_worker,node_ocr toneBlue
class node_station,node_processor,node_ocrclient,node_matcher,node_router,node_events,node_people,node_uniform,node_database toneAmber
class node_guard_api,node_decision,node_state,node_image toneMint
class node_guard_screen,node_student_screen,node_gate_ui toneRose
class node_camera,node_guard toneIndigo
```

## Components

### Capture and OCR

- [ID capture worker](https://github.com/stephenkhytze/verifigate/blob/master/python/services/id-capture/capture.py): `python/services/id-capture/capture.py`
- [OCR service](https://github.com/stephenkhytze/verifigate/blob/master/python/services/id-ocr/app/main.py): `python/services/id-ocr/app/main.py`

### Gate processing

- [Station scan endpoint](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Http/Controllers/Station/StationScanController.php): `web/app/Http/Controllers/Station/StationScanController.php`
- [Scan processor](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Services/IdScan/ScanProcessor.php): `web/app/Services/IdScan/ScanProcessor.php`
- [OCR client](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Services/IdScan/OcrClient.php): `web/app/Services/IdScan/OcrClient.php`
- [Identity matching](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Services/IdScan/IdentityMatcher.php): `web/app/Services/IdScan/IdentityMatcher.php`
- [Scan routing](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Services/IdScan/ScanRouter.php): `web/app/Services/IdScan/ScanRouter.php`
- [Gate events](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Models/GateEvent.php): `web/app/Models/GateEvent.php`
- [People records](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Models/Student.php): `web/app/Models/Student.php`
- [Uniform provider](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Services/IdScan/UniformProvider.php): `web/app/Services/IdScan/UniformProvider.php`

### Guard operations

- [Guard endpoints](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Http/Controllers/Station/GuardActionsController.php): `web/app/Http/Controllers/Station/GuardActionsController.php`
- [Guard decisions](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Http/Controllers/Station/GuardDecisionController.php): `web/app/Http/Controllers/Station/GuardDecisionController.php`
- [Gate state endpoints](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Http/Controllers/Station/GateStateController.php): `web/app/Http/Controllers/Station/GateStateController.php`
- [ID image endpoint](https://github.com/stephenkhytze/verifigate/blob/master/web/app/Http/Controllers/Station/IdImageController.php): `web/app/Http/Controllers/Station/IdImageController.php`

### Gate screens

- [Guard monitor](https://github.com/stephenkhytze/verifigate/blob/master/web/resources/js/pages/gate/guard.tsx): `web/resources/js/pages/gate/guard.tsx`
- [Student monitor](https://github.com/stephenkhytze/verifigate/blob/master/web/resources/js/pages/gate/screen.tsx): `web/resources/js/pages/gate/screen.tsx`
- [Gate UI components](https://github.com/stephenkhytze/verifigate/tree/master/web/resources/js/components/gate): `web/resources/js/components/gate`

### Other components

- **Camera**
- **Guard**
- **Application database**

## Connections

- Camera → ID capture worker: captures image
- ID capture worker → Station scan endpoint: posts crop
- Station scan endpoint → Scan processor: processes scan
- Scan processor → OCR client: requests OCR
- OCR client → OCR service: sends image
- Scan processor → Identity matching: matches identity
- Scan processor → Scan routing: routes scan (evidence: `web/app/Services/IdScan/ScanRouter.php`)
- Scan processor → Uniform provider: checks uniform
- Scan processor → Gate events: writes event
- Identity matching → People records: matches records
- Scan routing → Gate events: decides status (evidence: `web/app/Services/IdScan/ScanRouter.php`)
- Guard → Guard endpoints: searches or identifies
- Guard endpoints → People records: searches records (evidence: `web/app/Http/Controllers/Station/GuardActionsController.php`)
- Guard endpoints → Gate events: creates or updates (evidence: `web/app/Http/Controllers/Station/GuardActionsController.php`)
- Guard → Guard decisions: approves or denies
- Guard decisions → Gate events: updates status (evidence: `web/app/Http/Controllers/Station/GuardDecisionController.php`)
- Guard monitor → Gate state endpoints: polls guard state
- Student monitor → Gate state endpoints: polls screen state
- Guard monitor → Guard endpoints: uses guard actions
- Guard monitor → Gate UI components: renders components
- Gate state endpoints → Gate events: reads events (evidence: `web/app/Http/Controllers/Station/GateStateController.php`)
- Gate events → Application database: persists events
- People records → Application database: stores records
- ID image endpoint → ID capture worker: fetches crop