GeoMark

1System Overview

GeoMark is a web-based attendance management platform that combines cryptographically-signed rotating QR codes with GPS geofencing to guarantee that students mark attendance only when they are physically present inside the classroom. No dedicated mobile app is required — everything runs in a modern browser.

Key capabilities

• Rotating QR codes — new cryptographic token every 15–300 seconds (configurable)
• Verbal attendance code — 6-character fallback for students who cannot scan
• Bluetooth beacon — students tap Scan for Beacon to detect the classroom BLE signal
• GPS geofencing — configurable radius 10–500 m from the lecturer's position
• Late threshold — sessions automatically tag arrivals after a set number of minutes as "Late"
• Live attendance dashboard — instructors see new check-ins in real time
• Per-user notifications — students and lecturers receive confirmation on every event
• Full audit trail — every manual status override is recorded in the security log
• Multi-department sessions — lecturers can target one or more departments per session
• Profile photos — all users can upload or photograph a profile image in Settings

2Student Guide

2.1Signing In & Registering

Navigate to the app URL and click Sign In. You can sign in with Google or use a local account. When registering as a student, your Matric Number is your login identifier — no email address is needed. Enter it in the format BU24CSC1021 (2 letters + 2-digit year + 3-letter department code + 4 digits).

2.2Mark Attendance — QR Code

1. From the student dashboard, click Check In and select QR Code from the dropdown. You can also open Attendance in the sidebar directly.
2. Allow the browser to access your camera and location when prompted.
3. Hold your phone so the QR code displayed by your lecturer fills the square viewport.
4. The app detects and submits the code automatically — no button press needed.
5. A green success card confirms your status (Present or Late), your distance from the classroom centre, and the course name.

2.3Mark Attendance — Enter Code

Click Check In → Enter Code on the dashboard, or tap the Code tab on the Attendance page. Your lecturer will display or read out a 6-character code (e.g. XKPR7W). Type it in and tap Submit Code.

2.4Mark Attendance — Bluetooth

Click Check In → Bluetooth on the dashboard, or tap the Bluetooth tab on the Attendance page. Tap Scan for Beacon and select the GeoMark device from the browser prompt. The app reads the session token from the beacon and submits your attendance automatically.

2.5Viewing Your History & Rate

Go to History in the sidebar. The page shows a card per course you have attended, each with:

• Course name and ID, attended vs missed sessions, and a progress bar.
• An attendance rate percentage. A ⚠ icon appears for courses below 75%.
• Tap a course card to expand it — you'll see a breakdown of Present / Late / Missed counts and a scrollable list of every individual check-in with date, time, status badge, and distance from class.

2.6Notifications

The bell icon in the top bar shows your personal notifications. Each successful check-in, late mark, or status change generates a notification visible only to you. Clicking Mark all read clears the unread badge.

2.7Profile, Photo & Settings

Open Settings from the sidebar. You can:

• Upload or photograph a profile picture — tap Upload photo to choose a file, or Take photo to use your device camera. The image is resized to 200 × 200 px and stored securely.
• Edit your display name — your name appears in the topbar, sidebar, and attendance records.
• Edit your matric number — useful if it was entered incorrectly at registration. The new value must be unique across all accounts.

You can also click your name in the topbar and select Change Icon to pick an emoji avatar, which appears in place of a photo.

3Lecturer / Instructor Guide

3.1Starting an Attendance Session

1. Go to QR Sessions in the sidebar.
2. Click Generate New Session.
3. Fill in the form:
   • Course ID — a stable identifier for the course (e.g. CS101).
   • Course Name — friendly display name (e.g. "Introduction to Computing").
   • Departments — tick one or more departments whose students should be able to mark attendance. Leave blank to allow all departments. See §3.8 for multi-department sessions.
   • Radius (m) — how far from your GPS position students may be and still count as present. Default 100 m. Adjust for large lecture halls or outdoor venues.
   • Session Start time — the scheduled start of the class (datetime picker). Used to compute the Late threshold.
   • Late after time — students who check in at or after this datetime are marked Late. The form shows the computed gap (e.g. "Students arriving after 15 min are marked Late") next to the picker so you can verify at a glance. Set it equal to the start time to mark everyone Late.
4. Click Start Session. The system captures your browser's GPS coordinates as the classroom centre.

3.2The QR Code Display

After creation, a large QR code appears on screen. Project it on the classroom screen or share your screen via video conferencing. The code refreshes automatically every 15–30 seconds (depending on server configuration) — students must scan the current code. Old codes are cryptographically invalidated when they expire.

3.3The Verbal Code

Below the QR code, a 6-character attendance code(e.g. XKPR7W) is displayed in large monospace text. Read this code aloud or write it on the board for students who cannot scan the QR. The verbal code remains valid for the full duration of the session (it does not rotate like the QR token).

