Finale

KO | EN

gitlite — search

#python #hacktoberfest #typescript #llm #go #golang #deep-learning #macos #windows #awesome #kubernetes #vue #pytorch #mcp

(★ 5)

The Student Attendance App is a mobile app built with React and Expo for quick and accurate attendance marking. It uses Supabase for secure login and cloud storage. A Parents’ Proxy feature lets parents/guardians view a student’s attendance records and updates.

Finale Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# GPS-Based Student Attendance App

A mobile attendance system built with **Expo + React Native** and **Supabase** that lets students mark their own attendance only when physically present inside a classroom geofence.

---

## 1. Project Overview

### What It Does

Students open the app, tap "Mark Attendance", authenticate with Face ID / fingerprint / PIN, and the app verifies their GPS location against the classroom boundary. If they are inside the geofence, the attendance record is submitted and confirmed. Instructors create and close sessions from their own dashboard and can view or export a full attendance report immediately after class ends.

### Tech Stack

| Layer | Technology |
|---|---|
| Mobile app | Expo (SDK 52) + React Native + TypeScript |
| Navigation | Expo Router (file-based) |
| Backend | Supabase (Auth, PostgreSQL, Edge Functions, Realtime) |
| GPS | `expo-location` (high-accuracy foreground) |
| Biometrics | `expo-local-authentication` (Face ID / fingerprint / PIN) |
| Secure storage | `expo-secure-store` |
| Device fingerprint | `expo-device` + `expo-crypto` (SHA-256) |
| Testing | Jest + `@testing-library/react-native` + `fast-check` |

### Anti-Proxy Guarantees

1. **Physical presence** — GPS coordinates are verified server-side against the classroom geofence. A tampered client cannot bypass the server check.
2. **Device-bound identity** — biometric or PIN authentication must succeed on the student's registered device before any network call is made. No biometric data is transmitted.
3. **One record per session** — a `UNIQUE(session_id, student_id)` database constraint prevents duplicate submissions at the storage level.

---

## 2. Prerequisites

