System Requirements Document for snowy-complete

1. Introduction

snowy-complete is a production-ready AI Exam Generator & Examination Platform. It exists so that an administrator can turn any supported document, text, or topic into a professional, quality-checked, assignable exam — and so that learners can sit that exam in a clean, distraction-free interface and receive an automatically scored result.

The product serves two audiences and two jobs:

• Training and certification authors (Admin) who need to convert existing material — PDF, DOC, DOCX, TXT, PPT, PPTX, CSV, XLSX, and images via OCR where available — or a plainly typed topic, into exam-ready questions with explanations, difficulty, marks, tags, and verifiable source references.
• Learners and staff being assessed (User) who authenticate with a username and PIN, see only the exams assigned to them, take an exam with automatic answer saving, and receive a stored, per-attempt result.

The platform is explicitly optimized for IT training content (Windows, Windows Server, Active Directory, Microsoft 365, networking, hardware, cybersecurity, help desk and similar domains) but is not restricted to IT — general educational and professional content must generate equally well.

The delivery target is a real, interconnected application, not static mockups: authentication, database persistence, AI generation, document processing, question management, exam creation, exam assignment, exam taking, scoring, results, analytics and exports must all function end to end, with all major buttons working.

2. System Overview

snowy-complete is a single first-party web application with a secure backend, a PostgreSQL/Supabase-compatible database, and a server-side LLM integration. The presentation layer is a premium Liquid Glass / iOS-inspired glassmorphism interface, responsive across desktop, tablet and mobile, with Light/Dark/System themes, smooth animations, modern typography and professional enterprise styling.

Current delivery. All accepted behavior is current. The application owns identity (username + PIN), persistence, generation orchestration, exam lifecycle, scoring, analytics and export generation.

Actors.

• Admin — explicit source-named ADMIN role. Owns the authoring pipeline end to end.
• User — explicit source-named USER role. Owns exam-taking only, and cannot access admin functions.

Non-persona participants. The LLM provider (server-side only), the document parsers and OCR engine, the PostgreSQL/Supabase database, and the PDF/CSV export renderer are typed non-persona actors: they perform work on behalf of an accepted human actor but are never a destination and never a persona.

Ownership. The Landing and Login surfaces are anonymously reachable. Every other destination is role-restricted: Dashboard, AI Generator, Question Review, Question Bank, Exam Builder, Exams, Assign Exams, Users, Results, Analytics, Exports and Settings are Admin-only; My Dashboard, Exam Interface and Result are User-only. The floating AI assistant is a cross-page Admin component, not a destination.

Navigation. The Admin sidebar presents the eight explicit navigation destinations — Dashboard, AI Generator, Question Bank, Exams, Users, Results, Analytics, Settings. Question Review, Exam Builder, Assign Exams and Exports are task-focused Admin workspaces entered from the destination that owns the work in progress (generation, exam authoring, exam management, and record collections respectively).

Narrow exclusions. No email/password login for normal users; only username + PIN. No filler questions when source material is insufficient. No answer exposure in printable exam output. No invented performance data in the AI performance report. No client-side AI API keys. No user access to admin functions.

2a. Product Interpretation and Delivery Boundary

Everything described in this document is current delivery. There is no deferred release, no provider-owned surface, and no headless-only path: the product is a first-party application with first-party pages and a first-party backend.

Access boundary. The Landing page and the Login surface are reachable without identity. Login is the single access boundary for both roles — it owns first-use enrollment (establishing a username and PIN) and returning verification, and it is the only surface that may establish access to the protected parts of the application. No protected destination owns the interaction that grants access to itself. After verification, the application routes by role: an Admin lands in the admin-only area, a User lands on their own dashboard.

Identity rationale. Application-owned identity is a confirmed delivery fact, and it is independently indispensable: a learner's attempts, answers, scores and results must remain bound to the correct person across sessions and devices, and an Admin's generated questions, exams and assignments must remain privately owned and resumable. Session continuity is therefore required, and sessions expire.

Permission boundary. Role separation is explicit in the source (Admin-only pages; users cannot access admin functions). Beyond the ADMIN/USER role gate, no differentiated visibility or permission model is specified, and none is introduced.

Demo configuration. Demo accounts (admin / 1234, demo / 1111) may be provided and must be clearly marked in the interface and in Settings as configurable, not fixed product constants.

Boundary of behavior not added. Nothing here introduces adjacent account management (no self-service password reset by email, no social login, no billing, no user-created courses), no notification system, and no exam-authoring capability beyond what the source states.

2c. Page Content and Component Coverage

Landing

