# sumit-beldar/qr-attendance-v2 architecture

> Architecture diagram of the GitHub repository sumit-beldar/qr-attendance-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sumit-beldar/qr-attendance-v2
- Repository: https://github.com/sumit-beldar/qr-attendance-v2

## Overview

QR Attendance System supports teacher-managed classes and student check-ins in local-network or cloud mode. Teachers manage accounts, batches and students, then start sessions; the projector displays a seven-second rotating QR code and short-code fallback. Students authenticate, scan or enter a code, claim a short-lived ticket, optionally provide GPS, and complete check-in. Attendance routes validate and record the result, including anti-proxy checks; teachers monitor, revoke and export attendance. The excerpts support the core route and UI links; some README capabilities, including backup and deployment modes, are documented but not traced to sampled implementations.

Main entry points: [`src/server.js`](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/server.js) (HTTP server), [`src/db.js`](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/db.js) (Database access), [`src/routes/attendance.js`](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/routes/attendance.js) (Attendance check-in), [`src/auth.js`](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/auth.js) (Auth and limits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_teacher_ui["Teacher portal<br/>[teacher.js]"]
  node_student_ui["Student portal<br/>[student.js]"]
  node_projector_ui["Live projector<br/>[projector.js]"]
end

subgraph group_api["Application routes"]
  node_server["HTTP server<br/>[server.js]"]
  node_teacher_routes["Teacher management<br/>[teacher.js]"]
  node_student_routes["Student accounts<br/>[student.js]"]
  node_session_routes["Session management<br/>[sessions.js]"]
  node_attendance_routes["Attendance check-in<br/>[attendance.js]"]
end

subgraph group_security["Check-in services"]
  node_auth["Auth and limits<br/>[auth.js]"]
  node_codes["QR and tickets<br/>[codes.js]"]
  node_geo["Geofence checks<br/>[geo.js]"]
end

subgraph group_state["Persistence"]
  node_db_layer["Database access<br/>[db.js]"]
  node_attendance_store[("Attendance database<br/>[db.js]")]
end

node_teacher(("Teacher"))
node_student(("Student"))
node_projector_screen(("Projector screen"))
node_turso[("Turso libSQL")]

node_teacher -->|"uses"| node_teacher_ui
node_student -->|"uses"| node_student_ui
node_projector_screen -->|"displays"| node_projector_ui
node_teacher_ui -->|"requests APIs"| node_server
node_student_ui -->|"requests APIs"| node_server
node_projector_ui -->|"polls code"| node_server
node_server -->|"mounts API"| node_teacher_routes
node_server -->|"mounts API"| node_student_routes
node_server -->|"mounts API"| node_session_routes
node_server -->|"mounts API"| node_attendance_routes
node_teacher_routes -->|"checks access"| node_auth
node_teacher_routes -->|"reads and writes"| node_db_layer
node_student_routes -->|"checks access"| node_auth
node_student_routes -->|"reads and writes"| node_db_layer
node_session_routes -->|"checks teacher"| node_auth
node_session_routes -->|"reads sessions"| node_db_layer
node_session_routes -->|"generates QR"| node_codes
node_attendance_routes -->|"checks access and limits"| node_auth
node_attendance_routes -->|"validates code and ticket"| node_codes
node_attendance_routes -->|"checks location"| node_geo
node_attendance_routes -->|"reads and records"| node_db_layer
node_auth -->|"checks session versions"| node_db_layer
node_server -->|"checks database health"| node_db_layer
node_db_layer -->|"reads and writes"| node_attendance_store
node_db_layer -.->|"connects in cloud mode"| node_turso

click node_teacher_ui "https://github.com/sumit-beldar/qr-attendance-v2/blob/main/public/js/teacher.js"
click node_student_ui "https://github.com/sumit-beldar/qr-attendance-v2/blob/main/public/js/student.js"
click node_projector_ui "https://github.com/sumit-beldar/qr-attendance-v2/blob/main/public/js/projector.js"
click node_server "https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/server.js"
click node_teacher_routes "https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/routes/teacher.js"
click node_student_routes "https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/routes/student.js"
click node_session_routes "https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/routes/sessions.js"
click node_attendance_routes "https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/routes/attendance.js"
click node_auth "https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/auth.js"
click node_codes "https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/codes.js"
click node_geo "https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/geo.js"
click node_db_layer "https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/db.js"
click node_attendance_store "https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/db.js"

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_teacher_ui,node_student_ui,node_projector_ui,node_projector_screen toneBlue
class node_server,node_teacher_routes,node_student_routes,node_session_routes,node_attendance_routes,node_turso toneAmber
class node_auth,node_codes,node_geo toneMint
class node_db_layer,node_attendance_store toneRose
class node_teacher,node_student toneIndigo
```

## Components

### User interfaces

- [Teacher portal](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/public/js/teacher.js): `public/js/teacher.js`
- [Student portal](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/public/js/student.js): `public/js/student.js`
- [Live projector](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/public/js/projector.js): `public/js/projector.js`

### Application routes

- [HTTP server](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/server.js): `src/server.js`
- [Teacher management](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/routes/teacher.js): `src/routes/teacher.js`
- [Student accounts](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/routes/student.js): `src/routes/student.js`
- [Session management](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/routes/sessions.js): `src/routes/sessions.js`
- [Attendance check-in](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/routes/attendance.js): `src/routes/attendance.js`

### Check-in services

- [Auth and limits](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/auth.js): `src/auth.js`
- [QR and tickets](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/codes.js): `src/codes.js`
- [Geofence checks](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/geo.js): `src/geo.js`

### Persistence

- [Database access](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/db.js): `src/db.js`
- [Attendance database](https://github.com/sumit-beldar/qr-attendance-v2/blob/main/src/db.js): `src/db.js`

### Other components

- **Teacher**
- **Student**
- **Projector screen**
- **Turso libSQL**

## Connections

- Teacher → Teacher portal: uses
- Student → Student portal: uses
- Projector screen → Live projector: displays
- Teacher portal → HTTP server: requests APIs
- Student portal → HTTP server: requests APIs
- Live projector → HTTP server: polls code
- HTTP server → Teacher management: mounts API
- HTTP server → Student accounts: mounts API
- HTTP server → Session management: mounts API
- HTTP server → Attendance check-in: mounts API
- Teacher management → Auth and limits: checks access
- Teacher management → Database access: reads and writes
- Student accounts → Auth and limits: checks access
- Student accounts → Database access: reads and writes
- Session management → Auth and limits: checks teacher
- Session management → Database access: reads sessions
- Session management → QR and tickets: generates QR
- Attendance check-in → Auth and limits: checks access and limits
- Attendance check-in → QR and tickets: validates code and ticket
- Attendance check-in → Geofence checks: checks location
- Attendance check-in → Database access: reads and records
- Auth and limits → Database access: checks session versions
- HTTP server → Database access: checks database health
- Database access → Attendance database: reads and writes
- Database access → Turso libSQL: connects in cloud mode