System Requirements Document for exam-prep

1. Introduction

exam-prep is an AI-powered exam and board preparation product for high-stakes, regulated careers — NCLEX nursing boards, CPA, real estate licenses, and bar exams. The product's intent is narrow and deliberate: a candidate preparing for a pass/fail licensing exam uses AI to generate realistic practice questions, to have their exact knowledge gaps diagnosed, and to receive on-demand explanations of the mistakes they make.

The audience is a working adult betting a $20–$50/month subscription — or a fixed test-pass pass — and months of their life on a single outcome. They are nurses on night shift, accountants studying after hours, and candidates who cannot afford to fail twice. They want a cockpit, not a classroom: exact numbers, exact gaps, no cheerleading.

This document specifies the current committed product: the exam-prep experience for the Exam Candidate. The broader market-opportunity brief that motivated the project also lists candidate concepts in other verticals (document and contract analysis, niche diet coaching, elder-care coordination, subscription-leakage tracking, creator revenue dashboards, and hyperlocal home-maintenance marketplaces). Those concepts are recorded here as future candidates only; they are not current product scope, and no page, persona, or requirement in this document implements them.

2. System Overview

exam-prep is delivered as a mobile-first application experience with a public entry surface and a protected candidate workspace. The current committed capability set is:

• AI-generated realistic practice questions for a selected regulated exam (NCLEX, CPA, BAR, REALTOR).
• Exact knowledge-gap diagnosis across the exam's domains, expressed as per-domain readiness.
• On-demand explanations of mistakes, opened from a wrong answer.
• A readiness instrument — a live readiness percentage, per-domain readiness rows, and a days-to-exam countdown — that is the product's central promise rather than a decorative statistic.
• Monetization as a $20–$50/month subscription or a fixed test-pass pass.

Actors:

• Exam Candidate (human, active) — the sole accepted active human persona for the current product.
• AI question-and-diagnosis service (system actor) — generates practice questions, produces gap diagnosis, and produces mistake explanations. It is not a persona and has no page of its own.
• Subscription/payment provider (external actor) — owns payment instrument handling and recurring billing. It is not a persona and is not re-implemented first-party.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. The candidate-facing experience is first-party custom UI. The AI capabilities (question generation, gap diagnosis, mistake explanation) are first-party product behavior backed by an AI service; the candidate interacts with them through the product's own surfaces, never through a raw model interface.

Access ownership. The public entry surface is anonymous: a visitor can read what the product is, see the readiness instrument, and understand gap analysis before any identity exists. The candidate workspace — where a candidate's exam selection, drill history, per-domain readiness, and explanations accumulate — is durable, candidate-specific state that must remain bound to the correct candidate across sessions and devices. That continuity is indispensable to the accepted outcomes (a readiness percentage and a gap diagnosis are meaningless if they are not this candidate's), so application-owned identity is required: first-use identity establishment and returning verification, self-service. The anonymous entry surface cannot own the interaction that establishes access to the protected workspace; that interaction is an anonymous entry boundary, and protected state remains unavailable until identity is established.

Monetization boundary. The accepted models are a $20–$50/month subscription or a fixed test-pass pass. Payment instrument handling and recurring billing are provider-owned; the product surfaces plan selection and entitlement state but does not implement card handling.

Current vs. future boundary. Current: the exam-prep capability set above, for the Exam Candidate. Future candidates (not current scope, not current pages): the vertical document and contract analyzer; the hyper-niche diet and nutrition coach; the elderly care and family coordinator; the subscription and expense leakage tracker; the creator business and sponsorship dashboard; the hyperlocal home maintenance and diagnosis marketplace. The brief's execution guidance — pick one niche and one audience, prioritize mobile iOS first, and use native device features (camera, push notifications, offline syncing, location) rather than functioning as a wrapped website — is carried as a constraint on how the current product is built, not as a mandate to build the other concepts.

Explicit exclusions. No blue/indigo primary or accent anywhere, including focus rings and links. No white or near-white page ground. No Inter, Roboto, Arial, Helvetica, Poppins, Lato, Open Sans, or system-ui for headings or body. No gradient-blob heroes, floating glass cards, or grids of identical hover-lift feature cards. No cheerleading gamification: confetti, streak flames, cartoon mascots, or "You got this!" copy. No pill-shaped buttons or radii above 6px. No stock photography of smiling students or doctors. No purple-to-pink gradient washes. The generic indigo/blue-on-white SaaS template is forbidden for this project.

2c. Page Content and Component Coverage

Landing

Information and state. The anonymous entry surface. It explains what exam-prep is, which regulated exams it covers, and how gap analysis works, and it presents the readiness instrument as the product's central promise. It carries no candidate-specific state; the readiness gauge shown here is the illustrative instrument described in the creative direction, not a candidate's real score.

Primary actions.

• Start a 20-question diagnostic — the single amber squared button; the primary call to action.
• See how gap analysis works — a text link (the one underlined link on the screen).

Supporting actions.

• Exam selector — a segmented control in the sticky instrument bar with NCLEX / CPA / BAR / REALTOR; the active segment is filled amber. Selecting an exam changes the exam context the entry surface describes and carries that selection into the diagnostic start.
• Start drill — the squared button at the right of the sticky instrument bar; enters the same protected drill flow as the diagnostic CTA.

Domain entities. Exam (NCLEX, CPA, BAR, REALTOR); exam domain (e.g., Pharmacology, Med-Surg, Ethics); readiness percentage; days-to-exam countdown; plan (monthly subscription, fixed test-pass pass).

Component responsibilities.