• Information and state — Anonymous public entry. Hero title AI EXAM GENERATOR; subtitle "Turn Any Document Into a Professional Exam"; primary action CREATE EXAM; secondary action LOGIN. Feature cards: Any Document, AI Question Generation, Multiple Question Types, Smart Analytics, Simple User + PIN Login. No session state required; when an authenticated session already exists, the entry actions route to the role's home instead of re-authenticating.
• Primary actions — CREATE EXAM (begins the Admin generation journey through the Login gate when unauthenticated); LOGIN (opens the Login surface).
• Supporting actions — Theme toggle (Light / Dark / System); feature cards are descriptive only and do not create destinations; responsive reflow from multi-column desktop to stacked mobile.
• Domain entities — None owned; presents product capability statements only.
• Component responsibilities — HeroGlassPanel (title, subtitle, glass surface, gradient wash), EntryActionPair (CREATE EXAM, LOGIN), FeatureCardGrid (five named cards), ThemeToggle, GlassBackdrop (blur/transparency layer).
• States — Loading: static content, no async fetch; hero renders immediately. Empty: not applicable. Success: navigation to Login or the role home. Error: none owned. Recovery: none required.

Login

• Information and state — The single User + PIN access boundary. Fields: username and PIN. Two intents share this surface: first-use enrollment (establish username + PIN) and returning verification. Role is resolved server-side from the stored user record; the surface never asks the user to choose a role. Demo credentials, when enabled, are displayed with an explicit configurable marker.
• Primary actions — Verify credentials and establish a session; enroll a first-use identity; route by role to the Admin area or My Dashboard.
• Supporting actions — Reveal/hide PIN entry (never logging or echoing the raw PIN); switch between enrollment and verification; return to Landing; display demo credential hint when enabled.
• Domain entities — USERS (username, secure PIN hash, role, status, created date, last login). AUDIT_LOGS receives the authentication outcome.
• Component responsibilities — GlassAuthCard, UsernameField, PinField (masked, autocomplete-safe), IntentSwitch (first-use / returning), SubmitAction, InlineErrorRegion, DemoCredentialNotice.
• States — Loading: submit button enters a pending state and duplicate submits are suppressed. Empty: empty-field validation on submit. Success: session established, last login updated, role-based redirect. Error: invalid username or PIN (generic message that does not disclose which field failed); inactive user blocked with a distinct, non-credential-revealing message. Recovery: retry after correction, subject to rate limiting; no raw PIN is ever written to logs, responses or storage.

Dashboard

• Information and state — Admin home. Statistic tiles: Total Users, Total Exams, Total Questions, Completed Exams, Average Score, Pass Rate. Panels: Recent Exams, Recent AI Generations, Recent Activity. Performance charts rendered from stored data.
• Primary actions — Open a recent exam; open a recent AI generation; navigate into AI Generator, Question Bank, Exams, Users, Results, Analytics or Settings.
• Supporting actions — Chart range/hover inspection; refresh; empty-state navigation prompts.
• Domain entities — USERS, EXAMS, QUESTIONS, ATTEMPTS, RESULTS, DOCUMENTS, AUDIT_LOGS (activity feed).
• Component responsibilities — StatTileRow (six tiles), PerformanceChartSet, RecentExamsList, RecentGenerationsList, RecentActivityFeed, AdminSidebar (eight navigation destinations), AiAssistantOrb.
• States — Loading: skeleton tiles and chart placeholders. Empty: zero-state copy with a direct link to AI Generator when no exams exist. Success: tiles and charts reflect persisted aggregates. Error: a failed aggregate shows a retry affordance rather than fabricated numbers. Recovery: retry after database or network failure.

AI Generator

• Information and state — The visual centerpiece. Two intake methods: document upload (drag-and-drop; PDF, DOC, DOCX, TXT, PPT, PPTX, CSV, XLSX and images with OCR where available) and a large text/topic editor for manual entry or pasting. Below intake, the exam settings panel (question count, difficulty, difficulty distribution, question types, passing score, time limit, randomization and duplicate options). During generation, a staged progress region shows the seven processing messages in order, ending in ✓ Exam generated successfully.
• Primary actions — Drop or select a document; type/paste content or a topic; configure exam settings; run AI generation; disclose and resolve a high-confidence shortfall.
• Supporting actions — Remove/replace an uploaded file; clear the editor; set custom question count, custom duration, custom difficulty distribution; toggle Randomize questions, Randomize answers, Prevent duplicates; view the source document after ingestion.
• Domain entities — DOCUMENTS (name, type, extracted text, page/section index), generated QUESTION drafts, EXAMS settings payload, AUDIT_LOGS.
• Component responsibilities — DropZoneUploader (format validation, size feedback, OCR indication), TextTopicEditor, ExamSettingsPanel, DifficultyDistributionControl, QuestionTypeMultiSelect (eight types), GenerationProgressStepper (seven labeled stages), HighConfidenceShortfallDialog (reports the exact high-confidence count and asks whether general domain knowledge may be used), AiAssistantOrb.
• States — Loading: the seven-stage sequence — Analyzing document…, Extracting content…, Identifying topics…, Generating questions…, Checking quality…, Removing duplicates…, Preparing exam… — followed by ✓ Exam generated successfully. Empty: no file and no text → generation disabled with guidance. Success: generation completes and the