- **Node.js** 18 or later
- **npm** 9 or later
- **Supabase account** — free tier at [https://supabase.com](https://supabase.com)
- **Physical iOS or Android device** (recommended) — GPS and biometrics do not work in most simulators
- **Expo Go app** on your device for development

---

## 3. Step-by-Step Setup

### a. Install Dependencies

```bash
cd gps-attendance-app
npm install
```

### b. Create a Supabase Project

1. Go to [https://supabase.com](https://supabase.com) and sign in.
2. Click **New project**, give it a name, set a database password, and select a region.
3. Wait ~2 minutes for provisioning.

### c. Configure Environment Variables

1. In your Supabase dashboard, go to **Project Settings → API**.
2. Copy the **Project URL** and the **anon / public** key.
3. Open `.env` in the project root and fill in your values:

```dotenv
EXPO_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

> `.env` is in `.gitignore` and will not be committed.

### d. Run the Database Migration

1. In your Supabase dashboard, click **SQL Editor → New query**.
2. Open `supabase/migrations/001_initial_schema.sql` from this project.
3. Select all content, paste into the SQL Editor, and click **Run**.
4. Confirm the output shows **"Success. No rows returned."**

This creates all tables, indexes, RLS policies, and the `handle_new_user` trigger.

### e. Enable Realtime on `class_sessions`

1. In your Supabase dashboard, go to **Database → Replication**.
2. Enable replication for the `class_sessions` table.
3. Or run this SQL: `ALTER TABLE class_sessions REPLICA IDENTITY FULL;`

### f. Deploy Edge Functions

Install the Supabase CLI:

```bash
npm install -g supabase
supabase login
supabase link --project-ref your-project-ref
```

Deploy all four functions:

```bash
npx supabase functions deploy mark-attendance
npx supabase functions deploy create-session
npx supabase functions deploy close-session
npx supabase functions deploy attendance-report
```

The `SUPABASE_SERVICE_ROLE_KEY` is injected automatically by the Supabase runtime — you do not need to set it manually.

### g. Start the App

```bash
npm start
```

Scan the QR code with **Expo Go** on your device, or press `i` for iOS Simulator / `a` for Android Emulator.

---

## 4. Environment Variables

| Variable | Required | Description |
|---|---|---|
| `EXPO_PUBLIC_SUPABASE_URL` | Yes | Your Supabase project URL, e.g. `https://abcdefgh.supabase.co` |
| `EXPO_PUBLIC_SUPABASE_ANON_KEY` | Yes | The anon/public API key from **Project Settings → API** |

> The **service role key** is never placed in `.env` or shipped to the client. It is only available inside Edge Functions via `Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')`.

---

## 5. Creating Test Users

### Via Supabase Dashboard

1. Go to **Authentication → Users → Add user → Create new user**.
2. Enter email and password.
3. After creation, go to **Table Editor → profiles** and update the row:

**Student:**
```json
{ "full_name": "Jane Smith", "student_id": "S12345", "role": "student" }
```

**Instructor:**
```json
{ "full_name": "Dr. Ahmad", "student_id": null, "role": "instructor" }
```

### Via SQL

```sql
UPDATE profiles
SET full_name = 'Jane Smith', student_id = 'S12345', role = 'student'
WHERE id = '<user-uuid>';
```

---

## 6. Adding a Test Classroom

```sql
INSERT INTO classrooms (name, building, latitude, longitude, radius_meters, instructor_id)
VALUES (
  'Lab A',
  'Engineering Block',
  3.1390,    -- latitude (WGS-84)
  101.6869,  -- longitude (WGS-84)
  50,        -- geofence radius in metres
  '<instructor-user-uuid>'
);
```

To find coordinates for a real room: right-click the location in Google Maps and copy the lat/lng.

---

## 7. Enrolling a Student

```sql
INSERT INTO enrollments (student_id, classroom_id)
VALUES ('<student-user-uuid>', '<classroom-uuid>');
```

---

## 8. Troubleshooting

### GPS not working / "LOW_GPS_ACCURACY"

- Move outdoors with a clear view of the sky and wait 10–15 seconds.
- Check the app has **"While Using the App"** location permission in device Settings.
- On iOS Simulator: **Features → Location → Custom Location**.
- On Android Emulator: **Extended Controls → Location**.

### Biometric not prompting

- Ensure at least one fingerprint or Face ID is enrolled in device Settings.
- On iOS Simulator: **Features → Face ID → Enrolled**, then **Matching Face** to simulate success.
- On Android Emulator: enroll via **Settings → Security → Fingerprint**, simulate via `adb -e emu finger touch 1`.
- If no biometric hardware, the app falls back to device PIN — ensure a PIN is set.

### "NOT_ENROLLED" error

- The student is not in the `enrollments` table for this classroom.
- Run the enrollment SQL from section 7.
- Confirm the `classroom_id` in the enrollment matches the session's classroom.

### Edge Function errors (500 / unexpected responses)

- Go to **Edge Functions → \<function-name\> → Logs** in the Supabase dashboard.
- Common causes: missing Authorization header, invalid JSON body, missing required fields.

### Session not appearing for students

- Verify Realtime is enabled on `class_sessions` (see step e above).
- Confirm the student is enrolled in the classroom — the RLS policy only allows enrolled students to read open sessions.
- Check the `AttendanceProvider` is receiving a non-null `classroomId` prop.

### "DUPLICATE_SESSION" when creating a session

- An open session already exists for that classroom. Close it first:

```sql
UPDATE class_sessions
SET status = 'closed', ended_at = now()
WHERE classroom_id = '<classroom-uuid>' AND status = 'open';
```

---

## 9. Project Structure

```
gps-attendance-app/
├── .env                          # Supabase URL and anon key (not committed)
├── .env.example                  # Template with placeholder values
├── app.json                      # Expo config: scheme, permissions, plugins
├── package.json                  # Dependencies and npm scripts
├── tsconfig.json                 # TypeScript config with path aliases
├── EVENTS.md                     # All system events, state machines, Realtime payloads
│
├── app/                          # Expo Router screens
│   ├── _layout.tsx               # Root layout: providers + role-based routing
│   ├── (auth)/
│   │   ├── _layout.tsx           # Auth group layout
│   │   └── login.tsx             # Email + password sign-in
│   ├── (student)/
│   │   ├── _layout.tsx           # Student group layout (role guard)
│   │   ├── index.tsx             # Attendance button screen
│   │   └── history.tsx           # Personal attendance history
│   └── (instructor)/
│       ├── _layout.tsx           # Instructor group layout (role guard)
│       ├── index.tsx             # Session management dashboard
│       ├── session/[id].tsx      # Live session view
│       └── report/[id].tsx       # Attendance report + CSV export
│
├── src/
│   ├── types/index.ts            # All shared TypeScript interfaces and types
│   ├── contexts/
│   │   ├── AuthContext.tsx       # Supabase session lifecycle + user/role state
│   │   ├── AttendanceContext.tsx # Active session state + Realtime subscription
│   │   └── LocationContext.tsx   # GPS coordinates and permission state
│   ├── services/
│   │   ├── supabase.ts           # Supabase client singleton (reads from env vars)
│   │   ├── attendance.service.ts # Full submission pipeline
│   │   ├── geofence.service.ts   # expo-location wrapper
│   │   └── biometric.service.ts  # expo-local-authentication wrapper
│   ├── hooks/
│   │   ├── useAttendance.ts      # Submission hook with loading/error state
│   │   ├── useLocation.ts        # Location context hook
│   │   └── useSession.ts         # Session management hook
│   └── utils/
│       ├── haversine.ts          # haversineDistance, isInsideGeofence, validateGPSFix
│       └── deviceId.ts           # Stable SHA-256 device fingerprint
│
└── supabase/
    ├── migrations/
    │   └── 001_initial_schema.sql  # Full DDL: tables, indexes, RLS, trigger
    └── functions/
        ├── _shared/cors.ts
        ├── mark-attendance/index.ts
        ├── create-session/index.ts
        ├── close-session/index.ts
        └── attendance-report/index.ts
```

---

## 10. Evaluation Checklist (60 Marks)

### System Design & HCI (30 marks)

| Criterion | Location |
|---|---|
| Architecture diagram | `design.md` — Architecture section |
| Database schema + ERD | `design.md` — Database Schema; `supabase/migrations/001_initial_schema.sql` |
| Sequence diagrams | `design.md` — Sequence Diagrams section |
| State machine / event flow | `EVENTS.md` — Section 3 |
| Session lifecycle diagram | `EVENTS.md` — Section 4 |
| Auth state transitions | `EVENTS.md` — Section 5 |
| Security design + RLS | `design.md` — Security Considerations; migration SQL |
| Anti-proxy mechanism | `biometric.service.ts`, `mark-attendance/index.ts`, DB UNIQUE constraint |
| Environment variable management | `src/services/supabase.ts` — no hardcoded secrets |
| Realtime design | `EVENTS.md` — Section 2; `src/contexts/AttendanceContext.tsx` |
| Error handling | `design.md` — Error Handling; typed `AttendanceError` in `src/types/index.ts` |
| Role-based routing | `app/_layout.tsx`; separate `(student)` and `(instructor)` route groups |
| Immediate UX feedback | Client-side geofence pre-check; Realtime button state updates |
| User-facing error messages | Error code → message map in `app/(student)/index.tsx` |

### App Functionality (30 marks)

| Criterion | Implementation |
|---|---|
| Student login | `app/(auth)/login.tsx` + `src/contexts/AuthContext.tsx` |
| Instructor login | Same login screen; role-based routing after sign-in |
| Session creation | `supabase/functions/create-session/index.ts`; instructor dashboard |
| Session closure | `supabase/functions/close-session/index.ts`; instructor dashboard |
| GPS acquisition | `src/services/geofence.service.ts` — `Location.Accuracy.High` |
| GPS accuracy validation | `validateGPSFix()` — rejects accuracy > 50 m |
| Stale fix rejection | `validateGPSFix()` — rejects fixes older than 30 s |
| Biometric gate | `src/services/biometric.service.ts`; called before any network request |
| Client-side geofence check | `isInsideGeofence()` with accuracy buffer |
| Server-side geofence check | `mark-attendance/index.ts` — independent Haversine re-computation |
| Enrollment check | `mark-attendance/index.ts` — queries `enrollments` table |
| Duplicate prevention | DB `UNIQUE(session_id, student_id)`; Edge Function catches `23505` |
| Realtime session updates | `AttendanceContext` subscribes to `class_sessions` Realtime channel |
| Attendance button state | Disabled when session closed; updates on Realtime event |
| Attendance report | `supabase/functions/attendance-report/index.ts`; report screen |
| CSV export | `app/(instructor)/report/[id].tsx` — generates CSV + `Share.share()` |
| Student history | `app/(student)/history.tsx` — RLS enforces data isolation |
| RLS data isolation | Migration SQL — `students_read_own`, `instructors_read_session` |
| Secure session storage | `src/services/supabase.ts` — `expo-secure-store` adapter |
| Device fingerprint logging | `src/utils/deviceId.ts`; logged in every `attendance_logs` row |

Finale

Finale Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Finale

Finale Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README