System Requirements Document for college-attendance

1. Introduction

college-attendance is a production-ready College Attendance Management Web App built for a Class Representative (CR) who is responsible for the daily attendance of a class of 70–100+ students, and for the Students in that class who need to see their own attendance standing.

The product intent is calm, reliable bookkeeping under pressure: a CR standing in a lecture hall, phone held one-handed, marking a large roster quickly by USN, roll number, or name — by tap or by voice — while every percentage shown anywhere in the product is computed from the database and updates immediately after each committed change. The audience is two roles only: the CR, who owns all attendance-taking, correction, roster, subject, timetable, reporting, and audit work; and the Student, who reads their own overall percentage, subject-wise attendance, and attendance history and never edits attendance.

The application must be fully functional, fast, mobile-friendly, reliable, and production-quality — not a mockup or static prototype — with no placeholder or TODO functionality.

2. System Overview

The system is a web application with a React + TypeScript + Tailwind/shadcn frontend, a Node.js + Express backend, PostgreSQL persistence through Prisma, and JWT authentication with role-based access for the CR and Student roles.

Current delivery covers:

• Anonymous entry through Landing, and role-aware identity through Login (first-use enrollment and returning verification on the same neutral surface).
• CR-only working surfaces: Dashboard, Take Attendance, Attendance History, Voice Attendance, Import Students, Subjects, Timetable, Reports, and Audit Log.
• A Student-only surface: Student Profile.
• Backend-owned work that no human operates directly: transactional attendance persistence, database-derived percentage computation, audit recording, rate limiting, validation, and offline-change reconciliation.

Narrow exclusions and boundaries:

• Students have no attendance-editing capability of any kind.
• QR attendance is optional and, where present, is an additional capture path into the same attendance state system — it is not a separate product capability or destination.
• Voice recognition uses the Web Speech API with an optional Whisper/Vosk fallback; the fallback is optional, not a required second engine.
• No capability beyond the accepted thread is in scope: no fee, exam, leave-approval, messaging, or timetable-solver functionality.

2a. Product Interpretation and Delivery Boundary

The product is delivered as a first-party web application with application-owned identity. Because the CR controls shared, consequential attendance records and the Student reads private attendance data, identity must be established before any protected surface is reachable, and the role bound to that identity determines which surfaces are available. The anonymous entry surface (Landing) and the identity surface (Login) are reachable without a session; every other page requires an authenticated session and the correct role.

First-use enrollment and returning verification both happen on Login, which is the single neutral identity surface for both roles; the role is established as part of that identity step, so no protected destination owns the interaction that grants access to itself. Attendance changes are only authoritative once committed transactionally to PostgreSQL; offline-safe attendance state is held locally and reconciled before it becomes an authoritative record. All percentages displayed anywhere are derived from the database, never from client-side arithmetic over a stale snapshot.

Everything described in this document is current. No future-horizon capability is claimed.

2b. Source Content Inventory

Not applicable — no reference directive in this project declares a content_source.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous first impression of the product: what college-attendance is, that it serves a Class Representative managing 70–100+ students and the Students in that class, and that attendance can be taken by tap or by voice with percentages computed from the database.
• Primary action: Proceed to Login to enroll or sign in.
• Supporting actions: Read the short explanation of the CR and Student roles and what each can do.
• Domain entities: None persisted; presentation only.
• Component responsibilities: Paper-field hero composition (class-name-scale ink line, hairline rule, live-state numeral treatment, circular voice button motif as a static visual), role explanation block, single ink-slab entry control.
• States: Loading (minimal, static content renders immediately); empty (not applicable); success (renders); error (if the app shell fails to load, a single line of type with a retry link); recovery (retry reloads the shell).

Login

• Information/state: Neutral identity surface for both roles. First-use enrollment fields (name, identifier, role selection between CR and Student, credential) and returning verification fields (identifier, credential). Session state: unauthenticated, submitting, authenticated.
• Primary action: Enroll on first use, or verify credentials on return.
• Supporting actions: Switch between enrollment and verification; correct a validation error in place.
• Domain entities: User identity with bound role (CR or Student), session token.
• Component responsibilities: Form with inline field-level validation, role selector, submit control, single-line error region, post-success routing to the role's landing surface (CR → Dashboard, Student → Student Profile).
• States: Loading (submit in progress, control disabled); empty (blank form); success (session established, routed by role); error (invalid credentials, duplicate identifier on enrollment, missing required field — each as a single line of type in place); recovery (correct the field and resubmit; rate-limited attempts surface a clear wait message).

Dashboard

• Information/state: Total students, present count, absent count, attendance percentage, attendance trends, and low-attendance alerts — all computed from the database.
• Primary action: Read the current class attendance standing.
• Supporting actions: Move to Take Attendance to start a session; open a low-attendance alert to the relevant student context; open Reports for deeper analytics.
• Domain entities: Class roster, attendance sessions, attendance records, derived percentages, low-attendance thresholds.
• Component responsibilities: One dominant percentage numeral with a hairline rule beneath it; three label/value pairs (total, present, absent) aligned on a shared baseline; a single hairline sparkline for trends; a low-attendance list rendered as margin notes (thin rule plus ink percentage), never as coloured badges.
• States: Loading (skeleton rules, no spinners that shout); empty (no attendance recorded yet — a large paper area with one line of type and one thin rule); success (numerals and sparkline render); error (single line of type with retry); recovery (retry refetches; stale values are never shown as current).

Take Attendance

• Information/state: Mobile-first attendance workspace for the current session: each student row shows USN (tabular, muted, fixed column), roll number, and name, with three mark cells — Present, Absent, Leave. Live present count and session state (unsaved changes, saving, saved, offline-pending).
• Primary action: Mark each student Present, Absent, or Leave by tap.
• Supporting actions: Mark all present; bulk actions across a filtered selection; undo the last change; filter the roster; edit previous attendance by opening a prior session; optional QR capture into the same state; save the session.
• Domain entities: Session, subject/period context, student, attendance record with status, local pending-change queue.
• Component responsibilities: Ruled register (hairline-separated rows, 56px tall on mobile), mark cells using the status mark language (filled ink dot = present, hollow ring = absent, thin diagonal stroke = leave), bulk-action bar, undo control, filter control, save control, offline indicator, QR capture entry point when enabled.
• States: Loading (ruled skeleton rows); empty (no students in roster — one line of type plus a link to Import Students); success (marks fill over 120ms, present count updates, save confirms with a single line of type and the ink seal); error (save failure — single line of type, changes retained locally, retry available); recovery (undo reverses a mark; offline changes queue and reconcile on reconnect before becoming authoritative).

