# AttendAI A responsive role-based campus attendance application with QR and camera-assisted check-ins, class administration, timetables, reporting, and notifications. ## Masterplan - Serve school and college admins, teachers, and students from one role-aware workspace. - Replace manual attendance with short-lived QR sessions or camera-assisted check-ins. - Give staff live operational views for classes, students, attendance records, and reports. - Give students quick mobile check-in access plus timetable and attendance visibility. - Persist campus data through the GenMB relational database while retaining seeded data for initial setup. ## Tech Stack & Architecture - **Frontend:** React, TypeScript, Vite, React Router, and Lucide React icons. - **Styling:** utility-class styling backed by semantic CSS variables in `src/styles/main.css`; reusable primitives live in `src/components/ui/`. - **QR:** `qrcode` generates teacher-facing QR images; the browser `BarcodeDetector` API scans student-facing QR codes when supported. - **Camera:** `navigator.mediaDevices.getUserMedia()` provides face-frame capture and QR camera input. - **Persistence:** the SDK injected by `index.html` exposes relational CRUD at `window.genmb.db`. Type declarations belong in `src/genmb.d.ts`. - **Application state:** `src/context/AppDataContext.tsx` is the data/service boundary for role, settings, classes, students, attendance, sessions, and notifications. Pages and dialogs must use `useAppData()` rather than call `window.genmb.db` directly. - **Feedback:** `src/context/ToastContext.tsx` owns transient success, error, and informational messages. - **Routing/layout:** `src/main.tsx` initializes providers and routes. Routed pages render inside `src/components/AppShell.tsx` via ``. - **Seed/bootstrap:** `src/data/seed.ts` supplies the initial campus dataset used when persistent tables require initialization. - **Metadata:** pages use `src/hooks/usePageMetadata.ts` for document title/description updates. The application is client-rendered; there is no custom server source in this repository. GenMB’s injected capability is the backend boundary. ### GenMB Data API `index.html` injects a dynamic client with this surface: ```ts window.genmb.db..list(params?) window.genmb.db.

.getById(id) window.genmb.db.

.create(fields) window.genmb.db.

.update(id, fields) window.genmb.db.

.delete(id) window.genmb.db.

.count(params?) window.genmb.db.

.createMany(records) // maximum 100 window.genmb.db.

.deleteMany(ids) // maximum 100 window.genmb.db.

