# sa-rah9/hikvision-bio-metric-system architecture

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

- Interactive diagram: https://gitdiagram.com/sa-rah9/hikvision-bio-metric-system
- Repository: https://github.com/sa-rah9/hikvision-bio-metric-system

## Overview

This is a single-campus teacher-attendance application: administrators manage teachers and attendance rules, sync genuine Hikvision biometric events, review calculated attendance, and export reports. The graph covers the documented raw-event → daily-attendance → dashboard/report workflow, plus device, teacher, and settings capabilities. Edges use the shown route/page calls, SOURCE INDEX references, or README statements; several device internals and UI routes were not sampled, so their relationships are limited to documented links.

Main entry points: [`src/lib/prisma.ts`](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/prisma.ts) (PostgreSQL attendance store), [`src/lib/attendance/calculate.ts`](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/attendance/calculate.ts) (Daily attendance calculation), [`src/app/attendance/page.tsx`](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/attendance/page.tsx) (Daily attendance), [`src/lib/sync.ts`](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/sync.ts) (Event synchronization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Admin interface"]
  node_dashboard["Attendance dashboard<br/>[page.tsx]"]
  node_attendance_page["Daily attendance<br/>[page.tsx]"]
  node_raw_page["Raw event review<br/>[page.tsx]"]
  node_teachers_ui["Teacher management"]
  node_reports_page["Report filters and view<br/>[page.tsx]"]
end

subgraph group_api["Application API"]
  node_sync_route["Device sync endpoint<br/>[route.ts]"]
  node_teacher_routes["Teacher endpoints<br/>[route.ts]"]
  node_teacher_id_route["Teacher update endpoint<br/>[route.ts]"]
  node_settings_route["Attendance settings endpoint<br/>[route.ts]"]
  node_calculate_route["Recalculate endpoint<br/>[route.ts]"]
  node_excel_route["Excel export endpoint<br/>[route.ts]"]
end

subgraph group_attendance["Attendance domain"]
  node_raw_store[("PostgreSQL attendance store<br/>[prisma.ts]")]
  node_calculation["Daily attendance calculation<br/>[calculate.ts]"]
  node_settings["Attendance rules<br/>[settings.ts]"]
end

subgraph group_device["Biometric integration"]
  node_sync_service["Event synchronization<br/>[sync.ts]"]
  node_adapter["Device adapter registry<br/>[adapter.ts]"]
  node_hikvision_adapter["Hikvision adapter"]
  node_hikvision_client["ISAPI HTTP client<br/>[client.ts]"]
end

subgraph group_reporting["Reporting"]
  node_report_data["Report data and summaries<br/>[reports.ts]"]
  node_workbook["Workbook generation<br/>[excel.ts]"]
end

node_admin(("Campus administrator"))
node_device{{"Hikvision biometric device"}}

node_admin -->|"views"| node_dashboard
node_admin -->|"reviews"| node_attendance_page
node_admin -->|"reviews"| node_raw_page
node_admin -->|"manages"| node_teachers_ui
node_admin -->|"views"| node_reports_page
node_admin -->|"requests sync"| node_sync_route
node_teachers_ui -.->|"calls"| node_teacher_routes
node_teacher_routes -->|"reads/writes teachers"| node_raw_store
node_teacher_id_route -->|"reads/updates teachers"| node_raw_store
node_attendance_page -->|"ensures day"| node_calculation
node_attendance_page -->|"loads rules"| node_settings
node_attendance_page -->|"reads attendance"| node_raw_store
node_settings_route -->|"reads/updates"| node_settings
node_settings -->|"reads/writes rules"| node_raw_store
node_calculate_route -->|"recalculates"| node_calculation
node_dashboard -->|"refreshes attendance"| node_calculation
node_calculation -->|"loads rules"| node_settings
node_calculation -->|"reads events; writes daily rows"| node_raw_store
node_sync_route -->|"runs sync"| node_sync_service
node_sync_service -->|"selects adapter"| node_adapter
node_adapter -->|"registers"| node_hikvision_adapter
node_hikvision_adapter -->|"uses ISAPI client"| node_hikvision_client
node_hikvision_client -->|"sends ISAPI requests"| node_device
node_device -->|"provides genuine events"| node_sync_service
node_sync_service -->|"stores raw events"| node_raw_store
node_raw_page -->|"reads raw events"| node_raw_store
node_reports_page -->|"loads report data"| node_report_data
node_excel_route -->|"refreshes attendance"| node_calculation
node_excel_route -->|"fetches and summarizes"| node_report_data
node_report_data -->|"reads daily rows"| node_raw_store
node_excel_route -->|"builds workbook"| node_workbook

click node_dashboard "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/dashboard/page.tsx"
click node_attendance_page "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/attendance/page.tsx"
click node_raw_page "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/attendance/raw/page.tsx"
click node_teachers_ui "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/teachers/teachers-client.tsx"
click node_reports_page "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/reports/page.tsx"
click node_sync_route "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/api/hikvision/sync/route.ts"
click node_teacher_routes "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/api/teachers/route.ts"
click node_teacher_id_route "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/api/teachers/%5Bid%5D/route.ts"
click node_settings_route "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/api/attendance/settings/route.ts"
click node_calculate_route "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/api/attendance/calculate/route.ts"
click node_excel_route "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/api/reports/excel/route.ts"
click node_sync_service "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/sync.ts"
click node_adapter "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/devices/adapter.ts"
click node_hikvision_adapter "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/devices/hikvision-adapter.ts"
click node_hikvision_client "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/hikvision/client.ts"
click node_raw_store "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/prisma.ts"
click node_calculation "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/attendance/calculate.ts"
click node_settings "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/attendance/settings.ts"
click node_report_data "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/attendance/reports.ts"
click node_workbook "https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/excel.ts"

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_dashboard,node_attendance_page,node_raw_page,node_teachers_ui,node_reports_page toneBlue
class node_sync_route,node_teacher_routes,node_teacher_id_route,node_settings_route,node_calculate_route,node_excel_route toneAmber
class node_raw_store,node_calculation,node_settings toneMint
class node_sync_service,node_adapter,node_hikvision_adapter,node_hikvision_client toneRose
class node_report_data,node_workbook,node_admin,node_device toneIndigo
```

## Components

### Admin interface

- [Attendance dashboard](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [Daily attendance](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/attendance/page.tsx): `src/app/attendance/page.tsx`
- [Raw event review](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/attendance/raw/page.tsx): `src/app/attendance/raw/page.tsx`
- [Teacher management](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/teachers/teachers-client.tsx): `src/app/teachers/teachers-client.tsx`
- [Report filters and view](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/reports/page.tsx): `src/app/reports/page.tsx`

### Application API

- [Device sync endpoint](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/api/hikvision/sync/route.ts): `src/app/api/hikvision/sync/route.ts`
- [Teacher endpoints](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/api/teachers/route.ts): `src/app/api/teachers/route.ts`
- [Teacher update endpoint](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/api/teachers/%5Bid%5D/route.ts): `src/app/api/teachers/[id]/route.ts`
- [Attendance settings endpoint](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/api/attendance/settings/route.ts): `src/app/api/attendance/settings/route.ts`
- [Recalculate endpoint](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/api/attendance/calculate/route.ts): `src/app/api/attendance/calculate/route.ts`
- [Excel export endpoint](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/app/api/reports/excel/route.ts): `src/app/api/reports/excel/route.ts`

### Attendance domain

- [PostgreSQL attendance store](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/prisma.ts): `src/lib/prisma.ts`
- [Daily attendance calculation](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/attendance/calculate.ts): `src/lib/attendance/calculate.ts`
- [Attendance rules](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/attendance/settings.ts): `src/lib/attendance/settings.ts`

### Biometric integration

- [Event synchronization](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/sync.ts): `src/lib/sync.ts`
- [Device adapter registry](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/devices/adapter.ts): `src/lib/devices/adapter.ts`
- [Hikvision adapter](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/devices/hikvision-adapter.ts): `src/lib/devices/hikvision-adapter.ts`
- [ISAPI HTTP client](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/hikvision/client.ts): `src/lib/hikvision/client.ts`

### Reporting

- [Report data and summaries](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/attendance/reports.ts): `src/lib/attendance/reports.ts`
- [Workbook generation](https://github.com/sa-rah9/hikvision-bio-metric-system/blob/main/src/lib/excel.ts): `src/lib/excel.ts`

### Other components

- **Campus administrator**
- **Hikvision biometric device**

## Connections

- Campus administrator → Attendance dashboard: views (evidence: `README.md`)
- Campus administrator → Daily attendance: reviews (evidence: `README.md`)
- Campus administrator → Raw event review: reviews (evidence: `README.md`)
- Campus administrator → Teacher management: manages (evidence: `README.md`)
- Campus administrator → Report filters and view: views (evidence: `README.md`)
- Campus administrator → Device sync endpoint: requests sync (evidence: `README.md`)
- Teacher management → Teacher endpoints: calls
- Teacher endpoints → PostgreSQL attendance store: reads/writes teachers (evidence: `src/app/api/teachers/route.ts`)
- Teacher update endpoint → PostgreSQL attendance store: reads/updates teachers (evidence: `src/app/api/teachers/[id]/route.ts`)
- Daily attendance → Daily attendance calculation: ensures day (evidence: `src/app/attendance/page.tsx`)
- Daily attendance → Attendance rules: loads rules (evidence: `src/app/attendance/page.tsx`)
- Daily attendance → PostgreSQL attendance store: reads attendance (evidence: `src/app/attendance/page.tsx`)
- Attendance settings endpoint → Attendance rules: reads/updates (evidence: `src/app/api/attendance/settings/route.ts`)
- Attendance rules → PostgreSQL attendance store: reads/writes rules (evidence: `src/lib/attendance/settings.ts`)
- Recalculate endpoint → Daily attendance calculation: recalculates (evidence: `src/app/api/attendance/calculate/route.ts`)
- Attendance dashboard → Daily attendance calculation: refreshes attendance (evidence: `src/app/dashboard/page.tsx`)
- Daily attendance calculation → Attendance rules: loads rules (evidence: `src/lib/attendance/calculate.ts`)
- Daily attendance calculation → PostgreSQL attendance store: reads events; writes daily rows (evidence: `src/lib/attendance/calculate.ts`)
- Device sync endpoint → Event synchronization: runs sync (evidence: `src/app/api/hikvision/sync/route.ts`)
- Event synchronization → Device adapter registry: selects adapter (evidence: `src/lib/sync.ts`)
- Device adapter registry → Hikvision adapter: registers (evidence: `src/lib/devices/adapter.ts`)
- Hikvision adapter → ISAPI HTTP client: uses ISAPI client (evidence: `src/lib/devices/hikvision-adapter.ts`)
- ISAPI HTTP client → Hikvision biometric device: sends ISAPI requests (evidence: `README.md`)
- Hikvision biometric device → Event synchronization: provides genuine events (evidence: `README.md`)
- Event synchronization → PostgreSQL attendance store: stores raw events (evidence: `src/lib/sync.ts`)
- Raw event review → PostgreSQL attendance store: reads raw events (evidence: `src/app/attendance/raw/page.tsx`)
- Report filters and view → Report data and summaries: loads report data (evidence: `src/app/reports/page.tsx`)
- Excel export endpoint → Daily attendance calculation: refreshes attendance (evidence: `src/app/api/reports/excel/route.ts`)
- Excel export endpoint → Report data and summaries: fetches and summarizes (evidence: `src/app/api/reports/excel/route.ts`)
- Report data and summaries → PostgreSQL attendance store: reads daily rows (evidence: `src/lib/attendance/reports.ts`)
- Excel export endpoint → Workbook generation: builds workbook (evidence: `src/app/api/reports/excel/route.ts`)