Attendance History

• Information/state: Revisitable record of previous attendance sessions with their date, subject/period, and per-student statuses; filters by date range, subject, and status.
• Primary action: Open a previous session to review or edit its attendance.
• Supporting actions: Filter the session list; apply bulk actions within a session; undo an edit; navigate back to Take Attendance for the current session.
• Domain entities: Attendance sessions, attendance records, edit history entries.
• Component responsibilities: Session list with hairline separation, filter bar, session detail register reusing the same mark language and the same validation/state system as Take Attendance, undo control, save control.
• States: Loading (ruled skeleton); empty (no sessions recorded — one line of type and one thin rule); success (session opens with current statuses); error (load or save failure as a single line of type with retry); recovery (undo restores the prior status; failed saves retain edits locally).

Voice Attendance

• Information/state: Voice-driven attendance context: listening state (idle, listening, processing, confirming), recognized transcript, matched student candidates with confidence, pending "Did you mean?" disambiguation, and the shared session state.
• Primary action: Speak roll numbers, USNs, or student names to mark attendance.
• Supporting actions: Issue commands — present, absent, leave, undo, clear, save, mark-all-present; switch between continuous listening and push-to-talk/wake-word modes; run microphone testing; adjust confidence thresholds; receive voice confirmations.
• Domain entities: Session, student, attendance record, recognition result with confidence score, disambiguation candidate set.
• Component responsibilities: 96px (72px mobile) circular voice button with 1px ink ring; expanding persimmon ring and pulsing persimmon dot while listening; transcript line; candidate list for "Did you mean?"; command reference; microphone test panel; mode selector; threshold control; voice confirmation line.
• States: Loading (initializing recognition engine); empty (no speech yet — one line of type); success (confident match marks the student through the shared state system and a single line of confirmation appears); error (microphone permission denied, engine unavailable, or fallback unavailable — single line of type with recovery guidance); recovery (uncertain matches are never auto-marked; the CR resolves via "Did you mean?" or repeats the input; duplicate markings are prevented).

Import Students

• Information/state: Upload state, parsed rows, per-row validation results (valid, warning, error with reason), and a preview of what will be persisted.
• Primary action: Upload an Excel or CSV roster file and confirm the import.
• Supporting actions: Review the validation preview; correct or exclude invalid rows; cancel the import.
• Domain entities: Student records (USN, roll number, name), import batch, validation findings.
• Component responsibilities: File drop/select control, validation summary, preview table with hairline separation and per-row status, confirm and cancel controls.
• States: Loading (parsing file); empty (no file selected — one line of type and one thin rule); success (rows persisted, summary line shown); error (unreadable file, wrong columns, duplicate USN — each as a single line of type with the offending rows identified); recovery (fix the file and re-upload, or exclude invalid rows and import the remainder).

Subjects

• Information/state: List of attendance subjects with their identifying details and current association to attendance sessions.
• Primary action: Create a subject.
• Supporting actions: Edit a subject; remove a subject that is not required by existing records.
• Domain entities: Subject.
• Component responsibilities: Subject list with hairline separation, create/edit form, delete confirmation as a single line of type.
• States: Loading (ruled skeleton); empty (no subjects — one line of type and one thin rule); success (subject appears in the list and becomes selectable in attendance contexts); error (validation failure or delete blocked by existing records — single line of type); recovery (correct the field or resolve the dependency and retry).

Timetable

• Information/state: The class timetable mapping days and periods to subjects, used to give attendance sessions their subject/period context.
• Primary action: Add a timetable entry.
• Supporting actions: Edit an entry; remove an entry.
• Domain entities: Timetable entry (day, period, subject).
• Component responsibilities: Timetable grid or ruled list, entry form, conflict indication as a single line of type.
• States: Loading (ruled skeleton); empty (no entries — one line of type and one thin rule); success (entry appears and is available when starting an attendance session); error (conflicting or invalid entry — single line of type); recovery (adjust the entry and retry).

Reports

• Information/state: Attendance analytics across the class and per student, with the current filter set (date range, subject, student) and export state.
• Primary action: Generate the report view for the chosen filters.
• Supporting actions: Export as CSV, Excel, or PDF.
• Domain entities: Attendance records, derived percentages, export artifacts.
• Component responsibilities: Filter bar, analytics presentation using numerals-as-ornament and hairline sparklines (no filled area charts, no donut gauges), export controls, export progress and completion line.
• States: Loading (ruled skeleton); empty (no data for the filter set — one line of type and one thin rule); success (report renders; export downloads); error (export generation failure — single line of type with retry); recovery (adjust filters or retry the export).

Audit Log

• Information/state: Chronological record of every attendance edit, showing what changed, from what to what, when, and by whom.
• Primary action: Review the edit history.
• Supporting actions: Filter by date, student, subject, or actor; open the related session.
• Domain entities: Audit entry (attendance record reference, previous status, new status, timestamp, actor).
• Component responsibilities: Ruled chronological list, filter bar, entry detail.
• States: Loading (ruled skeleton); empty (no edits recorded — one line of type and one thin rule); success (entries render in order); error (load failure — single line of type with retry); recovery (retry refetches).

Student Profile

• Information/state: The signed-in Student's own attendance record: overall percentage, subject-wise attendance, and attendance history — all computed from the database.
• Primary action: Read own attendance standing.
• Supporting actions: Filter history by subject or date range.
• Domain entities: Student, attendance records, derived overall and subject-wise percentages.
• Component responsibilities: Dominant overall percentage numeral with hairline rule, subject-wise list with per-subject percentage, history list with hairline separation, low-attendance indication as a margin note.
• States: Loading (ruled skeleton); empty (no attendance recorded yet — one line of type and one thin rule); success (percentages and history render); error (load failure — single line of type with retry); recovery (retry refetches).