• Instrument hero panel — full-bleed graphite panel, not a centred marketing stack. Left 7 columns: stacked Saira Condensed uppercase headline "PASS THE BOARD. NOT EVENTUALLY." at clamp(56px, 9vw, 128px), line one in #EDE9E3, line two indented 8% and set in amber #C8752E; beneath it one ~60-word paragraph in Barlow #8A857C; then the amber squared button and the text link. Right 5 columns: the 320px circular readiness gauge on a #1A1E22 panel that bleeds off the right viewport edge at desktop.
• Readiness gauge — concentric hairline bezel rings in #2C3238 (1px outer stroke plus 1px inner stroke so it reads as milled), tick marks every 5%, an amber needle at 68%, the number "68%" in 56px tabular Barlow Semi Condensed, and the label "NCLEX-RN READINESS" tracked 0.08em beneath. The needle sweeps 0→68% over 900ms with ease-out cubic while the tabular counter counts up in lockstep.
• Domain readiness complication list — twelve hairline-separated ruled rows, each with an uppercase tracked domain label, a 2px amber progress rule, and a right-aligned tabular percentage. No cards, no shadows.
• Sticky 56px instrument nav bar — wordmark left, exam selector segmented control, one squared "Start drill" button; reads as a device bezel, not a website header.
• Alternating feature sections — left column a macro material photograph bleeding off the right edge, right column a three-item ruled spec list.
• Pricing as a ruled comparison table — monthly subscription vs. fixed test-pass pass, with an amber underline on the recommended column; never three floating cards.
• Expedition divider — one full-bleed ridgeline-at-dawn photograph, desaturated to graphite with a single amber highlight, used once as a section divider.
• Product screenshot in a machined bezel frame — tilted 3° in CSS perspective, never floating in a gradient blob.

States.

• Loading: the gauge renders its bezel rings and tick marks immediately; the needle and counter animate from 0 to final value over 900ms.
• Empty: not applicable — the entry surface has no candidate data to be empty.
• Success: the visitor understands the product and either starts the diagnostic or selects an exam and starts a drill.
• Error/recovery: if the exam catalog cannot be loaded, the exam selector renders its four known segments disabled with a muted #8A857C label and the CTAs remain available against the default exam; the visitor can retry by reloading.
• Reduced motion: needle and counters render at final value instantly; reveals become static; the countdown still updates its number without any transition.

Readiness Dashboard

Information and state. The candidate's protected home surface. It shows the candidate's current overall readiness percentage, the per-domain readiness complication list for their selected exam, the days-to-exam countdown, and the entry point to drilling. It is the authoritative record of the candidate's diagnosed gaps.

Primary actions.

• Start drill — begins a practice question set in the current exam context.
• Set or change exam and exam date — selects the regulated exam and the exam date that drives the countdown.

Supporting actions.

• Open a domain row — inspects a single domain's readiness and its contributing missed questions.
• Review missed questions — opens the explanation readout for a previously missed question.

Domain entities. Candidate; exam; exam date; exam domain; domain readiness percentage; overall readiness percentage; practice question; answer attempt (correct/incorrect); missed-question record; explanation.

Component responsibilities.

• Readiness gauge — the same milled instrument as the entry surface, now bound to the candidate's real readiness value.
• Domain readiness complication list — twelve hairline-separated ruled rows with uppercase tracked labels, 2px amber progress rules, and right-aligned tabular percentages. A domain row flashes amber when a question from that domain is missed; a teal #3FA8A0 "mastered" check appears only when a domain crosses 85%.
• Countdown panel — days-to-exam at 56px tabular Barlow in amber on a #1A1E22 panel with a hairline rule above it; also persists at the right end of the sticky bar on scroll, ticking once per second with no easing theatrics.
• Exam selector — segmented control (NCLEX / CPA / BAR / REALTOR), active segment filled amber.
• Drill entry — the single squared amber button.

States.

• Loading: panels render as #1A1E22 surfaces with hairline dividers; the gauge needle and counters animate to final value.
• Empty (new candidate, no attempts yet): the gauge reads 0% with the needle at rest, the domain rows render at 0% with empty amber rules, and the surface presents "Start a 20-question diagnostic" as the single amber action. No fabricated readiness is shown.
• Success: readiness percentage and per-domain rows reflect the candidate's actual attempts; mastered domains show the teal check.
• Error/recovery: if readiness data fails to load, the surface shows the last known values with a muted #8A857C "stale" label and a retry control; the drill entry remains available.
• Reduced motion: needle and counters render at final value instantly; the countdown number still updates without transition.

Practice Drill

Information and state. The active question-answering surface. It presents one AI-generated realistic practice question at a time in the candidate's exam context, records the candidate's answer, and reveals the outcome. It shows question progress (e.g., question 7 of 20) in tabular figures.

Primary actions.

• Select an answer — commits the candidate's response to the current question.
• Submit answer — confirms the selection and reveals correctness.
• Next question — advances to the next generated question.

Supporting actions.

• Open explanation — on a wrong answer, opens the rationale readout for that question.
• Exit drill — leaves the drill; answered questions are retained.

Domain entities. Practice question (stem, options, correct answer, domain); answer attempt; correctness; domain attribution; drill session; progress count.

Component responsibilities.

• Question stem panel — Barlow 400/500 at 17px/1.6 for readable question stems at length.
• Answer options — squared, chamfered (6px max radius) controls with a 2px inset top highlight that reads as a machined edge; never pill-shaped.
• Progress readout — tabular numerals so counters never jitter.
• Answer-feedback readout — on a wrong answer the rationale panel opens with a 2px amber left rule; on a correct answer the confirmation uses teal #3FA8A0. Amber and teal never appear in the same component.
• Domain flash — a missed question flashes its row in the complication list.

States.

• Loading: the next question renders a #1A1E22 panel with a hairline rule and a muted #8A857C "generating question" label; the progress readout holds its last value.
• Empty: not applicable — a drill always begins with a generated question.
• Success: the answer is recorded, correctness is shown, and the domain attribution updates readiness.
• Error/recovery: if question generation fails, the surface shows a muted error panel with a retry control and preserves the candidate's drill position; the candidate can exit and resume.
• Reduced motion: reveals become static; no bounce, no particles, no gradient drift.

Gap Analysis

Information and state. The candidate's diagnosed knowledge gaps, expressed as the full per-domain breakdown for the selected exam: each domain's readiness percentage, the volume of missed questions attributed to it, and which domains are mastered (≥85%, teal check) versus weak (amber). This is the surface where "diagnoses exact knowledge gaps" becomes an inspectable record rather than a single number.

Primary actions.

• Drill this domain — starts a practice set scoped to a weak domain.
• Review missed questions in a domain — opens the missed-question list for that domain.

Supporting actions.

• Sort/filter domains — by readiness ascending or by missed-question volume.
• Return to dashboard — back to the readiness overview.

Domain entities. Exam domain; domain readiness percentage; missed-question record; mastery threshold (85%); weak-domain designation.