3.4Monitoring Live Attendance

The session panel shows a live list of students who have checked in, including their name, email, status, timestamp, and distance from the classroom. The list refreshes every 10 seconds automatically.

3.5Adjusting Attendance Status

Each row in the attendee list has a status dropdown. You can change a student's status to Present, Late, Absent, or Flagged. Every change is:

• Saved immediately to the database.
• Written to the security audit log with your identity, the student's identity, the previous status, and the new status.
• Irreversible via the UI — if you need to revert, change it again manually.

3.6Ending a Session

Click End Session. The QR code and verbal code become immediately invalid — any subsequent scan or code submission will be rejected with "Session not found or already ended." A notification is sent to you summarising the total number of students who attended.

3.7Late Threshold Setting

The late threshold is configured via two datetime pickers in the session creation form: Session Start and Late after. The difference between them is the grace period. The form displays the computed gap as a live preview (e.g. "Students arriving after 15 min are marked Late") so you can see the exact value before starting the session.

3.8Multi-Department Sessions

By default, a session is open to students from all departments. To restrict attendance to specific cohorts, tick one or more departments in the Departments checkbox list in the session creation form.

• Only students whose registered department matches one of the ticked departments will be able to mark attendance.
• Students from other departments will see an error if they attempt to check in.
• You can select multiple departments for cross-listed or combined courses (e.g. tick both CSC and EEE for a shared elective).
• Leave all checkboxes unticked to allow every department — the same behaviour as before this feature was introduced.

4Admin Guide

4.1User Management

Navigate to Users in the sidebar. Admins can:

• View all registered accounts (passwords and device fingerprints are never exposed).
• Promote a student to instructor or admin via the role dropdown.
• Delete accounts (requires confirmation). You cannot delete or demote your own account.

4.2Security Logs

The Security page shows all high-severity events: invalid QR tokens, location anomalies, and manual attendance overrides. Each entry records the user, event type, IP address, user-agent, and full details.

4.3Analytics & CSV Export

The Analytics page aggregates attendance across all courses and sessions. Use the filters at the top of the page to narrow the data:

• Period — choose from All Time, This Week, This Month, or This Year to restrict the date range of sessions included in the charts and totals.
• Course — select a specific course from the dropdown to drill into individual cohort trends, or leave it on All Courses for a platform-wide overview.

Click Export CSV to download the filtered data as a spreadsheet. The export respects the currently selected period and course filters. All fields are sanitised to prevent spreadsheet formula injection (cells beginning with =, +, or @ are prefixed with a tab before export).

5Technical Notes

5.1QR Token Security

Each QR code embeds a signed token (not a plain session ID). The token is structured as:

<base64url(JSON payload)>.<HMAC-SHA256 signature>

Payload fields:
  sessionId   — UUID for the QR session
  courseId    — course identifier
  courseName  — human-readable course name
  lat / lon   — classroom GPS coordinates
  radius      — allowed geofence radius in metres
  iat         — issued-at timestamp (ms)
  exp         — expiry timestamp (ms)

The HMAC is computed with the server-side QR_SECRETenvironment variable using timing-safe comparison (crypto.timingSafeEqual) to prevent timing-oracle attacks. Tokens are validated for signature and expiry on every scan — an expired token is rejected even if the signature is valid.

5.2Geofencing

Distance is computed with the Haversine formula:

const R = 6371000; // Earth radius in metres
const dLat = toRad(lat2 - lat1);
const dLon = toRad(lon2 - lon1);
const a = sin²(dLat/2) + cos(lat1)·cos(lat2)·sin²(dLon/2);
const distance = 2·R·atan2(√a, √(1−a));

Accuracy depends on the device's GPS hardware. Indoor GPS can be off by 10–50 m on some devices. Set radiusMeters generously (100–150 m) for multi-storey buildings or venues with poor GPS reception.

5.3Rate Limiting

All submission endpoints are protected by an in-memory sliding-window rate limiter:

5.4Audit Trail

Every manual attendance status change writes aSecurityLog document:

{
  userId:    "<modifier's user ID>",
  eventType: "attendance_status_modified",
  severity:  "medium",
  details: {
    attendanceId:  "<record ID>",
    studentId:     "<student's user ID>",
    studentEmail:  "<student email>",
    courseId:      "<course ID>",
    previousStatus: "present" | "late" | "absent" | "flagged",
    newStatus:      "present" | "late" | "absent" | "flagged",
    modifiedBy:    "<modifier's email>",
  },
  ipAddress: "<requester IP>",
  userAgent: "<browser string>",
  createdAt: <timestamp>
}

Logs are never deleted automatically — retain them according to your institution's data governance policy.

5.5Security Headers

All responses include these HTTP security headers:

5.6Environment Variables

The following environment variables must be set before deploying. Missing required variables cause the server to refuse to start.

6Troubleshooting