3. Functional Requirements

FR-1 — Role-based login. As a Class Representative or a Student, I should log in with role-based access so that I reach only the surfaces my role permits. (provenance: explicit; lifecycle: initiator = CR or Student; trigger = submitting credentials on Login; observable result = authenticated session bound to the correct role, routed to Dashboard for CR and Student Profile for Student; access state = anonymous entry, protected state unavailable until identity is established; failure/recovery = invalid credentials or duplicate identifier produce a single-line error and the form can be corrected and resubmitted, with rate-limited attempts surfaced clearly; continuation = the role's landing surface loads with database-derived data.)

FR-2 — First-use enrollment and returning verification. As a Class Representative or a Student, I should establish my identity on first use and verify it on return so that my role is bound before any protected access. (provenance: required_inference; lifecycle: initiator = CR or Student; trigger = first visit to Login or a later return; observable result = identity created with the correct role, or an existing session restored; access state = anonymous entry on the same neutral surface for both roles; failure/recovery = validation errors shown in place and correctable; continuation = routing by role.)

FR-3 — Dashboard totals and percentages. As a Class Representative, I should see total students, present count, absent count, and attendance percentage on the Dashboard so that I know the class standing at a glance. (provenance: explicit; lifecycle: initiator = CR; trigger = opening Dashboard; observable result = totals and percentage rendered from database-derived values; access state = authenticated CR; failure/recovery = load failure shows a single line of type with retry and never presents stale values as current; continuation = drill into Take Attendance or Reports.)

FR-4 — Dashboard trends. As a Class Representative, I should see attendance trends on the Dashboard so that I can judge direction over time. (provenance: explicit; lifecycle: initiator = CR; trigger = opening Dashboard; observable result = a single hairline sparkline of attendance over time; access state = authenticated CR; failure/recovery = trend unavailable shows a single line of type; continuation = open Reports for detail.)

FR-5 — Low-attendance alerts. As a Class Representative, I should see low-attendance alerts on the Dashboard so that I can identify students who need attention. (provenance: explicit; lifecycle: initiator = CR; trigger = opening Dashboard; observable result = students below the low-attendance threshold listed as typographic margin notes with their percentage in ink; access state = authenticated CR; failure/recovery = alert computation failure shows a single line of type with retry; continuation = open the student's context or Reports.)

FR-6 — Mobile-first Take Attendance with identifiers and statuses. As a Class Representative, I should take attendance on a mobile-first screen showing USN, roll number, and name with Present/Absent/Leave controls so that I can mark a large roster quickly one-handed. (provenance: explicit; lifecycle: initiator = CR; trigger = opening Take Attendance for a session; observable result = each student row shows USN, roll number, name, and three mark cells, and a tap sets the status; access state = authenticated CR; failure/recovery = save failure retains changes locally with a single-line error and retry; continuation = save the session or continue marking.)

FR-7 — Mark all present. As a Class Representative, I should mark all present in one action so that a mostly-present class is recorded quickly. (provenance: explicit; lifecycle: initiator = CR; trigger = invoking mark-all-present; observable result = every student in scope is set to Present and the present count updates; access state = authenticated CR; failure/recovery = undo reverses the action; continuation = adjust individual exceptions and save.)

FR-8 — Bulk actions. As a Class Representative, I should apply bulk actions to a filtered selection so that groups of students can be marked together. (provenance: explicit; lifecycle: initiator = CR; trigger = selecting students and choosing a bulk status; observable result = all selected students take the chosen status; access state = authenticated CR; failure/recovery = undo reverses the bulk change; continuation = save or continue editing.)

FR-9 — Undo. As a Class Representative, I should undo my last attendance change so that a mistaken mark is corrected immediately. (provenance: explicit; lifecycle: initiator = CR; trigger = invoking undo; observable result = the previous status is restored and the mark reverses over 120ms; access state = authenticated CR; failure/recovery = if undo is unavailable, the CR can set the status directly; continuation = continue marking or save.)

FR-10 — Filters. As a Class Representative, I should filter the roster and history so that I can find students and sessions quickly. (provenance: explicit; lifecycle: initiator = CR; trigger = applying a filter; observable result = the list narrows to matching students or sessions; access state = authenticated CR; failure/recovery = clearing the filter restores the full list; continuation = act on the filtered set.)

FR-11 — Edit previous attendance. As a Class Representative, I should edit previous attendance so that historical records can be corrected. (provenance: explicit; lifecycle: initiator = CR; trigger = opening a prior session from Attendance History; observable result = the prior session's statuses are editable through the same validation/state system and the change is persisted transactionally; access state = authenticated CR; failure/recovery = save failure retains edits locally with a single-line error and retry; continuation = the corrected record is reflected in percentages and in the Audit Log.)

FR-12 — Voice attendance marking. As a Class Representative, I should say roll numbers, USNs, or student names and have attendance marked instantly so that I can record a large class without tapping. (provenance: explicit; lifecycle: initiator = CR; trigger = speaking while listening is active; observable result = the matched student is marked through the same validation/state system as manual marking, with a single line of voice confirmation; access state = authenticated CR; failure/recovery = no match or low confidence produces no automatic marking and offers "Did you mean?"; continuation = resolve the candidate or continue speaking.)

FR-13 — Voice commands. As a Class Representative, I should issue the commands present, absent, leave, undo, clear, save, and mark-all-present by voice so that the whole session can be driven hands-free. (provenance: explicit; lifecycle: initiator = CR; trigger = speaking a command; observable result = the corresponding action is applied to the shared attendance state; access state = authenticated CR; failure/recovery = an unrecognized command produces a single line of type and no state change; continuation = repeat the command or act manually.)

FR-14 — Confidence-based matching with no automatic uncertain marking. As a Class Representative, I should have uncertain students never marked automatically, with a "Did you mean?" option shown instead, so that incorrect attendance is never recorded silently. (provenance: explicit; lifecycle: initiator = CR; trigger = a recognition result below the confidence threshold; observable result = no status change occurs and a candidate list is presented for the CR to choose from; access state = authenticated CR; failure/recovery = dismissing the candidates leaves the student unmarked; continuation = choose a candidate, repeat the input, or mark manually.)

FR-15 — Shared validation and state for voice and manual. As a Class Representative, I should have voice and manual attendance use the same validation and state system so that both paths produce identical, consistent records. (provenance: explicit; lifecycle: initiator = CR; trigger = any marking action from either path; observable result = the same validation rules, the same session state, and the same persistence path apply; access state = authenticated CR; failure/recovery = a validation rejection from either path surfaces the same single-line error; continuation = correct and retry.)

FR-16 — Voice engine, language, and modes. As a Class Representative, I should use the Web Speech API with an optional Whisper/Vosk fallback, en-IN recognition, continuous listening, and push-to-talk/wake-word modes so that voice attendance works in a real lecture hall. (provenance: explicit; lifecycle: initiator = CR; trigger = activating voice and choosing a mode; observable result = recognition runs in the selected mode with en-IN as the language; access state = authenticated CR; failure/recovery = if the primary engine is unavailable, the optional fallback is used when configured, otherwise a single line of type explains the limitation; continuation = continue in the working mode.)

FR-17 — Microphone testing. As a Class Representative, I should test my microphone before a session so that recognition failures are not discovered mid-lecture. (provenance: explicit; lifecycle: initiator = CR; trigger = running the microphone test; observable result = input level and recognition responsiveness are shown; access state = authenticated CR; failure/recovery = permission denial or no input is reported as a single line of type with guidance; continuation = proceed to voice attendance once the test passes.)

FR-18 — Confidence thresholds and voice confirmations. As a Class Representative, I should set confidence thresholds and receive voice confirmations so that recognition behaves predictably and I know what was recorded. (provenance: explicit; lifecycle: initiator = CR; trigger = adjusting the threshold or completing a marking action; observable result = the threshold governs the auto-mark boundary and a single line of confirmation states what was recorded; access state = authenticated CR; failure/recovery = a threshold that suppresses all auto-marking still allows "Did you mean?" resolution; continuation = continue the session.)

FR-19 — Duplicate and incorrect marking prevention. As a Class Representative, I should have duplicate or incorrect markings prevented so that the record stays trustworthy. (provenance: explicit; lifecycle: initiator = CR; trigger = a repeated or conflicting marking input; observable result = the existing status is not duplicated and the state remains consistent; access state = authenticated CR; failure/recovery = the CR can still change the status deliberately; continuation = continue the session.)

FR-20 — Student profiles with overall, subject-wise, and history. As a Student, I should see my overall percentage, subject-wise attendance, and attendance history so that I know my standing. (provenance: explicit; lifecycle: initiator = Student; trigger = opening Student Profile; observable result = overall percentage, per-subject percentages, and history render from database-derived values; access state = authenticated Student, own record only; failure/recovery = load failure shows a single line of type with retry; continuation = filter history by subject or date.)

FR-21 — Subject management. As a Class Representative, I should manage subjects so that attendance is recorded against the right subject. (provenance: explicit; lifecycle: initiator = CR; trigger = creating, editing, or removing a subject; observable result = the subject list reflects the change and subjects become selectable in attendance contexts; access state = authenticated CR; failure/recovery = validation failure or a delete blocked by existing records is reported as a single line of type; continuation = correct and retry.)

FR-22 — Timetable management. As a Class Representative, I should manage the timetable so that attendance sessions carry the correct subject and period context. (provenance: explicit; lifecycle: initiator = CR; trigger = adding, editing, or removing a timetable entry; observable result = the timetable reflects the change and is available when starting a session; access state = authenticated CR; failure/recovery = a conflicting or invalid entry is reported as a single line of type; continuation = adjust and retry.)

FR-23 — Reports and analytics. As a Class Representative, I should view reports and analytics so that I can analyse attendance across the class and per student. (provenance: explicit; lifecycle: initiator = CR; trigger = opening Reports and choosing filters; observable result = analytics render from database-derived values; access state = authenticated CR; failure/recovery = no data for the filter set shows a single line of type; continuation = adjust filters or export.)

FR-24 — CSV, Excel, and PDF export. As a Class Representative, I should export reports as CSV, Excel, and PDF so that attendance can be shared and archived. (provenance: explicit; lifecycle: initiator = CR; trigger = choosing an export format; observable result = a file in the chosen format is produced from the current report; access state = authenticated CR; failure/recovery = export generation failure shows a single line of type with retry; continuation = retry or change filters.)

FR-25 — Excel/CSV student import with validation and preview. As a Class Representative, I should import students from Excel or CSV with validation and preview so that the roster is correct before it is persisted. (provenance: explicit; lifecycle: initiator = CR; trigger = uploading a roster file; observable result = parsed rows are validated and previewed with per-row findings before confirmation; access state = authenticated CR; failure/recovery = unreadable files, wrong columns, or duplicate USNs are reported with the offending rows identified, and invalid rows can be excluded; continuation = confirm the import and see the roster updated.)

FR-26 — Audit log for every attendance edit. As a Class Representative, I should have every attendance edit recorded in an audit log so that changes are traceable. (provenance: explicit; lifecycle: initiator = CR (edits) and CR (review); trigger = any attendance edit; observable result = an audit entry records what changed, from what to what, when, and by whom, and is reviewable in Audit Log; access state = authenticated CR; failure/recovery = load failure shows a single line of type with retry; continuation = filter or open the related session.)

FR-27 — Optional QR attendance. As a Class Representative, I should optionally capture attendance by QR so that a second capture path is available when useful. (provenance: explicit, optional; lifecycle: initiator = CR; trigger = enabling QR capture within the attendance workspace; observable result = a QR-captured mark enters the same validation/state system as manual and voice marking; access state = authenticated CR; failure/recovery = an unreadable or invalid code produces no marking and a single line of type; continuation = mark manually or retry the code.)

FR-28 — Light/dark mode and accessible responsive UI. As a Class Representative or a Student, I should use the app in light or dark mode with an accessible, responsive interface so that it is usable in a lecture hall and on any device. (provenance: explicit; lifecycle: initiator = CR or Student; trigger = toggling the theme or resizing the viewport; observable result = the interface switches between the paper-light and ink-dark variants and remains fully legible and operable at 375px, 768px, and 1280px; access state = any authenticated surface; failure/recovery = a persisted theme preference that cannot be read falls back to light; continuation = continue working.)

FR-29 — Database-derived percentages that update immediately. As a Class Representative or a Student, I should see attendance percentages calculated from the database that update immediately after changes so that what I see is always current. (provenance: explicit; lifecycle: initiator = CR or Student; trigger = any committed attendance change or a page load; observable result = displayed percentages are database-derived and refresh after the change commits; access state = authenticated CR or Student; failure/recovery = if a refresh fails, stale values are not presented as current and a single line of type with retry is shown; continuation = the refreshed values are used.)

FR-30 — Secure authentication, validation, rate limiting, and transactions. As a Class Representative or a Student, I should have my session secured and my changes validated, rate-limited, and committed transactionally so that the record is trustworthy. (provenance: explicit; lifecycle: initiator = CR or Student; trigger = any authenticated request or attendance write; observable result = requests are authenticated and validated, abusive rates are limited, and attendance writes commit atomically; access state = authenticated session required for protected operations; failure/recovery = rejected requests return a clear single-line error and no partial write occurs; continuation = correct and retry.)

FR-31 — Offline-safe attendance state. As a Class Representative, I should have attendance state remain safe when connectivity drops so that a session is not lost mid-lecture. (provenance: explicit; lifecycle: initiator = CR; trigger = connectivity loss during marking; observable result = changes are held locally and the session remains usable with a visible offline indicator; access state = authenticated CR; failure/recovery = on reconnect, held changes reconcile before becoming authoritative persisted records, and conflicts are surfaced rather than silently overwritten; continuation = the reconciled session is saved and reflected in percentages.)

FR-32 — Seed data and demo credentials. As a Class Representative or a Student, I should have seed data for approximately 85 students and working demo credentials so that the application can be evaluated immediately. (provenance: explicit; lifecycle: initiator = CR or Student; trigger = running the seeded environment; observable result = a populated roster and usable demo credentials for both roles; access state = Login; failure/recovery = a failed seed run reports a single line of type and can be re-run; continuation = log in and use the app.)

FR-33 — Docker setup, tests, and README. As a developer or evaluator, I should have a Docker setup, tests, and a README so that the application can be run and verified. (provenance: explicit; lifecycle: initiator = developer/evaluator (non-persona delivery actor); trigger = following the README; observable result = the stack starts via Docker and the test suite runs; access state = not applicable; failure/recovery = startup or test failures are reported with actionable output; continuation = the running application is exercised.)

FR-34 — No placeholder or TODO functionality. As a Class Representative or a Student, I should encounter no placeholder or TODO functionality so that every visible capability actually works. (provenance: explicit; lifecycle: initiator = CR or Student; trigger = using any capability; observable result = the capability performs its real function against real persistence; access state = as per the surface; failure/recovery = genuine errors are reported as real errors, never as stubs; continuation = the workflow completes.)

4. User Personas

Class Representative (CR)

Product context. The CR is the sole operator of attendance for a class of 70–100+ students. They work standing in a lecture hall, phone held one-handed, often speaking roll numbers over ambient noise, and they must not look flashy or distracted in front of a professor. Their tool must be quiet, fast, and legible in sunlight.

Primary goal. Record accurate attendance for the whole class quickly — by tap or by voice — and keep every percentage in the product correct and current.

Distinct accepted responsibilities. The CR logs in with role-based access and owns: reading the Dashboard (totals, present, absent, percentage, trends, low-attendance alerts); taking attendance on the mobile-first Take Attendance screen using USN, roll number, and name with Present/Absent/Leave controls; mark-all-present, bulk actions, undo, filters, and editing previous attendance; voice attendance by speaking roll numbers, USNs, or names with the commands present, absent, leave, undo, clear, save, and mark-all-present; confidence-based matching where an uncertain student is never marked automatically and a "Did you mean?" option is offered; managing subjects and the timetable; importing students from Excel/CSV with validation and preview; producing reports and analytics with CSV, Excel, and PDF export; and reviewing the audit log of every attendance edit. The CR may optionally use QR capture.

Relevant inputs and decisions. Which session and subject/period is being recorded; each student's status; whether a low-confidence voice match should be accepted via "Did you mean?" or repeated; whether to mark all present and then correct exceptions; whether an imported row is valid enough to persist; whether a previous session needs correction.

Interactions with other accepted participants. The CR's attendance decisions directly determine what each Student sees on Student Profile. The CR is the only participant who writes attendance; the Student is the only other participant and is a reader of the CR's records.

Observable success. Attendance percentages computed from the database update immediately after each change; low-attendance alerts identify the right students; a session survives connectivity loss and reconciles correctly; the audit log shows every edit; the interface stays legible and operable on a phone in a lecture hall.

Student

Product context. The Student is a member of the class whose attendance is recorded by the CR. They check their standing between or after lectures, usually on a phone, and they have no role in recording attendance.

Primary goal. See an accurate, current picture of their own attendance standing.

Distinct accepted responsibilities. The Student logs in with role-based access and views their own attendance record on Student Profile: overall percentage, subject-wise attendance, and attendance history, all calculated from the database. They may filter their history by subject or date range.

Relevant inputs and decisions. Which subject or date range to inspect; whether their current standing warrants action with the CR outside the product.

Interactions with other accepted participants. The Student is the recipient of the CR's attendance decisions; the Student's view is entirely determined by records the CR created and edited. The Student never edits attendance and never sees other students' records.

Observable success. The overall percentage, subject-wise percentages, and history match the CR's records exactly and reflect the most recent committed changes.

5. Core User Flows

Flow 1 — CR first-use enrollment and returning login

1. The CR opens the application and lands on Landing, which explains the product and its CR and Student audiences.
2. The CR proceeds to Login and chooses first-use enrollment, entering their name, identifier, the CR role, and a credential.
3. The system validates the input; on success it creates the identity with the CR role bound and establishes a session.
4. The CR is routed to Dashboard, which loads totals, present and absent counts, attendance percentage, trends, and low-attendance alerts from the database.
5. On a later visit, the CR returns to Login, verifies credentials, and is routed to Dashboard again.
6. Failure/recovery: an invalid credential or duplicate identifier produces a single line of type in place; the CR corrects the field and resubmits. Rate-limited attempts surface a clear wait message. Continuation: the CR proceeds to take attendance.

Flow 2 — Student first-use enrollment and returning login

1. The Student opens the application and lands on Landing.
2. The Student proceeds to Login, enrolls with their name, identifier, the Student role, and a credential, and the system binds the Student role to the identity.
3. The Student is routed to Student Profile, which loads their overall percentage, subject-wise attendance, and attendance history from the database.
4. On a later visit, the Student verifies credentials on Login and returns to Student Profile.
5. Failure/recovery: validation errors are shown in place and correctable; rate-limited attempts surface a clear wait message. Continuation: the Student filters history by subject or date range.

Flow 3 — CR takes attendance manually for a session

1. The CR opens Take Attendance for the current session, with the subject/period context available from the timetable.
2. The ruled register renders each student as a row: USN in a fixed tabular column, roll number, name, and three mark cells.
3. The CR taps Present, Absent, or Leave for each student; the mark fills over 120ms and the live present count updates.
4. The CR uses mark all present to set the whole class present, then corrects individual exceptions.
5. The CR applies bulk actions to a filtered selection where a group shares a status.
6. The CR taps undo to reverse the most recent change when a mark was wrong.
7. The CR taps save; the session commits transactionally and a single line of confirmation with the ink seal appears.
8. Failure/recovery: if the save fails, changes are retained locally, a single line of type explains the failure, and the CR retries. Continuation: percentages on Dashboard and Student Profile reflect the committed change immediately.

Flow 4 — CR takes attendance by voice

1. The CR opens Voice Attendance and runs the microphone test to confirm input is working.
2. The CR selects continuous listening or push-to-talk/wake-word mode and sets the confidence threshold.
3. The CR activates the 96px circular voice button; the 1px ink ring expands and the persimmon dot pulses, making the listening state unmistakable.
4. The CR speaks a roll number, USN, or student name. A confident match marks that student through the same validation/state system as manual marking, and a single line of voice confirmation states what was recorded.
5. The CR speaks commands — present, absent, leave, undo, clear, save, mark-all-present — and each applies to the shared attendance state.
6. Failure/recovery: if the match is uncertain, no student is marked automatically; a "Did you mean?" candidate list appears and the CR chooses the correct student, repeats the input, or marks manually. Duplicate or conflicting inputs do not create duplicate markings. If the primary engine is unavailable, the optional Whisper/Vosk fallback is used when configured; otherwise a single line of type explains the limitation. Continuation: the CR saves the session and the committed changes are reflected in percentages and in the Audit Log.

Flow 5 — CR edits previous attendance

1. The CR opens Attendance History and filters by date range, subject, or status.
2. The CR opens a previous session; its statuses render in the same register and mark language used in Take Attendance.
3. The CR changes one or more statuses, applies a bulk action, or taps undo to reverse an edit.
4. The CR saves; the change commits transactionally and an audit entry records what changed, from what to what, when, and by whom.
5. Failure/recovery: a failed save retains the edits locally with a single line of type and a retry. Continuation: the corrected record is visible in Audit Log, and the affected percentages update immediately.

Flow 6 — CR imports the student roster

1. The CR opens Import Students and selects an Excel or CSV file.
2. The system parses the file and validates each row, showing a preview with per-row findings.
3. The CR reviews the preview, excludes invalid rows, and confirms the import.
4. The roster is persisted and the new students appear in attendance contexts.
5. Failure/recovery: an unreadable file, wrong columns, or duplicate USNs are reported with the offending rows identified; the CR fixes the file and re-uploads or excludes the rows. Continuation: the CR takes attendance for the updated roster.

Flow 7 — CR manages subjects and the timetable

1. The CR opens Subjects, creates a subject, and edits or removes subjects as needed.
2. The CR opens Timetable and adds entries mapping days and periods to subjects, editing or removing entries as needed.
3. Failure/recovery: validation failures and delete attempts blocked by existing records are reported as a single line of type; conflicting timetable entries are flagged. Continuation: the subject and period context is available when the CR next opens Take Attendance.

Flow 8 — CR reviews reports and exports

1. The CR opens Reports and sets filters for date range, subject, and student.
2. The analytics render from database-derived values using numerals-as-ornament and hairline sparklines.
3. The CR exports the report as CSV, Excel, or PDF.
4. Failure/recovery: an empty filter set shows a single line of type; an export generation failure shows a single line of type with retry. Continuation: the CR adjusts filters or retries the export.

Flow 9 — CR reviews the audit log

1. The CR opens Audit Log and reviews the chronological record of attendance edits.
2. The CR filters by date, student, subject, or actor, and opens the related session.
3. Failure/recovery: a load failure shows a single line of type with retry. Continuation: the CR returns to Attendance History or Take Attendance.

Flow 10 — CR works through a connectivity drop

1. Mid-session, connectivity drops while the CR is marking attendance on Take Attendance.
2. The session remains usable; changes are held locally and an offline indicator is visible.
3. When connectivity returns, the held changes reconcile before becoming authoritative persisted records.
4. Failure/recovery: conflicts are surfaced to the CR rather than silently overwritten. Continuation: the reconciled session is saved and the percentages update immediately.

Flow 11 — Student checks their attendance standing

1. The Student logs in and opens Student Profile.
2. The overall percentage renders as the dominant numeral with a hairline rule beneath it; subject-wise attendance and attendance history render below.
3. The Student filters history by subject or date range.
4. Failure/recovery: if no attendance has been recorded yet, a large paper area with one line of type and one thin rule is shown; a load failure shows a single line of type with retry. Continuation: the Student returns later and sees the most recent committed changes reflected.

Flow 12 — CR optionally captures attendance by QR

1. Within the attendance workspace, the CR enables QR capture.
2. A student's code is scanned and the resulting mark enters the same validation/state system as manual and voice marking.
3. Failure/recovery: an unreadable or invalid code produces no marking and a single line of type. Continuation: the CR marks manually or retries the code, then saves the session.

6. Visuals, Colors and Theme

The creative direction is authoritative for this section. The muse is Kenya Hara, and the headline idea is "Emptiness as attendance: paper-white ground, one ink mark per student, nothing that shouts." The register itself is the composition; the product's data is the design.

Color tokens

Light mode

Dark mode — an ink ground, not a colour inversion gimmick: background #1C1A18, surface #23211E, text #F7F5F0, primary #F7F5F0 (paper-white slabs with ink labels), accent #B4472E unchanged, muted #8C877E, hairline #3A3733. Equally quiet.

No blue anywhere in the system — no #0057FF, #2563EB, #4F46E5 or their neighbours, including focus rings. Focus is a 2px ink outline offset 2px.

Status is coded by ink weight and mark, not colour: present = filled 16px ink dot; absent = hollow 1px ring; leave = a single thin diagonal stroke. No red/green traffic lights, no coloured status pills.

Typography

• Family: Zen Kaku Gothic New only, for both headings and body. No Inter, Roboto, Poppins, Montserrat, or any geometric-grotesque default.
• Headings: weight 300–400, very large, tracking -0.01em, sentence case, never all-caps, never bold-shouting — size does the work, not weight.
• Numerals are the ornament: attendance percentages and roll numbers set at weight 700 in tabular figures, larger than their labels.
• Labels: 11–12px, weight 500, letter-spacing 0.14em, uppercase, muted — the only place caps appear.
• Scale: 1.25 modular with wide display steps — 13 / 15 / 18 / 24 / 34 / 52 / 76px. Display sizes clamp: hero 40px mobile → 76px desktop; page titles 28px → 40px; the live present-count numeral 44px mobile → 72px desktop.
• Body: 15px mobile / 16px desktop, line-height 1.75, measure capped at 62ch.

Shape language

Almost no shape. Hairline 1px rules in #E3DFD7 do the separating work. Where a container is unavoidable it is a plain white rectangle with a 2px radius — square proportions, no pill buttons, no soft-shadow floats. The only permitted curves are the circular student mark (16px filled dot / hollow ring) and the circular voice button (72px mobile, 96px desktop) with a 1px ink ring.

Layout

Centred single column on a paper field: max-width 720px for reading, 960px for the attendance sheet, with margins so generous that the first screen holds one idea. Take Attendance is a ruled register, not a card grid: each row is USN (tabular, muted, 96px fixed column) · name · three mark cells, separated by 1px hairlines, 56px tall on mobile for a thumb. The Dashboard is one enormous percentage numeral with a thin rule beneath it and three label/value pairs aligned on a shared baseline; trends are a single hairline sparkline with no filled area and no chart chrome. Section transitions are horizontal rules spanning the full column width. Navigation is a top hairline bar with a wordmark and a two-item ink/paper toggle — no sidebar, no icon soup.

Imagery

No photography, no illustration, no 3D. The imagery is the interface's own marks: the filled/hollow/diagonal attendance symbols, the hairline register, the hairline sparkline, and a single small hand-drawn ink seal used as the save confirmation. Empty states are a large area of paper with one line of type and one thin rule — emptiness is the content.

7. Signature Design Concept

The register as the hero. The public entry is not a marketing hero; it is the register itself, composed on a paper-white field.

• A 76px (40px mobile) ink line reading the class name sits flush left at the top, with a 1px rule beneath it spanning the full column.
• Beneath the rule, the live state of today's period: one enormous tabular numeral — the present count — at 72px desktop / 44px mobile, set in ink, with "of 85 present" in 13px muted caps on its baseline.
• To the right of that numeral, vertically centred, the 96px circular voice button with its 1px ink ring. When listening, the expanding persimmon ring is the only colour on the screen.
• The bottom two-thirds is the ruled student register, first eight rows visible, each row separated by a hairline, marks at the right edge.
• There is no gradient, no card, no coloured button, no image — the composition is type, rule, numeral, and one red pulse against paper.

This concept recomposes only accepted content, states, and controls: the class roster, the present count, the voice listening state, and the attendance marks. It introduces no new behaviour, page, or destination.

8. Interaction Model & Motion Direction

Interaction Model: Static Motion Tempo: still Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject: the ruled student register with its live present-count numeral and the single circular voice button — the product's own data as the composition.
• Input → transformation → outcome thesis: the CR's voice or tap is the input; the transformation is a single mark filling in the register and the present-count numeral incrementing; the outcome is a committed attendance record whose percentage is database-derived. Nothing else on the screen moves.
• Motion vocabulary: stillness with one deliberate exception. Screen changes are 200ms opacity crossfades with no translate. Marking a student fills the dot over 120ms; undo reverses it. Voice confirmations are a single line of text appearing in place, never a toast that flies in.
• Composed first frame: class-name ink line flush left, hairline rule beneath it, the 72px present-count numeral with its muted caps baseline label, the 96px ink-ringed voice button vertically centred to its right, and the first eight hairline-separated register rows below with marks at the right edge.
• The one continuous motion: the listening state — a 1px ink ring expanding from the voice button and fading over 1.6s, paired with the persimmon dot pulsing at 1.2s. It must clearly read as "the microphone is open."
• Reduced-motion state: under prefers-reduced-motion the expanding ring becomes a static persimmon outline and the pulsing dot becomes a steady fill; crossfades and mark fills resolve instantly.

No user-requested 3D/WebGL and no direction-derived webgl dimensionality apply, so no Canvas/R3F/Drei scene is required.

9. Non-Functional Requirements

• NFR-1 — Database-derived percentages. All attendance percentages must be calculated from the database and update immediately after changes. (provenance: explicit; rationale: the product's core trust guarantee.)
• NFR-2 — Transactional persistence. Attendance changes must commit transactionally so that no partial write is ever visible. (provenance: explicit; rationale: a partially written session would corrupt the record.)
• NFR-3 — Shared validation. Voice and manual attendance must use the same validation and state system. (provenance: explicit; rationale: two divergent paths would produce inconsistent records.)
• NFR-4 — No automatic uncertain marking. An uncertain student must never be marked automatically; a "Did you mean?" option is shown instead. (provenance: explicit; rationale: silent mis-marking is worse than no marking.)
• NFR-5 — Secure authentication. JWT authentication with role-based access for the CR and Student roles. (provenance: explicit; rationale: the CR controls shared records and the Student reads private data.)
• NFR-6 — Validation and rate limiting. Requests are validated and abusive rates are limited. (provenance: explicit; rationale: protects data integrity and availability.)
• NFR-7 — Offline-safe attendance state. Attendance state must remain safe through connectivity loss and reconcile before becoming authoritative. (provenance: explicit; rationale: sessions happen in lecture halls with unreliable connectivity.)
• NFR-8 — Voice engine requirements. Web Speech API with optional Whisper/Vosk fallback, en-IN, continuous listening, push-to-talk/wake-word modes, microphone testing, confidence thresholds, and voice confirmations. (provenance: explicit; rationale: recognition must work in a real Indian lecture hall.)
• NFR-9 — Duplicate and incorrect marking prevention. (provenance: explicit; rationale: repeated or conflicting inputs must not corrupt the record.)
• NFR-10 — Accessibility and responsiveness. Accessible, responsive UI, light/dark mode, legible in sunlight, operable at 375px, 768px, and 1280px. (provenance: explicit; rationale: the CR works one-handed on a phone.)
• NFR-11 — Performance. The application must be fast and mobile-friendly. (provenance: explicit; rationale: marking 85+ students must not be slowed by the tool.)
• NFR-12 — Production quality. No placeholder or TODO functionality; the application must be fully functional and production-quality, not a mockup or static prototype. (provenance: explicit; rationale: the deliverable is a working application.)
• NFR-13 — Deliverable completeness. Complete working frontend, backend, database schema/migrations, seed data for ~85 students, demo credentials, Docker setup, tests, and README. (provenance: explicit; rationale: the application must be runnable and verifiable.)

10. Tech Stack

Source-specified choices are preserved exactly:

• Frontend: React + TypeScript + Tailwind/shadcn.
• Backend: Node.js + Express.
• Database: PostgreSQL with Prisma, including schema and migrations, with real database persistence.
• Authentication: JWT with role-based access for CR and Student.
• Voice: Web Speech API, with optional Whisper/Vosk fallback.
• Export: CSV, Excel, and PDF generation for reports.
• Import: Excel/CSV parsing with validation and preview.
• Packaging: Docker setup (Docker/docker-compose) as an explicit deliverable.
• Tests: an automated test suite as an explicit deliverable.
• Documentation: README as an explicit deliverable.

Kubernetes is not required by any source statement and is not included.

11. Assumptions and Constraints

• A-1 — The class roster is on the order of 70–100+ students, with seed data for approximately 85 students. (source-stated)
• A-2 — The CR is the only participant who creates or edits attendance; the Student is a reader of their own record only. (source-stated)
• A-3 — Identity is application-owned, with first-use enrollment and returning verification on the single neutral Login surface; the role is bound at that step. (required_inference)
• A-4 — QR attendance is optional; where present it feeds the same validation/state system and is not a separate destination. (source-stated)
• A-5 — The Whisper/Vosk fallback is optional; the Web Speech API is the primary engine. (source-stated)
• A-6 — Low-attendance alerts require a threshold; the specific threshold value is not specified by the user and is treated as a configurable value rather than a fixed product rule. (unspecified qualifier retained)
• A-7 — Voice recognition quality depends on the browser's Web Speech API implementation and on microphone conditions in the lecture hall; the product mitigates this with confidence thresholds, microphone testing, and "Did you mean?" rather than guaranteeing recognition. (constraint)
• A-8 — Offline-safe state covers attendance marking during connectivity loss; reconciliation occurs before held changes become authoritative. (required_inference)
• A-9 — No capability outside the accepted thread is in scope; in particular, no fee, exam, leave-approval, messaging, or timetable-solver functionality is included. (boundary)
• A-10 — The visual system follows the supplied creative direction: no blue anywhere, no card grids with soft shadows, no pill buttons, no red/green status coding, no filled area charts, no flying toasts, and no geometric-grotesque default typefaces. (source-stated)

12. Glossary

• CR (Class Representative) — The accepted persona who owns all attendance-taking, correction, roster, subject, timetable, reporting, and audit work for the class.
• Student — The accepted persona who reads their own overall percentage, subject-wise attendance, and attendance history, and never edits attendance.
• USN — University Seat Number; a student's institutional identifier, displayed in a fixed tabular column in the register.
• Roll number — The student's roll number within the class, used alongside USN and name for identification and voice matching.
• Session — One attendance-taking instance for a subject and period, containing a status for each student.
• Attendance record — The persisted status (Present, Absent, or Leave) for one student in one session.
• Status mark language — Present = filled 16px ink dot; Absent = hollow 1px ring; Leave = a single thin diagonal stroke.
• Confidence threshold — The recognition confidence boundary above which a voice match may be applied automatically; below it, no automatic marking occurs and "Did you mean?" is offered.
• "Did you mean?" — The disambiguation candidate list shown when a voice match is uncertain, from which the CR selects the correct student.
• Audit entry — The record of an attendance edit capturing what changed, from what to what, when, and by whom.
• Low-attendance alert — A typographic margin note on the Dashboard identifying a student below the low-attendance threshold.
• Offline-safe state — Locally held attendance changes that remain usable during connectivity loss and reconcile before becoming authoritative persisted records.
• Reconciliation — The process by which held offline changes are committed and conflicts surfaced before the record becomes authoritative.