Component responsibilities.

• Ruled domain table — hairline-separated rows with uppercase tracked domain labels, 2px amber progress rules, and right-aligned tabular percentages; the same complication-list language as the dashboard, at full detail.
• Mastery indicator — teal #3FA8A0 check at ≥85%; amber otherwise.
• Missed-question list — per-domain list of missed questions with their stems and the date attempted.

States.

• Loading: ruled rows render with muted labels and empty rules.
• Empty (no attempts): every domain reads 0% with no missed questions; the surface presents the diagnostic as the single amber action.
• Success: domains are ranked by weakness and each offers a scoped drill.
• Error/recovery: if diagnosis data fails to load, the surface shows a muted error with retry and preserves the last known breakdown.
• Reduced motion: static ruled rows; hover rule slide is suppressed.

Explanation

Information and state. The on-demand explanation of a specific mistake. It shows the question as it was presented, the candidate's selected answer, the correct answer, and the AI-produced rationale for why the correct answer is correct and why the candidate's choice was wrong. It names the domain the question belongs to.

Primary actions.

• Read the rationale — the core content.
• Drill this domain — start a scoped practice set from the explanation.

Supporting actions.

• Next missed question — move to the next explanation in the missed-question list.
• Return to gap analysis — back to the domain breakdown.

Domain entities. Practice question; candidate's selected answer; correct answer; rationale; domain attribution.

Component responsibilities.

• Rationale panel — opens with a 2px amber left rule; Barlow body at 17px/1.6 for readable rationales at length.
• Answer comparison — the candidate's answer and the correct answer shown side by side in ruled rows, correct answer confirmed in teal #3FA8A0.
• Domain attribution row — the domain label with its current readiness percentage in tabular figures.

States.

• Loading: the rationale panel renders its amber left rule and a muted "generating explanation" label.
• Empty: not applicable — an explanation is always opened from a specific missed question.
• Success: the candidate can articulate why they missed the question and can start a scoped drill.
• Error/recovery: if explanation generation fails, the panel shows a muted error with a retry control and keeps the question, the candidate's answer, and the correct answer visible so the mistake is still reviewable.
• Reduced motion: static panel; no reveal animation.

Account Access

Information and state. The anonymous entry boundary that establishes and verifies the candidate's application-owned identity so that exam selection, drill history, per-domain readiness, and explanations remain bound to the correct candidate across sessions and devices. It is reachable without identity; the protected workspace is not.

Primary actions.

• Create identity (first use) — self-service establishment of the candidate's identity.
• Verify identity (returning) — returning verification to resume the candidate's own state.

Supporting actions.

• Return to Landing — back to the public entry surface.

Domain entities. Candidate identity; session.

Component responsibilities.

• Identity form — squared, chamfered inputs and a single amber squared submit button; no pill shapes.
• Mode switch — between first-use establishment and returning verification.
• Error readout — muted #8A857C messaging with a 2px amber left rule on failure.

States.

• Loading: the submit control shows a muted in-progress state; inputs remain readable.
• Empty: not applicable.
• Success: the candidate lands in the Readiness Dashboard with their own state intact.
• Error/recovery: invalid or unrecognized credentials show a muted error with the amber left rule and preserve the entered values so the candidate can correct and retry.
• Reduced motion: static form; no transition on state change.

Plan & Billing

Information and state. The candidate's plan and entitlement state: the $20–$50/month subscription or the fixed test-pass pass, which plan is active, and when it renews or expires. Payment instrument handling and recurring billing are provider-owned; this surface presents plan selection and entitlement state and hands payment to the provider.

Primary actions.

• Choose a plan — select the monthly subscription or the fixed test-pass pass.
• Manage plan — change or cancel the current plan.

Supporting actions.

• View entitlement — see what the current plan entitles the candidate to.
• Return to dashboard — back to the readiness overview.

Domain entities. Plan (monthly subscription, fixed test-pass pass); price ($20–$50/month range); entitlement; renewal/expiry date; provider payment reference.

Component responsibilities.

• Ruled plan comparison table — the two plans as ruled rows with an amber underline on the recommended column; never three floating cards.
• Entitlement readout — active plan and renewal/expiry in tabular figures.
• Provider handoff — a squared amber control that transfers payment to the provider surface.

States.

• Loading: plan rows render with muted prices; the entitlement readout holds its last value.
• Empty (no plan): the comparison table renders with the amber underline on the recommended plan and a single amber action to choose.
• Success: the active plan and its entitlement are shown with the renewal or expiry date.
• Error/recovery: if the provider handoff fails or the entitlement cannot be confirmed, the surface shows a muted error with retry and does not grant or revoke entitlement on an unconfirmed result.
• Reduced motion: static table; no transition.

3. Functional Requirements

Each requirement is a distinct story point with provenance, lifecycle facts, and observable acceptance. Provenance is explicit (stated in the authoritative requirement thread), basic_default (accepted default), or required_inference (indispensable inferred mechanics).

FR-1 — Exam selection. As an Exam Candidate, I should select which regulated exam I am preparing for — NCLEX nursing boards, CPA, real estate license, or bar exam — so that every question, diagnosis, and explanation is scoped to my exam.

• Provenance: explicit (the source names NCLEX nursing boards, CPA, real estate licenses, and bar exams as the target exams).
• Trigger/input: the candidate selects a segment in the exam selector (NCLEX / CPA / BAR / REALTOR).
• Observable result: the active segment is filled amber and the exam context changes across the readiness gauge label, the domain complication list, and subsequent question generation.
• Access state: the selector is usable anonymously on Landing and is bound to the candidate's own state on the protected surfaces.
• Failure/recovery: if the exam catalog cannot be loaded, the four known segments render disabled in muted #8A857C and the candidate can retry by reloading.
• Continuation: the selected exam persists into the drill, gap analysis, and explanation surfaces.

FR-2 — AI-generated realistic practice questions. As an Exam Candidate, I should be given realistic practice questions generated by AI in my selected exam's context so that my practice resembles the real exam rather than generic quiz content.