.subscribe(callback) window.genmb.db.transaction(operations) ``` Use `transaction()` for related writes that must not partially succeed. Subscriptions are at-most-once and have no replay; refetch after reconnect. The injected SDK maps common database errors to user-safe messages, but callers must still catch failures and show them through `ToastContext` or inline form errors. ## File Structure ```text index.html # App metadata and injected GenMB relational database SDK package.json # Runtime dependencies and Vite scripts vite.config.ts # Vite build/development configuration src/main.tsx # React entry point, providers, router, and route definitions src/types.ts # Shared Role and domain entity types src/genmb.d.ts # Browser capability typings, including GenMB/BarcodeDetector src/styles/main.css # Global styles, semantic color tokens, utility setup, and dark theme src/context/AppDataContext.tsx # Central data loading, mutations, role, settings, and session logic src/context/ToastContext.tsx # Toast state and notification helpers src/data/seed.ts # Initial classes, students, attendance, settings, and related records src/components/AppShell.tsx # Desktop sidebar, mobile navigation, header, role switcher, and theme control src/components/AttendanceChart.tsx # Last-seven-date attendance percentage chart src/components/MetricCard.tsx # Dashboard KPI card with semantic tone src/components/attendance/ # QR session, QR scanner, and camera check-in workflows src/components/classes/ClassFormDialog.tsx # Required-field class creation form src/components/students/StudentFormDialog.tsx # Student creation and email validation src/components/ui/ # Button, Card, Dialog, Input, badges, skeletons, and state components src/pages/DashboardPage.tsx # Role-sensitive overview and metrics src/pages/AttendancePage.tsx # Attendance records and check-in/session actions src/pages/ClassesPage.tsx # Class listing and creation src/pages/TimetablePage.tsx # Schedule view src/pages/StudentsPage.tsx # Student profiles and creation src/pages/ReportsPage.tsx # Attendance analytics and reporting src/pages/NotificationsPage.tsx # Notification list/read state src/pages/SettingsPage.tsx # Institution and attendance feature settings src/pages/NotFoundPage.tsx # Unknown-route recovery src/hooks/usePageMetadata.ts # Per-page browser metadata src/lib/utils.ts # Shared class-name and formatting helpers ``` ## Key Features ### Role-based workspace Supported roles are `admin`, `teacher`, and `student`. `AppShell.tsx` filters navigation as follows: - All roles: Dashboard, Attendance, Timetable, Reports, Notifications, Settings. - Admin and teacher only: Classes and Students. Role switching calls `changeRole()`, returns the user to `/`, and changes the visible experience. Navigation filtering is currently a UI rule, not an authentication or server authorization boundary; any future sensitive write must also be authorized in the backend. ### Attendance - Teachers/admins can create a QR session for a selected class through `QRSessionDialog.tsx`. - Sessions produce a six-digit code, QR image, and 15-minute expiry. - Students can scan with an environment-facing camera or enter the code manually through `QRScannerDialog.tsx`. - Codes must match `/^\d{6}$/` and resolve through `findActiveSession()`. - Camera scanning depends on `window.BarcodeDetector`; manual code entry is the required fallback. - Camera check-in in `FaceCheckInDialog.tsx` captures a frame and records method `face`. - **Important:** the current implementation does not perform biometric matching, liveness detection, or face recognition. UI copy must not claim that it verifies identity. - Both student check-in dialogs currently resolve the active student using hard-coded ID `student-maya`, then fall back to the first student. Replace this with authenticated-user identity before production use. - Camera streams and animation frames must be stopped on success, close, and component cleanup. Attendance statuses include at least `present` and `absent`; chart calculations treat every non-absent record as attended. Attendance methods include `qr` and `face`. ### Classes and students `ClassFormDialog.tsx` creates classes with: ```ts { code, name, section, teacher, room, schedule } ``` All fields are required. `StudentFormDialog.tsx` creates students with: ```ts { name, email, rollNumber, program, year } ``` All fields are required, and email receives basic client validation. Mutations run through `addClass()` and `addStudent()` in `AppDataContext`. ### Analytics and notifications - `AttendanceChart.tsx` groups records by date, sorts chronologically, takes the latest seven dates, and displays rounded attendance percentages. - Dashboard metrics use `MetricCard.tsx` and semantic tones: `primary`, `success`, `warning`, or `info`. - Unread notification count is derived from records where `read === false` and appears in the app header. - Reports, timetable, settings, and notifications remain routed pages and should continue to consume centralized context data. ### Settings Settings include institution name, theme, and camera/face-verification availability. Theme changes are persisted via `saveSettings()` and reflected through semantic CSS tokens. Disabling face verification must prevent camera check-in rather than merely hiding its trigger. ## Design Guidelines - Use the existing blue primary palette with white/soft-gray surfaces and semantic `success`, `warning`, `info`, and `destructive` tokens. - Use semantic classes such as `bg-background`, `bg-card`, `text-muted-foreground`, and `text-primary`; do not introduce hard-coded colors that bypass dark mode. - Cards and controls use rounded corners, subtle borders, restrained shadows, and occasional primary-to-info gradients. - Typography is professional sans-serif with bold, tightly tracked headings and compact supporting copy. - Desktop navigation is a fixed 16rem sidebar at `lg` and above. Smaller screens use the header menu and mobile navigation dialog. - Forms generally become two-column grids at `sm`; primary actions should remain usable as full-width controls on narrow screens. - Preserve focus rings, `aria-label`, `role="alert"`, disabled/loading states, and keyboard-operable dialogs. ## App Flow 1. The application loads providers and routes from `src/main.tsx`; `AppDataContext` fetches or initializes workspace data. 2. `AppShell` displays role-appropriate navigation, institution name, theme control, notifications, and role selection. 3. Admins/teachers create classes and student profiles, then start a QR attendance session for a class. 4. Students open Attendance, scan the QR or enter its six-digit code, and receive success/error feedback. 5. If enabled, students may capture a camera frame as an alternative attendance method. 6. Attendance records feed the dashboard, live status, and reports; notifications expose unread activity. Key edge cases: - Empty classes or students must produce an actionable empty state, not broken selectors. - Invalid/expired QR codes must not create attendance. - Unsupported camera or `BarcodeDetector`, denied permissions, and decode failures require manual fallback. - Prevent duplicate submissions while mutations are pending. - Unknown URLs render `NotFoundPage.tsx`. - Loading, empty, and failed fetches should use `Skeleton`, `EmptyState`, and `FetchError`. - Always clean up active camera tracks when a dialog closes or unmounts. ## Conventions - Use PascalCase for components/types and camelCase for functions, hooks, variables, and context actions. - Keep route-level composition in `src/pages/`; place reusable domain workflows under `src/components//`. - Use default exports for components, matching the current codebase. - Build controls from `src/components/ui/` and combine classes with `cn()` from `src/lib/utils.ts`. - Keep persisted domain state and mutations in `AppDataContext`; keep temporary form, dialog, camera, and submission state local. - All async mutations need a pending state, `try/catch/finally`, inline actionable errors where relevant, and toast feedback. - Add shared domain shapes to `src/types.ts`; do not duplicate entity interfaces inside pages. - To add a page: create `src/pages/Page.tsx`, register its route in `src/main.tsx`, add metadata, and add an entry with explicit role access to `navItems` in `AppShell.tsx`. - To add a data-backed feature: extend types and seed data, implement loading/mutations in `AppDataContext.tsx`, then consume those methods from pages/components. Do not scatter direct GenMB calls through the UI. - Never describe captured camera frames as biometric verification unless a real, consented recognition and liveness service is implemented. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.

AI Attendance Platform