• Provenance: explicit ("AI generates realistic practice questions").
• Trigger/input: the candidate starts a drill or a 20-question diagnostic.
• Observable result: a question stem with answer options is presented, with progress shown in tabular figures (e.g., question 7 of 20).
• Access state: requires the candidate's protected workspace; the diagnostic is initiated from the anonymous entry surface and continues under the candidate's identity.
• Failure/recovery: if generation fails, a muted error panel with a retry control appears and the candidate's drill position is preserved.
• Continuation: the candidate answers and advances to the next generated question.

FR-3 — Answer commitment and correctness feedback. As an Exam Candidate, I should commit an answer to each question and immediately learn whether it was correct so that I know where I stand on that item.

• Provenance: explicit (implied by "explains mistakes on demand" — a mistake must be identified).
• Trigger/input: the candidate selects an option and submits.
• Observable result: correctness is shown; a correct answer is confirmed in teal #3FA8A0, a wrong answer opens the rationale panel with a 2px amber left rule. Amber and teal never appear in the same component.
• Access state: protected workspace.
• Failure/recovery: if the answer cannot be recorded, the surface shows a muted error with retry and does not advance until the attempt is recorded.
• Continuation: the candidate opens the explanation or advances to the next question.

FR-4 — Exact knowledge-gap diagnosis. As an Exam Candidate, I should have my exact knowledge gaps diagnosed across my exam's domains so that I know precisely which domains are weak rather than receiving a vague overall impression.

• Provenance: explicit ("diagnoses exact knowledge gaps").
• Trigger/input: the candidate's recorded answer attempts.
• Observable result: a per-domain readiness percentage for each exam domain, with weak domains in amber and mastered domains (≥85%) marked with a teal #3FA8A0 check; the overall readiness percentage is shown on the milled gauge.
• Access state: protected workspace; the diagnosis is the candidate's own.
• Failure/recovery: if diagnosis data fails to load, the last known breakdown is shown with a muted "stale" label and a retry control.
• Continuation: the candidate drills a weak domain or reviews missed questions in it.

FR-5 — On-demand explanation of mistakes. As an Exam Candidate, I should be able to open an explanation of any mistake I made, on demand, so that I understand why my answer was wrong and why the correct answer is correct.

• Provenance: explicit ("explains mistakes on demand").
• Trigger/input: the candidate opens the explanation from a wrong answer or from a missed question in a domain.
• Observable result: a rationale panel opens with a 2px amber left rule, showing the question, the candidate's selected answer, the correct answer, and the AI-produced rationale, with the domain named.
• Access state: protected workspace.
• Failure/recovery: if explanation generation fails, the panel shows a muted error with retry and keeps the question, the candidate's answer, and the correct answer visible so the mistake is still reviewable.
• Continuation: the candidate moves to the next missed question or starts a drill scoped to that domain.

FR-6 — Readiness instrument. As an Exam Candidate, I should see my readiness as a live instrument — an overall percentage on a milled gauge, a per-domain complication list, and a days-to-exam countdown — so that I can read my position precisely at a glance.

• Provenance: explicit (the creative direction's signature moves; the readiness percentage, weak-domain needles, and countdown are the accepted instrument).
• Trigger/input: the candidate opens the readiness dashboard or the entry surface.
• Observable result: the needle sweeps from 0 to the real value over 900ms with ease-out cubic while the tabular counter counts up in lockstep; the domain rows show 2px amber progress rules and right-aligned tabular percentages; the countdown ticks once per second.
• Access state: the entry surface shows the illustrative instrument anonymously; the dashboard shows the candidate's real values under identity.
• Failure/recovery: if readiness data fails to load, last known values are shown with a muted "stale" label and retry.
• Continuation: the candidate starts a drill from the instrument.

FR-7 — Exam date and countdown. As an Exam Candidate, I should set my exam date and see a persistent days-to-exam countdown so that the pressure of the real deadline is always visible.

• Provenance: explicit (the creative direction's countdown numerals as ornament, sitting in the sticky bar's right end on scroll).
• Trigger/input: the candidate sets or changes the exam date.
• Observable result: days-to-exam renders at 56px tabular Barlow in amber on a #1A1E22 panel with a hairline rule above it, and persists at the right end of the sticky bar on scroll.
• Access state: protected workspace.
• Failure/recovery: if the date cannot be saved, the previous date is retained and a muted error is shown with retry.
• Continuation: the countdown continues to tick as the candidate drills.

FR-8 — Domain-scoped drilling. As an Exam Candidate, I should be able to start a practice set scoped to a specific weak domain so that I can attack the gap the diagnosis identified.

• Provenance: required_inference (causally necessary for the accepted outcome that a diagnosed gap leads to improvement; it introduces no separately invoked user goal beyond drilling, which is already accepted).
• Trigger/input: the candidate selects "Drill this domain" from a domain row in gap analysis or from an explanation.
• Observable result: a drill begins whose questions are attributed to that domain, and subsequent attempts move that domain's readiness.
• Access state: protected workspace.
• Failure/recovery: if generation fails, the muted error panel with retry appears and the candidate returns to gap analysis.
• Continuation: the candidate's updated domain readiness is visible on the dashboard.

FR-9 — Candidate identity and state continuity. As an Exam Candidate, I should establish my identity on first use and verify it on return so that my exam selection, drill history, per-domain readiness, and explanations remain mine across sessions and devices.

• Provenance: required_inference (indispensable: a readiness percentage and a gap diagnosis are only meaningful as this candidate's durable state, and the accepted outcomes require resuming them).
• Trigger/input: first use — self-service identity establishment; return — verification.
• Observable result: on success the candidate lands in their own Readiness Dashboard with prior state intact.
• Access state: the entry interaction is anonymous; the protected workspace is unavailable until identity is established.
• Failure/recovery: invalid or unrecognized credentials show a muted error with a 2px amber left rule and preserve entered values for correction and retry.
• Continuation: the candidate resumes drilling and review where they left off.

FR-10 — Plan selection and entitlement. As an Exam Candidate, I should choose between a $20–$50/month subscription and a fixed test-pass pass, and see my entitlement state, so that I know what I have paid for and what it covers.

• Provenance: explicit ("Monetization: $20–$50/month subscription or fixed test-pass pass").
• Trigger/input: the candidate selects a plan or manages the current one.
• Observable result: the active plan and its renewal or expiry date are shown in tabular figures; the recommended column carries an amber underline.
• Access state: protected workspace; payment instrument handling is handed to the provider.
• Failure/recovery: if the provider handoff fails or entitlement cannot be confirmed, a muted error with retry is shown and entitlement is not granted or revoked on an unconfirmed result.
• Continuation: the candidate returns to drilling with entitlement applied.

FR-11 — Native device capability use. As an Exam Candidate, I should be able to use the app's native device capabilities — push notifications for study and exam-date reminders, and offline syncing of drill progress — so that the product works as a real mobile app rather than a wrapped website.

• Provenance: explicit (the brief's execution guidance: "Focus on Native Device Features: Ensure the app utilizes core mobile capabilities (camera, push notifications, offline syncing, or location) rather than functioning as a wrapped website").
• Trigger/input: the candidate grants notification permission and/or answers questions while offline.
• Observable result: reminders are delivered as push notifications; attempts made offline are synced and reflected in readiness once connectivity returns.
• Access state: protected workspace.
• Failure/recovery: if sync fails, attempts are retained locally and retried; the candidate sees a muted "pending sync" label rather than losing the attempt.
• Continuation: readiness updates once sync completes.

4. User Personas

Exam Candidate

Product context. A working adult preparing for a high-stakes, regulated licensing exam — NCLEX nursing boards, CPA, real estate license, or bar exam. They are studying around a job: night shifts, after-hours sessions, stolen hours. They have committed real money ($20–$50/month or a fixed test-pass pass) and months of their life to a single pass/fail outcome, and many of them cannot afford to fail twice. They are not looking for a fun learning app; they are looking for an instrument that tells them the truth about whether they are ready.

Primary goal. To pass their licensing exam on the next attempt, by knowing exactly which domains they are weak in and closing those gaps before the exam date.

Distinct accepted responsibilities.

• Selecting the regulated exam they are preparing for (NCLEX / CPA / BAR / REALTOR) and setting their exam date.
• Working through AI-generated realistic practice questions in that exam's context.
• Committing answers and reading the correctness feedback.
• Reading their exact knowledge-gap diagnosis across exam domains and identifying which domains are weak versus mastered.
• Opening on-demand explanations of the specific mistakes they made.
• Drilling the weak domains the diagnosis surfaced.
• Choosing and managing their plan — monthly subscription or fixed test-pass pass.
• Establishing and verifying their identity so their readiness and history remain theirs.

Relevant inputs and decisions. Which exam and which exam date; which answer to commit on each question; whether to open an explanation or move on; which weak domain to drill next; which plan to buy. Their decisions are driven by the instrument's numbers, not by encouragement.

Interactions with other accepted participants. The Exam Candidate is the only accepted active human persona in the current product. They interact with the AI question-and-diagnosis service (a system actor that generates questions, produces the gap diagnosis, and produces mistake explanations) and, for payment, with the subscription/payment provider (an external actor that owns payment instrument handling and recurring billing). Neither is a persona, and neither has a page of its own.

Observable success. The candidate's overall readiness percentage rises, weak domains cross the 85% mastery threshold and show the teal check, the days-to-exam countdown stays visible, and they enter the exam knowing their exact position rather than a vague sense of preparedness.

What makes this role's work different. The candidate's work is diagnostic and adversarial rather than exploratory: every session is measured against a pass/fail outcome and a fixed date, and the product's value is the precision of the gap it exposes. This is why the interface is an instrument — a cockpit, not a classroom — and why the product never cheers, never gamifies, and never softens a number.

5. Core User Flows

Flow 1 — First visit, diagnostic, and first diagnosis (Exam Candidate)

1. Starting context: the candidate is anonymous, has heard about exam-prep, and has not established identity. They arrive at Landing.
2. On Landing, they read the instrument hero: the headline "PASS THE BOARD. NOT EVENTUALLY.", the ~60-word paragraph, and the readiness gauge with its milled bezel rings, 5% tick marks, and amber needle sweeping 0→68% while the tabular counter counts up in lockstep.
3. They select their exam in the segmented control (NCLEX / CPA / BAR / REALTOR); the active segment fills amber and the gauge label and domain complication list change to that exam's context.
4. They read the twelve-row domain readiness complication list — uppercase tracked labels, 2px amber progress rules, right-aligned tabular percentages — and understand that the product breaks the whole exam down like a watch's complications.
5. They click Start a 20-question diagnostic (the single amber squared button).
6. Access boundary: because the diagnostic produces durable candidate-specific state, they are taken to Account Access and establish identity on first use, self-service. Protected state remains unavailable until this succeeds. If their credentials are rejected, a muted error with a 2px amber left rule appears and their entered values are preserved so they can correct and retry.
7. On success they land in Readiness Dashboard, which is empty for a new candidate: the gauge reads 0% with the needle at rest, the domain rows render at 0% with empty amber rules, and the single amber action is the diagnostic. No fabricated readiness is shown.
8. They begin the diagnostic in Practice Drill. The first AI-generated realistic question appears with its stem in Barlow at 17px/1.6 and its squared, chamfered answer options; progress reads in tabular figures.

9. For each question they select an option and submit. A correct answer is confirmed in teal #3FA8A0; a wrong answer opens the rationale panel with a 2px amber left rule and flashes that question's domain row in the complication list.
10. Observable result: when the diagnostic completes, the candidate's readiness percentage and per-domain breakdown reflect their actual attempts, and weak domains are visible in amber.
11. Continuation: they open Gap Analysis to see the full ranked breakdown, or return to the dashboard and start a drill.

Flow 2 — Understanding a mistake on demand (Exam Candidate)

1. Starting context: the candidate is in Practice Drill and has just answered a question incorrectly, or is in Gap Analysis reviewing a weak domain's missed questions.
2. They open the explanation for that specific mistake.
3. Explanation opens with a 2px amber left rule, showing the question as it was presented, their selected answer, the correct answer, and the AI-produced rationale for why the correct answer is correct and why their choice was wrong. The domain is named with its current readiness percentage in tabular figures.
4. If explanation generation fails, the panel shows a muted error with a retry control and keeps the question, their answer, and the correct answer visible so the mistake is still reviewable.
5. Observable result: the candidate can articulate why they missed the question.
6. Continuation: they click Drill this domain to start a practice set scoped to that domain, or move to the next missed question.

Flow 3 — Attacking a diagnosed gap (Exam Candidate)

1. Starting context: the candidate is in Gap Analysis, looking at the ranked domain table with weak domains in amber and mastered domains (≥85%) marked with a teal check.
2. They sort or filter by readiness ascending to find their weakest domain, and open it to see the missed questions attributed to it.
3. They click Drill this domain.
4. Practice Drill begins with questions attributed to that domain. They answer, receive correctness feedback, and open explanations for mistakes as needed.
5. Observable result: that domain's readiness percentage moves, and when it crosses 85% the teal "mastered" check appears on its row.
6. Continuation: they return to Readiness Dashboard, where the overall gauge and the complication list reflect the change, and pick the next weak domain.

Flow 4 — Reading readiness against the exam date (Exam Candidate)

1. Starting context: the candidate has set their exam date and is returning to the product after some time away.
2. They verify their identity at Account Access and land in Readiness Dashboard with their prior state intact.
3. They read the milled readiness gauge — the needle sweeping to their real value over 900ms while the tabular counter counts up in lockstep — and the twelve-row domain complication list.
4. They read the countdown panel: days-to-exam at 56px tabular Barlow in amber on a #1A1E22 panel with a hairline rule above it. As they scroll, the countdown persists at the right end of the sticky 56px instrument bar, ticking once per second.
5. If readiness data fails to load, the surface shows their last known values with a muted "stale" label and a retry control, and the drill entry remains available.
6. Observable result: the candidate knows their exact position — overall readiness, per-domain gaps, and days remaining — in one read.
7. Continuation: they click Start drill to begin a session in the current exam context.

Flow 5 — Choosing a plan (Exam Candidate)

1. Starting context: the candidate has been drilling and wants to commit to a plan, or wants to change the one they have.
2. They open Plan & Billing.
3. They read the ruled plan comparison table — the $20–$50/month subscription and the fixed test-pass pass as ruled rows, with an amber underline on the recommended column, never three floating cards.
4. They choose a plan. Payment instrument handling and recurring billing are handed to the subscription/payment provider; the product does not handle card details.
5. If the provider handoff fails or entitlement cannot be confirmed, a muted error with retry is shown, and entitlement is not granted or revoked on an unconfirmed result.
6. Observable result: the active plan and its renewal or expiry date are shown in tabular figures, and the candidate's entitlement is applied.
7. Continuation: they return to Readiness Dashboard and continue drilling.

Flow 6 — Studying offline and syncing (Exam Candidate)

1. Starting context: the candidate is on a night shift or commuting with no connectivity, and opens the app to drill.
2. They work through practice questions in Practice Drill. Attempts are retained locally, and the surface shows a muted "pending sync" label rather than losing the attempt.
3. Observable result: when connectivity returns, the retained attempts sync and the candidate's readiness percentage and per-domain breakdown update to include them.
4. If sync fails, the attempts remain retained locally and are retried; nothing is discarded.
5. Continuation: the candidate returns to Readiness Dashboard to read the updated instrument, and may receive a push notification reminding them of their study session or approaching exam date.

6. Visuals Colors and Theme

Muse and headline. MARQ by Garmin — luxury instrument aesthetic. The register is precision under pressure, worn on the body: titanium, sapphire, dial instrumentation, expedition endurance. A candidate tracking readiness percentage, weak-domain needles, and a countdown is the same gesture as a tool watch tracking altitude and heart rate. The headline for this product is "PASS THE BOARD. NOT EVENTUALLY."

Mode. Dark mode only.

Colour tokens by role.

Colour rules. Amber and teal never appear in the same component; they are the two needles of the instrument. Proportion: 80% dark ground, 14% surface panels, 5% amber, 1% teal. No blue/indigo primary or accent anywhere — no #2563EB, #4F46E5, #7C3AED or neighbours, including focus rings and links. No white or near-white page ground. No purple-to-pink gradient washes.

Typography.

• Headings: Saira Condensed 600–700, uppercase for section heads and gauge labels with 0.06em tracking. Display headlines set in Saira Condensed 700 at very large sizes with tight 0.95 leading so a single word can span the viewport.
• Numerals: Barlow Semi Condensed 600 with tabular figures for all numerals — readiness %, days-to-exam, question counts, scores — so counters never jitter.
• Body: Barlow 400/500 at 17px/1.6 — humanist, engineered, readable at length for question stems and rationales.
• Scale: 1.25 modular on a 4/8pt base. Display 56px mobile / 96px tablet / 128px desktop (clamp(56px, 9vw, 128px)); h1 40/56/72; h2 28/34/40; h3 20/22/24; body 17/18/18; label 12px uppercase tracked 0.08em; data numeral 32/44/56 tabular.
• Forbidden: Inter, Roboto, Arial, Helvetica, Poppins, Lato, Open Sans, or system-ui for headings or body.

Shape language. Instrument geometry: circular gauges and bezel rings as the primary motif, ruled data rows with hairline dividers, chamfered corners (6px radius max, never pill), squared-off buttons with a 2px inset top highlight that reads as a machined edge. Bezel rings get a 1px outer stroke plus a 1px inner stroke in #2C3238 so they look milled, not flat. Needle sweeps and tick marks are drawn as real SVG, not decoration.

Spacing rhythm. Strict 12-column grid with a 24px gutter (16px at 375px). Edge-to-edge dark panels. Sticky top nav is a thin 56px instrument bar.

Imagery style. Macro photography only: brushed titanium and sapphire glass surfaces, a knurled bezel edge, a topographic contour line, a leather strap grain — all on flat dark grounds, lit from one side like a product studio. No stock people, no clip art, no illustrated characters. One expedition-adjacent photograph (a ridgeline at dawn, desaturated to graphite with a single amber highlight) may be used full-bleed once as a section divider. Product screenshots are shown inside a machined bezel frame, tilted 3° in CSS perspective, never floating in a gradient blob.

Layout. Hero is a full-bleed instrument panel, not a centred marketing stack. Below it, a "domain readiness" band of ruled rows — each exam domain as a horizontal row with a label, a thin amber bar, and a tabular percentage, like a watch's complication list. Feature sections alternate: left column a macro material photograph bleeding off the right edge, right column a three-item ruled spec list. Pricing is a ruled comparison table with an amber underline on the recommended column, never three floating cards.

Readable text and controls. Headlines, wordmarks, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Imagery, decoration, and motion may be cropped, bled off an edge, rotated, overlapped, or cut exactly as the direction asks, as long as they cover no readable text or control. Where the direction asks readable text or a control to be cropped, clipped, covered, or run off an edge, keep it whole and carry the gesture with imagery or decoration instead.

7. Signature Design Concept

The readiness gauge as the hero's dominant element — the number is the product promise, not a screenshot.

The public entry is a full-bleed graphite instrument panel, not a centred SaaS stack. On the left 7 columns: a stacked Saira Condensed uppercase headline — "PASS THE BOARD" on line one in #EDE9E3, "NOT EVENTUALLY" on line two indented 8% and set in amber #C8752E — at clamp(56px, 9vw, 128px) with 0.95 leading. Beneath it, one ~60-word paragraph in Barlow #8A857C, then a single squared amber button "Start a 20-question diagnostic" and one underlined text link "See how gap analysis works".

On the right 5 columns sits a 320px circular readiness gauge on a #1A1E22 panel that bleeds off the right viewport edge at desktop. The gauge is built from concentric hairline bezel rings in #2C3238 — a 1px outer stroke plus a 1px inner stroke so it reads as milled rather than flat — with tick marks every 5% drawn as real SVG. An amber needle rests at 68%; the number "68%" is set in 56px tabular Barlow Semi Condensed so it never jitters; the label "NCLEX-RN READINESS" is tracked 0.08em beneath it.

On load, the needle sweeps from 0 to 68% over 900ms with an ease-out cubic while the tabular counter counts up in lockstep. This is the whole concept in one gesture: the product's promise is a precise number about your readiness, delivered by an instrument, not a marketing claim.

Below the hero, the "domain readiness" band carries the same language at full width: twelve hairline-separated ruled rows, each with an uppercase tracked domain label, a 2px amber progress rule, and a right-aligned tabular percentage — the whole exam broken down like a watch's complications, no cards, no shadows. The sticky 56px instrument nav bar above it reads as a device bezel: wordmark left, exam selector as a segmented control (NCLEX / CPA / BAR / REALTOR) with the active segment filled amber, and one squared "Start drill" button.

At 375px the gauge stacks below the headline, shrinks to 220px, and the headline wraps to four lines, all fully inside the viewport.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: cinematic Hero Dimensionality: dimensional_css

Landing Hero Motion Brief.

• Focal subject: the 320px circular readiness gauge — concentric milled bezel rings, 5% tick marks, an amber needle, and a tabular counter — sitting on a #1A1E22 panel that bleeds off the right viewport edge.
• Input → transformation → outcome thesis: on load, the needle sweeps from 0 to the real value (68% on the entry surface) over 900ms with an ease-out cubic, and the tabular counter counts up in lockstep; the outcome is that the visitor reads a precise readiness number as the product's promise before reading a single word of copy.
• Motion vocabulary: precise, never playful. Panel reveals slide up 16px with a 240ms ease. Hover on a domain row slides a 2px amber rule in from the left. The exam countdown ticks once per second with no easing theatrics. No bounce, no particles, no gradient drift.
• Composed first frame: the graphite ground #0E1113 with the hero panel in place, the headline fully set, the gauge bezel rings and tick marks already drawn, the needle at rest at 0%, and the counter reading 0% — a composed instrument at rest, not a blank or a spinner.
• Reduced-motion state: the needle and counters render at their final value instantly, reveals become static, and the countdown still updates its number without any transition. The composed first frame is the final frame.

Landing Hero 3D Scene Brief — DIRECTION-DERIVED. The direction's hero dimensionality is dimensional_css, so the hero is a crafted layered CSS object rather than a WebGL scene: the gauge is composed of real stacked layers — the #1A1E22 panel, the outer bezel ring stroke, the inner bezel ring stroke, the SVG tick-mark layer, the SVG needle layer, and the tabular numeral layer — each with its own depth and its own animation timing, so the needle sweep reads as a physical instrument moving inside a milled case rather than a flat stat card. No Canvas, R3F, or Drei is required.

9. Non-Functional Requirements

NFR-1 — Mobile-first, iOS-first delivery. The product is delivered mobile-first, prioritizing iOS, per the brief's execution guidance ("Prioritize Mobile iOS First: Apple's App Store consistently generates significantly higher revenue per user than Google Play for non-gaming consumer apps"). Provenance: explicit. Rationale: the accepted audience and monetization model depend on iOS-first distribution.

NFR-2 — Native device capabilities, not a wrapped website. The product must use core mobile capabilities — push notifications for study and exam-date reminders, and offline syncing of drill progress — rather than functioning as a wrapped website. Provenance: explicit ("Focus on Native Device Features: Ensure the app utilizes core mobile capabilities (camera, push notifications, offline syncing, or location) rather than functioning as a wrapped website"). Rationale: the accepted offline and reminder behavior (FR-11) is only achievable with native capability.

NFR-3 — Durable candidate state. Candidate identity, exam selection, exam date, drill history, answer attempts, per-domain readiness, and explanations must persist durably and remain bound to the correct candidate across sessions and devices. Provenance: required_inference. Rationale: a readiness percentage and a gap diagnosis are only meaningful as the candidate's own durable state; without continuity the accepted outcomes are unachievable.

NFR-4 — AI service dependency. Question generation, gap diagnosis, and mistake explanation depend on an AI service. Provenance: explicit ("AI generates realistic practice questions, diagnoses exact knowledge gaps, and explains mistakes on demand"). Rationale: these are the product's defining capabilities; the AI service is a system actor, not a persona, and has no page of its own.

NFR-5 — Provider-owned payment. Payment instrument handling and recurring billing are owned by the subscription/payment provider; the product surfaces plan selection and entitlement state and does not handle card details. Provenance: required_inference (the accepted monetization models require a payment owner, and the product's own surfaces do not accept card data). Rationale: keeps payment handling with its accepted owner and out of first-party scope.

NFR-6 — Accessibility and reduced motion. With prefers-reduced-motion, the needle and counters render at their final value instantly, reveals become static, and the countdown still updates its number without any transition. Readable text and controls stay whole at 375px, 768px, and 1280px. Provenance: explicit (creative direction). Rationale: the instrument must remain readable and usable without motion.

NFR-7 — Performance of the instrument. The readiness needle sweep completes in 900ms with ease-out cubic, panel reveals in 240ms, and the countdown ticks once per second; numerals use tabular figures so counters never jitter. Provenance: explicit (creative direction). Rationale: the instrument's credibility depends on precise, non-jittering motion.

NFR-8 — Monetization range. The accepted price points are $20–$50/month for the subscription and a fixed test-pass pass. Provenance: explicit. Rationale: the accepted monetization model for this product.

10. Tech Stack

• Frontend: React (mobile-first web application shell), styled to the creative direction's dark instrument system. [Default — not specified by user]
• Backend: Python / FastAPI, serving the exam catalog, drill sessions, answer attempts, readiness computation, gap diagnosis, explanation retrieval, and entitlement state. [Default — not specified by user]
• AI service: an AI service for question generation, gap diagnosis, and mistake explanation, called from the backend. Provenance: explicit (AI capability required); the specific provider is [Default — not specified by user].
• Storage: a durable datastore for candidate identity, exam selection, exam date, drill sessions, answer attempts, per-domain readiness, missed-question records, and explanations. [Default — not specified by user]
• Payments: a subscription/payment provider for plan purchase, recurring billing, and entitlement confirmation. Provenance: required_inference (provider-owned payment).
• Native capabilities: push notifications and offline sync, delivered through the mobile shell. Provenance: explicit (native device features guidance).
• Packaging and deployment: Docker / docker-compose for the backend and its datastore. Kubernetes is not required by any accepted requirement and is not included. [Default — not specified by user]

11. Assumptions and Constraints

Assumptions.

• A-1. The current product is exam-prep only. The other concepts in the market-opportunity brief (document and contract analyzer, hyper-niche diet and nutrition coach, elderly care and family coordinator, subscription and expense leakage tracker, creator business and sponsorship dashboard, hyperlocal home maintenance and diagnosis) are future candidates and are not implemented in the current product. Provenance: explicit (the brief is a market-opportunity brief listing candidate concepts; the user selected the exam-prep concept and named the project).
• A-2. The Exam Candidate is the only accepted active human persona for the current product. The AI question-and-diagnosis service and the subscription/payment provider are non-persona actors. Provenance: required_inference.
• A-3. The four exam contexts named in the source — NCLEX nursing boards, CPA, real estate licenses, and bar exams — are the current exam catalog. Provenance: explicit.
• A-4. The readiness gauge's 68% and the twelve domain rows shown on the entry surface are the illustrative instrument described in the creative direction, not a candidate's real data. Provenance: explicit (creative direction).
• A-5. The mastery threshold is 85%, at which a domain shows the teal "mastered" check. Provenance: explicit (creative direction).
• A-6. The 20-question diagnostic is the accepted entry drill size. Provenance: explicit (creative direction).

Constraints.

• C-1. No product, niche, or audience beyond exam-prep has been selected; the source explicitly advises picking one niche and one audience rather than building a broad multi-purpose app. The current product therefore owns one niche (high-stakes regulated exam prep) and one audience (the Exam Candidate). Provenance: explicit.
• C-2. The source is a market-opportunity brief, not a committed product specification; all listed concepts other than exam-prep are candidates and remain out of current scope. Provenance: explicit.
• C-3. Execution guidance is binding on how the current product is built: prioritize mobile iOS first, and use native device features (camera, push notifications, offline syncing, location) rather than functioning as a wrapped website. Provenance: explicit.
• C-4. The generic indigo/blue-on-white SaaS template is forbidden for this project. No blue/indigo primary or accent anywhere, including focus rings and links; no white or near-white page ground; no Inter, Roboto, Arial, Helvetica, Poppins, Lato, Open Sans, or system-ui for headings or body; no gradient-blob heroes, floating glass cards, or grids of identical hover-lift feature cards; no cheerleading gamification (confetti, streak flames, cartoon mascots, "You got this!" copy); no pill-shaped buttons or radii above 6px; no stock photography of smiling students or doctors; no purple-to-pink gradient washes. Provenance: explicit (creative direction).
• C-5. Amber #C8752E is used only for live/urgent signals — countdown numbers, the readiness needle, the active exam-mode button, one underlined link per screen. Teal #3FA8A0 is used only for "mastered" states and correct-answer confirmation. Amber and teal never appear in the same component. Provenance: explicit (creative direction).
• C-6. Payment instrument handling and recurring billing remain with the subscription/payment provider; the product does not handle card details. Provenance: required_inference.

12. Glossary

• Exam Candidate — the sole accepted active human persona: a working adult preparing for a high-stakes, regulated licensing exam.
• Regulated exam — one of the high-stakes licensing exams the product covers: NCLEX nursing boards, CPA, real estate license, or bar exam.
• Exam domain — a subject area within a regulated exam (e.g., Pharmacology, Med-Surg, Ethics) against which readiness is measured.
• Readiness percentage — the candidate's measured preparedness, shown overall on the milled gauge and per domain in the complication list.
• Complication list — the ruled, hairline-separated band of domain rows, each with an uppercase tracked label, a 2px amber progress rule, and a right-aligned tabular percentage.
• Mastery threshold — 85%; a domain at or above it shows the teal #3FA8A0 "mastered" check.
• Diagnostic — the 20-question entry drill that establishes a candidate's initial readiness and gap diagnosis.
• Drill — a practice question set, either in the current exam context or scoped to a specific weak domain.
• Gap analysis — the full per-domain breakdown of the candidate's diagnosed knowledge gaps, ranked by weakness.
• Explanation — the on-demand AI-produced rationale for a specific mistake, showing the question, the candidate's answer, the correct answer, and why.
• Countdown — the days-to-exam readout at 56px tabular Barlow in amber, persistent at the right end of the sticky instrument bar on scroll.
• Instrument bar — the sticky 56px nav bar: wordmark left, exam selector segmented control, one squared "Start drill" button.
• Test-pass pass — the fixed-price monetization option alongside the $20–$50/month subscription.

• AI question-and-diagnosis service — the non-persona system actor that generates practice questions, produces gap diagnosis, and produces mistake explanations.
• Subscription/payment provider — the non-persona external actor that owns payment instrument handling and recurring billing.