System Requirements Document for bitshield

1. Introduction

BITSHIELD is a Bitcoin Scam Risk Detector delivered as a single self-contained HTML file that runs fully offline in a browser. A user pastes a suspicious Bitcoin message or offer into a local rule engine, and the app returns a transparent, educational risk analysis: a 0–100 Risk Score, a Risk Level (LOW / MEDIUM / HIGH / CRITICAL), warning signs, highlighted suspicious phrases in the original message, beginner-friendly reasons, next steps, a scam stage tracker, a scam type classification, a mathematical reality check, and a list of rules that were checked but not matched.

The product is deliberately not a simple scam / not-scam verdict. Its flow is RISK SCORE > WARNING SIGNS > WHY RISKY > WHAT TO CHECK. It uses sample/test data only and never handles real Bitcoin, keys, or payments.

The audience is beginners, students, and curious non-experts who need to read a suspicious Bitcoin message the way an investigator reads a case file, plus a college cybersecurity project presenter who needs to demonstrate the rule engine, negation handling, scoring formula, and reality-check math without any backend or real crypto.

2. System Overview

BITSHIELD is a single-page, offline, client-side web application. All logic — the rule engine, scoring, highlighting, scam classification, stage tracking, reality check, action checklist, practice mode, and self-test — executes locally in vanilla JavaScript inside one HTML file. There is no backend, API, database, wallet, blockchain integration, or external request. The app works fully offline.

Actors:

• Suspicious Message Recipient — pastes a suspicious Bitcoin message and reviews the analysis.
• Cybersecurity Learner / Demo Presenter — demonstrates the tool offline with sample data, walks through the rule engine, negation handling, scoring formula, and reality-check math, and runs the self-test.

Accepted behavior: message entry with a 5000-character limit and live counter; five sample buttons with auto-analysis; an 18–20 rule negation-aware local rule engine; exponential 0–100 scoring with an urgency+payment bonus and full formula display; evidence-tape phrase highlighting; warning-sign findings; scam type classification; a five-stage tracker; a compounded-return reality check; a dynamic action checklist with India Cyber Crime Portal and Helpline 1930; a checked-and-clear list; a 6-scenario practice mode; and a true 5-sample self-test.

Ownership: All four destinations (Landing, Analyzer, Practice, Self-Test) are application-owned custom pages with no access requirement. There is no application identity, account, or session continuity — the app is a stateless offline tool.

Narrow exclusions: No real Bitcoin, keys, or payments are ever handled. No frameworks, libraries, backend, API, database, wallet, blockchain, or external requests. No neon, glow gradients, glassmorphism, emoji icons, or generic SaaS/crypto-dashboard look. No innerHTML with user text, no eval, no Function. No nested-quantifier regex.

2a. Product Interpretation and Delivery Boundary

BITSHIELD is delivered as one self-contained HTML file that a user opens directly in a browser. It requires no server, no installation, no login, and no network connection. Every destination is reachable anonymously; there is no account, profile, or saved session. The tool is an educational instrument: it quotes suspicious phrases, tags them as evidence, and frames the message as a case file, but it never asserts that a message is definitively a scam or definitively legitimate.

The current delivery horizon covers the full analyzer, practice mode, and self-test as described in this document. There is no future-horizon functionality specified by the user; anything beyond the current scope is out of bounds.

2b. Source Content Inventory

Not applicable — no reference directive contains content_source.

2c. Page Content and Component Coverage

Landing

• Information/state: Product name BITSHIELD, subtitle "Bitcoin Scam Risk Detector", the explanatory line "Analyze suspicious Bitcoin messages using transparent warning patterns and understand why a message may be risky.", three status labels (OFFLINE DEMO, NO REAL CRYPTO, NO DATA SENT), and a plain-language summary of what the tool does and does not do.
• Primary action: Enter the Analyzer.
• Supporting actions: Read the educational disclaimer; view the flat CSS shield mark.
• Domain entities: Product identity, status labels, disclaimer text.
• Component responsibilities: Header block with shield mark and wordmark; status tag row; subtitle; entry control into the Analyzer; footer disclaimer.
• States: Loading (static, no async work); empty (not applicable — content is static); success (entry control navigates to Analyzer); error (not applicable); recovery (not applicable).

Analyzer

• Information/state: Header with BITSHIELD wordmark, status labels, and subtitle; "Submit the Evidence" section with label "Suspicious message or offer", large textarea (max 5000 chars), live counter "0 / 5000", CHECK MESSAGE and CLEAR buttons; five sample buttons (Fake Giveaway, Guaranteed Profit, Fake Support, Withdrawal Fee, Normal Question); pre-loaded Guaranteed Profit analysis on page load; risk verdict stamp with level and score; text progress bar; "Why this score?" calculation breakdown; highlighted original message with evidence-tape labels; "Warning Signs Detected" findings; scam type card; stage tracker; reality check; "What to Do Now" checklist; "Checked and Clear" list.
• Primary actions: CHECK MESSAGE; CLEAR; click a sample button; click a highlight to scroll/focus its finding.
• Supporting actions: Read the score calculation; read findings; read scam type; read stage tracker; read reality check; follow the India Cyber Crime Portal link; call Helpline 1930.
• Domain entities: Message text, rule matches, weights, bonus, score, risk level, matched phrases, findings, scam family, stages, percentage claims, compounded yearly return, action checklist items, unmatched rules.
• Component responsibilities: Textarea with live counter; sample button row; rule engine; scoring module; verdict stamp; progress bar; calculation breakdown; highlight renderer (textContent/createElement/appendChild only); findings list; scam type card; stage tracker (horizontal desktop / stacked mobile); reality check card; action checklist; checked-and-clear list; aria-live region wrapping result updates.
• States:
  • Loading: On page load, Guaranteed Profit is auto-loaded and analyzed; a brief entrance fade/slide plays (disabled under prefers-reduced-motion).
  • Empty: Friendly message when the textarea is empty or whitespace-only; no analysis is produced.
  • Success: Full analysis rendered with score, level, findings, highlights, scam type, stages, reality check, checklist, and checked-and-clear list.
  • Error: Analysis wrapped in try/catch; a friendly message is shown and no raw error is ever displayed.
  • Recovery: User can CLEAR and re-enter, or click another sample to re-run.

Practice

• Information/state: Exactly 6 scenarios, each with SCAM and SAFE buttons; per-scenario correct/incorrect feedback and explanation. Scenarios cover: send BTC get more back; simple Bitcoin price question; seed phrase request; recovery fee; "Never share your seed phrase"; independent verification.
• Primary actions: Choose SCAM or SAFE for each scenario.
• Supporting actions: Read feedback and explanation.
• Domain entities: Scenario text, expected answer, user answer, feedback, explanation.
• Component responsibilities: Scenario list; SCAM/SAFE button pairs; feedback region.
• States: Loading (static); empty (not applicable); success (correct feedback + explanation); error (incorrect feedback + explanation); recovery (user may re-answer).

Self-Test

• Information/state: RUN SELF-TEST button; per-sample result lines in the form "Fake Giveaway ..... PASS"; summary line "5/5 SELF-TESTS PASSED" (or X/5).
• Primary actions: RUN SELF-TEST.
• Supporting actions: Read per-sample results and summary.
• Domain entities: Sample name, expected level, actual level, pass/fail, summary count.
• Component responsibilities: Run button; results list; summary line.
• States: Loading (idle before run); empty (no results yet); success (all pass); error (one or more fail, shown as X/5); recovery (re-run).

3. Functional Requirements

FR-01 — Single self-contained offline file (explicit) As a Suspicious Message Recipient, I should be able to open BITSHIELD as one self-contained HTML file with HTML + CSS in <style> and vanilla JS in <script>, so that it works fully offline with no frameworks, libraries, backend, API, database, wallet, blockchain, or external requests.

• Trigger/input: Open the HTML file in a browser.
• Observable result: The app loads and functions with no network access.
• Access state: Anonymous, no account.
• Failure/recovery: If a resource fails, the app still renders from the single file.
• Continuation: User proceeds to the Analyzer.

FR-02 — Font fallbacks (explicit) As a Suspicious Message Recipient, I should see headings in "Bricolage Grotesque", Arial, system-ui; body in "IBM Plex Sans", system-ui; and evidence text in "IBM Plex Mono", ui-monospace, monospace, so that typography is consistent even offline.

• Trigger/input: Page render.
• Observable result: Correct font stacks applied by role.
• Access state: Anonymous.
• Failure/recovery: System fallbacks render if named fonts are unavailable.
• Continuation: User reads the page.

FR-03 — Header identity and status (explicit) As a Suspicious Message Recipient, I should see BITSHIELD / Bitcoin Scam Risk Detector, the status labels OFFLINE DEMO, NO REAL CRYPTO, NO DATA SENT, and the text "Analyze suspicious Bitcoin messages using transparent warning patterns and understand why a message may be risky."

• Trigger/input: Page render.
• Observable result: Header with wordmark, status labels, and subtitle.
• Access state: Anonymous.
• Failure/recovery: Static content; no failure path.
• Continuation: User reads the subtitle and proceeds.

FR-04 — Submit the Evidence input (explicit) As a Suspicious Message Recipient, I should see a section "Submit the Evidence" with label "Suspicious message or offer", a large textarea with max 5000 chars, a live counter "0 / 5000", and buttons CHECK MESSAGE and CLEAR.

• Trigger/input: Typing or pasting into the textarea.
• Observable result: Live counter updates; CHECK MESSAGE runs analysis; CLEAR empties the textarea and resets the counter.
• Access state: Anonymous.
• Failure/recovery: Empty, whitespace, emoji, Unicode, non-English, long, and pasted text are handled with friendly messages; analysis is wrapped in try/catch and never shows raw errors.
• Continuation: User reviews the analysis or clears and re-enters.

FR-05 — Five sample buttons with auto-analysis (explicit) As a Suspicious Message Recipient, I should see 5 sample buttons — Fake Giveaway, Guaranteed Profit, Fake Support, Withdrawal Fee, Normal Question — where clicking fills the textarea, updates the counter, and auto-analyzes; on page load, Guaranteed Profit is auto-loaded and analyzed.

• Trigger/input: Click a sample button, or load the page.
• Observable result: Textarea filled, counter updated, analysis rendered.
• Access state: Anonymous.
• Failure/recovery: If analysis fails, a friendly message is shown.
• Continuation: User reviews the analysis.

FR-06 — Exact sample texts (explicit) As a Suspicious Message Recipient, I should see the exact sample texts:

• Giveaway: "Congratulations! You have been selected for an exclusive Bitcoin giveaway. Send 0.01 BTC to the address below and we will send 0.1 BTC back. Act now, this offer expires in 10 minutes!"
• Guaranteed Profit: "Our private Bitcoin investment program guarantees 8% daily profit with zero risk. Deposit BTC today and your returns are guaranteed. Pay a small upfront activation fee before withdrawal."
• Fake Support: "URGENT SECURITY ALERT: Your Bitcoin exchange account will be suspended today. I am from exchange support. Verify your wallet immediately by sending your seed phrase or private key to our support agent."
• Withdrawal Fee: "Your Bitcoin withdrawal is ready, but a refundable 0.02 BTC compliance fee must be paid first. Send the fee to unlock your funds. If you do not pay today, your account may face legal action."
• Normal: "Hi, I am learning about Bitcoin. What is the difference between a Bitcoin wallet address and a private key? I will never share my seed phrase."
• Trigger/input: Click a sample button.
• Observable result: Exact text appears in the textarea.
• Access state: Anonymous.
• Failure/recovery: Static strings; no failure path.
• Continuation: Auto-analysis runs.

FR-07 — Rule engine structure (explicit) As a Suspicious Message Recipient, I should have a JS array of 18–20 rules, each with id, label, weight, regex, explanation, tip, family, and stage.

• Trigger/input: Analysis run.
• Observable result: Rules evaluated against the message.
• Access state: Anonymous.
• Failure/recovery: Safe regex only; no nested quantifiers; bounded wildcards like [\s\S]{0,60}.
• Continuation: Matches feed scoring and findings.

FR-08 — Rule coverage (explicit) As a Suspicious Message Recipient, I should have rules covering: guaranteed profit, unrealistic returns, Bitcoin giveaway, send BTC to get more back, urgency, seed phrase request, private key request, fake exchange support, fake security alert, gift card payment, crypto ATM payment, wallet address, short links, look-alike domains, secrecy, upfront fees, recovery scam, remote-access software, legal threats, password/OTP request, and unexpected crypto payment demand.

• Trigger/input: Analysis run.
• Observable result: Each covered pattern can match and contribute to findings.
• Access state: Anonymous.
• Failure/recovery: Safe regex only.
• Continuation: Matches feed scoring.

FR-09 — Negation handling (explicit) As a Suspicious Message Recipient, I should have "Never share your seed phrase" and "Do not send Bitcoin" NOT trigger rules.

• Trigger/input: Message containing these negations.
• Observable result: No match for the negated rule.
• Access state: Anonymous.
• Failure/recovery: If a negation is missed, the rule would falsely match — this must not occur.
• Continuation: Analysis continues with remaining rules.

FR-10 — Scoring formula (explicit) As a Suspicious Message Recipient, I should see sum = total matched weights; score = round(100 × (1 − e^(−sum/45))), cap 100; +12 bonus to sum when urgency AND payment rules both match; levels 0–24 LOW, 25–47 MEDIUM, 48–71 HIGH, 72–100 CRITICAL; and the full calculation (weights, bonus, formula, final score).

• Trigger/input: Analysis run.
• Observable result: Score, level, and full calculation displayed.
• Access state: Anonymous.
• Failure/recovery: If sum is 0, score is 0 and level is LOW.
• Continuation: User reads "Why this score?".

FR-11 — Sample level targets (explicit) As a Suspicious Message Recipient, I should see Giveaway, Guaranteed Profit, and Fake Support reach CRITICAL; Withdrawal Fee reach HIGH; and Normal reach LOW, with weights tuned so these pass.

• Trigger/input: Click each sample.
• Observable result: Correct level for each sample.
• Access state: Anonymous.
• Failure/recovery: If a target fails, weights must be tuned.
• Continuation: User reviews the analysis.

FR-12 — Result stamp and progress bar (explicit) As a Suspicious Message Recipient, I should see a prominent stamp-style level + "86 / 100" + a text progress bar, then "Why this score?" listing patterns, weights, bonus, formula; updates wrapped in aria-live.

• Trigger/input: Analysis run.
• Observable result: Stamp, score, progress bar, and calculation rendered; aria-live announces updates.
• Access state: Anonymous.
• Failure/recovery: If analysis fails, a friendly message is shown.
• Continuation: User reads findings.

FR-13 — Highlighted evidence (explicit) As a Suspicious Message Recipient, I should see the original message with matched phrases in evidence-tape styling; never use innerHTML with user text; use textContent/createElement/appendChild; no eval or Function; clicking a highlight scrolls/focuses its finding.

• Trigger/input: Analysis run; click a highlight.
• Observable result: Matched phrases rendered as evidence tape; clicking scrolls/focuses the finding.
• Access state: Anonymous.
• Failure/recovery: If no matches, the message renders as plain text.
• Continuation: User reads the finding.

FR-14 — Warning Signs Detected (explicit) As a Suspicious Message Recipient, I should see "Warning Signs Detected" with each finding showing severity, rule name, matched evidence, why risky, and what to check, in plain beginner language.

• Trigger/input: Analysis run.
• Observable result: Findings list rendered.
• Access state: Anonymous.
• Failure/recovery: If no matches, the section shows a clear empty state.
• Continuation: User reads scam type and next steps.

FR-15 — Scam type card (explicit) As a Suspicious Message Recipient, I should see the strongest family from Investment, Giveaway, Impersonation, Credential Theft, Phishing, Pressure, Advance Fee, Recovery, Device Takeover, Payment, with name + "How it works", and the note that it is an educational classification, not a legal determination.

• Trigger/input: Analysis run.
• Observable result: Scam type card rendered.
• Access state: Anonymous.
• Failure/recovery: If no family matches, a neutral state is shown.
• Continuation: User reads the stage tracker.

FR-16 — Stage tracker (explicit) As a Suspicious Message Recipient, I should see HOOK > TRUST > PRESSURE > PAYMENT > EXIT with active stages from matched rules; horizontal on desktop, stacked on mobile.

• Trigger/input: Analysis run.
• Observable result: Stage tracker rendered with active stages.
• Access state: Anonymous.
• Failure/recovery: If no stages match, all stages show inactive.
• Continuation: User reads the reality check.

FR-17 — Reality check (explicit) As a Suspicious Message Recipient, I should see detection of "X% daily/weekly/monthly" claims, the compounded yearly return computed (e.g. (1.08^365 − 1) × 100), and the note "This is a mathematical reality check, not proof that the sender's claim is true. Extremely large repeated returns are a reason to stop and independently verify the offer."

• Trigger/input: Message containing a percentage claim.
• Observable result: Compounded yearly return displayed with the note.
• Access state: Anonymous.
• Failure/recovery: If no claim is found, the card shows a neutral state.
• Continuation: User reads the action checklist.

FR-18 — What to Do Now (explicit) As a Suspicious Message Recipient, I should see a dynamic checklist. High risk: don't send Bitcoin, don't pay upfront fees, verify independently, never share seed phrase/private key/passwords/OTP, no remote-access software, don't click suspicious links, ignore deadlines. Low risk: keep verifying, don't share credentials, verify payment requests independently. Include India Cyber Crime Portal https://cybercrime.gov.in/ (opens in new tab, rel="noopener noreferrer") and Helpline 1930.

• Trigger/input: Analysis run.
• Observable result: Checklist rendered by risk level; portal link and helpline shown.
• Access state: Anonymous.
• Failure/recovery: If analysis fails, a friendly message is shown.
• Continuation: User follows the checklist.

FR-19 — Checked and Clear (explicit) As a Suspicious Message Recipient, I should see rules that did not match with a check mark and the note "No matched rule is not proof that a message is legitimate."

• Trigger/input: Analysis run.
• Observable result: Unmatched rules listed with check marks and the note.
• Access state: Anonymous.
• Failure/recovery: If all rules match, the list shows an empty state.
• Continuation: User reads practice mode.

FR-20 — Practice mode (explicit) As a Cybersecurity Learner / Demo Presenter, I should see exactly 6 scenarios, each with SCAM and SAFE buttons, then correct/incorrect feedback + explanation, covering: send BTC get more back, simple Bitcoin price question, seed phrase request, recovery fee, "Never share your seed phrase", independent verification.

• Trigger/input: Choose SCAM or SAFE.
• Observable result: Feedback and explanation shown.
• Access state: Anonymous.
• Failure/recovery: User may re-answer.
• Continuation: User proceeds to self-test.

FR-21 — Self-test (explicit) As a Cybersecurity Learner / Demo Presenter, I should see a RUN SELF-TEST button that really runs the analyzer on all 5 samples, compares to expected levels, shows "Fake Giveaway ..... PASS" lines, and "5/5 SELF-TESTS PASSED" (or X/5).

• Trigger/input: Click RUN SELF-TEST.
• Observable result: Per-sample result lines and summary.
• Access state: Anonymous.
• Failure/recovery: If a sample fails, X/5 is shown.
• Continuation: User re-runs or reviews.

FR-22 — Accessibility (explicit) As a Suspicious Message Recipient, I should have proper labels, keyboard navigation, visible focus, aria-live, WCAG AA contrast, meaning never by color alone, and touch-friendly buttons.

• Trigger/input: Keyboard or touch interaction.
• Observable result: All controls reachable and labeled; focus visible; meaning conveyed by text as well as color.
• Access state: Anonymous.
• Failure/recovery: If a control is unreachable, it must be fixed.
• Continuation: User completes the task.

FR-23 — Responsive layout (explicit) As a Suspicious Message Recipient, I should have a layout that works at 320/360/390px, tablet, and desktop with NO horizontal scroll; mobile single column with full-width buttons; desktop two columns: LEFT input + highlighted message + findings; RIGHT scam type, reality check, what to do, checked and clear, practice, self-test.

• Trigger/input: Resize viewport.
• Observable result: Layout adapts with no horizontal scroll.
• Access state: Anonymous.
• Failure/recovery: If overflow occurs, it must be fixed.
• Continuation: User reads the page.

FR-24 — Theme (explicit) As a Suspicious Message Recipient, I should have light and dark themes via CSS variables following prefers-color-scheme; dark = dark blue-grey paper, light ink, muted borders, deep red stamp; not cyberpunk.

• Trigger/input: OS theme change.
• Observable result: Theme switches accordingly.
• Access state: Anonymous.
• Failure/recovery: If the media query is unsupported, light theme renders.
• Continuation: User reads the page.

FR-25 — Animation (explicit) As a Suspicious Message Recipient, I should have only one subtle entrance fade/slide; static slight stamp rotation; all motion disabled for prefers-reduced-motion; localStorage optional, in try/catch.

• Trigger/input: Page load; reduced-motion preference.
• Observable result: Entrance animation plays once; stamp stays rotated; motion disabled under reduced-motion.
• Access state: Anonymous.
• Failure/recovery: If localStorage throws, it is caught and ignored.
• Continuation: User reads the page.

FR-26 — Hierarchy (explicit) As a Suspicious Message Recipient, I should see risk level and score as the loudest elements, then warning signs, highlighted evidence, why risky, what to do; secondary cards quieter.

• Trigger/input: Page render.
• Observable result: Visual hierarchy matches the specified order.
• Access state: Anonymous.
• Failure/recovery: Static; no failure path.
• Continuation: User reads the page.

FR-27 — Footer disclaimer (explicit) As a Suspicious Message Recipient, I should see the footer: "BitShield provides pattern-based educational guidance, not proof that a message is a scam or legitimate. Always verify important claims independently. This demo uses sample/test data only and never handles real Bitcoin or money."

• Trigger/input: Page render.
• Observable result: Footer text displayed.
• Access state: Anonymous.
• Failure/recovery: Static; no failure path.
• Continuation: User reads the disclaimer.

FR-28 — Final check (explicit) As a Cybersecurity Learner / Demo Presenter, I should have no console errors, all five sample levels correct, negation works, bonus works, formula shown, highlights safe and clickable, 6 practice questions, self-test truly runs, and the app works offline.

• Trigger/input: Run the app and self-test.
• Observable result: All checks pass.
• Access state: Anonymous.
• Failure/recovery: If a check fails, it must be fixed.
• Continuation: Demo completes.

FR-29 — Anonymous entry to the Landing page (required_inference) As a Suspicious Message Recipient, I should reach an explanatory Landing entry before analysis, so that I understand the tool's purpose and boundaries before pasting a message.

• Trigger/input: Open the app.
• Observable result: Landing content with entry control into the Analyzer.
• Access state: Anonymous, no account.
• Failure/recovery: Static; no failure path.
• Continuation: User enters the Analyzer.

FR-30 — Offline analyzer usability (required_inference) As a Suspicious Message Recipient, I should be able to use the Analyzer offline with no backend, API, database, wallet, blockchain, or external requests.

• Trigger/input: Open the Analyzer offline.
• Observable result: Full analysis runs locally.
• Access state: Anonymous.
• Failure/recovery: If analysis fails, a friendly message is shown.
• Continuation: User reviews results.

FR-31 — Safe local input handling (required_inference) As a Suspicious Message Recipient, I should have my input handled safely and never see raw errors.

• Trigger/input: Paste or type any text.
• Observable result: Analysis runs or a friendly message is shown; no raw error is displayed.
• Access state: Anonymous.
• Failure/recovery: try/catch wraps analysis.
• Continuation: User retries or clears.

FR-32 — Practice and Self-Test reachability (required_inference) As a Cybersecurity Learner / Demo Presenter, I should be able to reach Practice and Self-Test as local learning and validation continuations.

• Trigger/input: Navigate to Practice or Self-Test.
• Observable result: Both destinations are reachable and functional offline.
• Access state: Anonymous.
• Failure/recovery: If a destination fails to render, it must be fixed.
• Continuation: User completes practice or self-test.

4. User Personas

Suspicious Message Recipient

Product context: A person who has received a suspicious Bitcoin message or offer — via chat, email, or social media — and wants to understand whether it is risky before acting. They are not a security expert and need plain-language explanations.

Primary goal: Understand why a message may be risky, see the specific warning signs, and know what to check or do next.

Distinct accepted responsibilities: Paste or select a message; run the analysis; read the risk score and level; read the highlighted evidence; read the warning signs; read the scam type and stage tracker; read the reality check; follow the action checklist; review the checked-and-clear list.

Relevant inputs or decisions: The message text; whether to trust the sender; whether to send Bitcoin, pay a fee, share credentials, or click a link.

Interactions with other accepted participants: None — this persona works alone with the tool.

Observable success: A clear risk score and level, specific warning signs with evidence, a scam type, a stage tracker, a reality check, and a concrete action checklist.

Cybersecurity Learner / Demo Presenter

Product context: A student or presenter demonstrating a college cybersecurity project. They need the app to run fully offline with sample data and to show the full scoring calculation, negation handling, and reality-check math without any backend or real crypto.

Primary goal: Demonstrate the rule engine, scoring formula, negation handling, and self-test convincingly to an audience.

Distinct accepted responsibilities: Load samples; show the full calculation; demonstrate negation handling; run the self-test on all five samples; walk through practice scenarios; explain the reality-check math.

Relevant inputs or decisions: Which sample to load; whether to run the self-test; which practice scenarios to demonstrate.

Interactions with other accepted participants: None — this persona works alone with the tool.

Observable success: All five sample levels correct; self-test shows 5/5; formula and bonus visible; negation works; no console errors; works offline.

5. Core User Flows

Flow 1 — Suspicious Message Recipient analyzes a pasted message

1. The user opens the BITSHIELD HTML file in a browser. The Landing page renders with the wordmark, status labels, subtitle, and an entry control into the Analyzer.
2. The user enters the Analyzer. On page load, the Guaranteed Profit sample is auto-loaded into the textarea, the counter updates, and the analysis runs automatically.
3. The user reads the risk verdict stamp (level + score), the text progress bar, and the "Why this score?" calculation showing weights, bonus, formula, and final score.
4. The user reads the highlighted original message with evidence-tape labels over matched phrases.
5. The user clicks a highlight. The page scrolls to and focuses the corresponding finding in "Warning Signs Detected".
6. The user reads each finding: severity, rule name, matched evidence, why risky, what to check.
7. The user reads the scam type card (strongest family + "How it works") and the stage tracker (HOOK > TRUST > PRESSURE > PAYMENT > EXIT with active stages).
8. The user reads the reality check (compounded yearly return and the note).
9. The user reads the "What to Do Now" checklist and, if needed, follows the India Cyber Crime Portal link (opens in a new tab, rel="noopener noreferrer") or calls Helpline 1930.
10. The user reads the "Checked and Clear" list and the note that no matched rule is not proof that a message is legitimate.
11. Failure/recovery: If the textarea is empty or whitespace-only, a friendly message is shown. If analysis throws, a friendly message is shown and no raw error is displayed. The user can CLEAR and re-enter, or click another sample.
12. Continuation: The user may paste a different message, click another sample, or move to Practice or Self-Test.

Flow 2 — Suspicious Message Recipient loads a sample

1. The user is on the Analyzer.
2. The user clicks one of the five sample buttons: Fake Giveaway, Guaranteed Profit, Fake Support, Withdrawal Fee, or Normal Question.
3. The textarea fills with the exact sample text, the counter updates, and the analysis auto-runs.
4. The user reads the resulting score, level, findings, highlights, scam type, stages, reality check, checklist, and checked-and-clear list.
5. Failure/recovery: If analysis throws, a friendly message is shown.
6. Continuation: The user may click another sample or paste their own message.

Flow 3 — Suspicious Message Recipient clears and re-enters

1. The user is on the Analyzer with a previous analysis displayed.
2. The user clicks CLEAR.
3. The textarea empties and the counter resets to "0 / 5000".
4. The user pastes or types a new message.
5. The user clicks CHECK MESSAGE.
6. The analysis runs and the results update.
7. Failure/recovery: If the textarea is empty or whitespace-only, a friendly message is shown.
8. Continuation: The user reviews the new analysis.

Flow 4 — Cybersecurity Learner / Demo Presenter runs the self-test

1. The presenter navigates to the Self-Test page.
2. The presenter clicks RUN SELF-TEST.
3. The analyzer runs on all 5 samples and compares each result to its expected level.
4. The page shows per-sample result lines in the form "Fake Giveaway ..... PASS" and a summary line "5/5 SELF-TESTS PASSED" (or X/5).
5. Failure/recovery: If a sample fails, X/5 is shown and the presenter can re-run.
6. Continuation: The presenter returns to the Analyzer to walk through the calculation.

Flow 5 — Cybersecurity Learner / Demo Presenter walks through practice scenarios

1. The presenter navigates to the Practice page.
2. The presenter reads the first of exactly 6 scenarios.
3. The presenter chooses SCAM or SAFE.
4. The page shows correct/incorrect feedback and an explanation.
5. The presenter repeats for the remaining scenarios: send BTC get more back; simple Bitcoin price question; seed phrase request; recovery fee; "Never share your seed phrase"; independent verification.
6. Failure/recovery: The presenter may re-answer any scenario.
7. Continuation: The presenter moves to the Self-Test page.

Flow 6 — Cybersecurity Learner / Demo Presenter demonstrates negation handling

1. The presenter is on the Analyzer.
2. The presenter clicks the Normal Question sample, which contains "I will never share my seed phrase."
3. The analysis runs and the seed-phrase rule does not trigger.
4. The presenter points out the LOW level and the checked-and-clear list.
5. Failure/recovery: If the negation were missed, the rule would falsely match — this must not occur.
6. Continuation: The presenter explains the negation handling to the audience.

6. Visuals Colors and Theme

Muse: Virgil Abloh. Headline: Evidence-room quotation marks — an industrial case file for suspicious Bitcoin messages.

The direction is authoritative for this section. The palette is flat, industrial, and forensic — no gradients, no glow, no glass.

Light mode tokens:

• Background: #E7E9EC (pale industrial blue-grey workspace)
• Surface: #FBFBFA (near-white evidence sheet)
• Text: #12151A (near-black ink)
• Primary: #1B1F24
• Accent: #F04E1E (safety orange — matched evidence tape, active states, CHECK MESSAGE button, rule-weight chips)
• Muted: #6B7280
• Border: #C9CDD3 (1px hairline)
• Verdict red: #8E1B1B (rotated rubber-stamp verdict and CRITICAL level)
• MEDIUM: #B7791F (muted amber)
• HIGH: #4A5058 (neutral between amber and red)
• LOW/clear: #2F6B4F (dark muted green)

Dark mode tokens (via prefers-color-scheme):

• Background: dark blue-grey paper
• Surface: dark blue-grey sheet
• Text: light ink
• Borders: muted
• Stamp: deep red
• Not cyberpunk.

Typography:

• Headings: "Bricolage Grotesque", Arial, system-ui — 600–800 weight, tight −0.02em tracking; sentence case for section titles, ALL CAPS with +0.14em letterspacing for label-like headings (BITSHIELD, SUBMIT THE EVIDENCE, WARNING SIGNS DETECTED).
• Body: "IBM Plex Sans", system-ui.
• Evidence and all numerals: "IBM Plex Mono", ui-monospace, monospace at 14–15px.
• Scale (1.25 modular): 56 / 44 / 34 / 24 / 18 / 16 / 14 with a 12px micro-label tier.
• Risk level: clamp(40px, 8vw, 88px).
• Score: clamp(34px, 6vw, 64px).
• Section headings: clamp(20px, 3vw, 30px).
• Body: 16px / 1.6.

Shape language: Hard-edged industrial rectangles with 2px radius at most; 1px hairline borders; exposed grid lines behind section headers; hazard-stripe tape bars as section accents. Evidence tags are small rectangles with a 2px left orange bar and a slight 1.5deg rotation. The shield mark is a flat two-tone CSS polygon in ink and orange — no gradient, no glow. Buttons are chunky rectangles with a 2px ink border and an offset solid shadow on hover.

Spacing rhythm: 12-column grid with visible 1px column rules behind the header at 40% opacity; 32–48px gutters on desktop, 16px on mobile. Every card is a numbered evidence sheet: "EXHIBIT 01 — SUBMIT THE EVIDENCE".

Imagery style: No photography and no illustrations. Imagery is diagrammatic and industrial: the CSS shield mark, hazard-stripe tape bars, ruled evidence sheets, monospace metadata blocks, and a stage tracker rendered as a five-stop transit line with square stations. The highlighted message itself is the hero image — a monospace evidence sheet with orange taped labels over matched phrases.

7. Signature Design Concept

The public entry is a full-width evidence desk header, not a centred SaaS hero.

• Left edge: the flat CSS shield mark at 72px in ink with an orange lower band.
• Immediately right: BITSHIELD set in Bricolage Grotesque 800 at clamp(44px, 9vw, 96px) with +0.02em tracking, sitting on a 1px ink rule that spans the viewport.
• Under the rule: three status tags — OFFLINE DEMO, NO REAL CRYPTO, NO DATA SENT — in 12px monospace caps inside bordered rectangles with a small square dot in amber, ink, and green.
• Subtitle: runs full measure beneath in IBM Plex Sans 18px.
• Behind the header: a faint 12-column grid of 1px #C9CDD3 vertical rules at 40% opacity, plus a hazard-stripe bar (8px, orange and ink diagonals) pinned to the very top edge.
• Below the header: the desk begins — on the left the Submit the Evidence sheet, on the right a pre-loaded Guaranteed Profit analysis with the deep-red rubber stamp already pressed at −3deg reading CRITICAL.

This concept recomposes only accepted content, states, and controls. It introduces no new behavior, page, or destination.

8. Interaction Model & Motion Direction

Interaction Model: Static (direction) Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief:

• Focal subject: the evidence desk header — the flat CSS shield mark, the BITSHIELD wordmark on a 1px ink rule, the three status tags, and the hazard-stripe bar pinned to the top edge.
• Input → transformation → outcome thesis: on load, the whole desk fades and slides in once (300ms, ease-out); the stamp presses in with a 120ms scale from 1.06 to 1 and stays static at −3deg rotation; the highlighted message sheet renders with orange taped labels over matched phrases. The outcome is a composed first frame that reads as a case file, not a marketing hero.
• Motion vocabulary: one entrance fade/slide; one stamp press; one highlight underline draw on click (1px orange). No marquees, no parallax, no particle fields.
• Composed first frame: shield mark at left, wordmark on the ink rule, status tags beneath, subtitle full measure, hazard-stripe bar at the top edge, 12-column forensic grid behind at 40% opacity, and the pre-loaded Guaranteed Profit analysis with the CRITICAL stamp already pressed.
• Reduced-motion state: all motion disabled under prefers-reduced-motion: reduce; the desk renders in its final composed state with the stamp static at −3deg.

9. Non-Functional Requirements

NFR-01 — Offline operation (explicit) The app must work fully offline with no external requests. Rationale: the user requires a self-contained demo that runs without network access.

NFR-02 — Single-file delivery (explicit) The app must be one self-contained HTML file with HTML + CSS in <style> and vanilla JS in <script>. Rationale: the user requires a single-file deliverable.

NFR-03 — No frameworks or backend (explicit) No frameworks, libraries, backend, API, database, wallet, blockchain, or external requests. Rationale: the user requires a purely local tool.

NFR-04 — Safe DOM handling (explicit) Never use innerHTML with user text; use textContent / createElement / appendChild. No eval or Function. Rationale: the user requires safe rendering of untrusted input.

NFR-05 — Safe regex (explicit) Use safe regex only: no nested quantifiers; bounded wildcards like [\s\S]{0,60}. Rationale: the user requires regex that cannot cause catastrophic backtracking.

NFR-06 — Negation correctness (explicit) "Never share your seed phrase" and "Do not send Bitcoin" must NOT trigger rules. Rationale: the user requires correct negation handling.

NFR-07 — Input limit (explicit) Textarea max 5000 chars. Rationale: the user specifies a 5000-character limit.

NFR-08 — Rule count (explicit) The rule engine must contain 18–20 rules. Rationale: the user specifies this range.

NFR-09 — Practice count (explicit) Practice mode must have exactly 6 scenarios. Rationale: the user specifies exactly 6.

NFR-10 — Visual exclusions (explicit) No neon, glow gradients, glassmorphism, emoji icons, or generic SaaS/crypto-dashboard look; simple CSS shield mark, no emoji logo. Rationale: the user specifies the "Cybersecurity Evidence Desk" aesthetic.

NFR-11 — No horizontal scroll (explicit) No horizontal scroll at 320/360/390px, tablet, or desktop. Rationale: the user requires responsive behavior without horizontal scroll.

NFR-12 — Reduced motion (explicit) Disable all motion for prefers-reduced-motion. Rationale: the user requires reduced-motion support.

NFR-13 — No raw errors (explicit) Never show raw errors; wrap analysis in try/catch. Rationale: the user requires friendly error handling.

NFR-14 — localStorage safety (explicit) localStorage is optional and must be wrapped in try/catch. Rationale: the user requires safe optional storage.

NFR-15 — External link safety (explicit) The India Cyber Crime Portal link must open in a new tab with rel="noopener noreferrer". Rationale: the user specifies this link behavior.

NFR-16 — Scoring formula (explicit) score = round(100 × (1 − e^(−sum/45))), cap 100; +12 bonus to sum when urgency AND payment rules both match; levels 0–24 LOW, 25–47 MEDIUM, 48–71 HIGH, 72–100 CRITICAL. Rationale: the user specifies this formula and these thresholds.

NFR-17 — Sample level targets (explicit) Giveaway, Guaranteed Profit, Fake Support = CRITICAL; Withdrawal Fee = HIGH; Normal = LOW. Rationale: the user specifies these targets.

NFR-18 — Accessibility (explicit) Proper labels, keyboard navigation, visible focus, aria-live, WCAG AA contrast, meaning never by color alone, touch-friendly buttons. Rationale: the user requires accessible behavior.

NFR-19 — Theme (explicit) Light and dark via CSS variables following prefers-color-scheme; dark = dark blue-grey paper, light ink, muted borders, deep red stamp; not cyberpunk. Rationale: the user specifies theming.

NFR-20 — Animation (explicit) Only one subtle entrance fade/slide; static slight stamp rotation. Rationale: the user specifies restrained motion.

NFR-21 — Hierarchy (explicit) Risk level and score are the loudest elements, then warning signs, highlighted evidence, why risky, what to do; secondary cards quieter. Rationale: the user specifies visual hierarchy.

NFR-22 — No console errors (explicit) No console errors. Rationale: the user requires a clean demo.

10. Tech Stack

• Delivery: One self-contained HTML file. HTML + CSS in <style> + vanilla JS in <script>. (explicit)
• Runtime: Browser only; no backend, API, database, wallet, blockchain, or external requests. (explicit)
• Fonts: System font fallbacks — headings "Bricolage Grotesque", Arial, system-ui; body "IBM Plex Sans", system-ui; evidence text "IBM Plex Mono", ui-monospace, monospace. (explicit)
• Storage: localStorage optional, wrapped in try/catch. (explicit)
• No frameworks or libraries. (explicit)

11. Assumptions and Constraints

Assumptions:

• The user opens the HTML file directly in a modern browser. (required_inference)
• The user has JavaScript enabled. (required_inference)
• The user's browser supports prefers-color-scheme and prefers-reduced-motion; if not, light theme and full motion render. (required_inference)

Constraints:

• ONE self-contained HTML file: HTML + CSS in <style> + vanilla JS in <script>; no frameworks, libraries, backend, API, database, wallet, blockchain, or external requests. (explicit)
• Must work fully offline. (explicit)
• Use sample/test data only; never handle real Bitcoin, keys, or payments. (explicit)
• Never use innerHTML with user text; use textContent / createElement / appendChild; no eval or Function. (explicit)
• Use safe regex only: no nested quantifiers; bounded wildcards like [\s\S]{0,60}. (explicit)
• Ignore negations: "Never share your seed phrase" and "Do not send Bitcoin" must NOT trigger rules. (explicit)
• Textarea max 5000 chars. (explicit)
• Rule engine must contain 18–20 rules. (explicit)
• Practice mode must have exactly 6 scenarios. (explicit)
• No neon, glow gradients, glassmorphism, emoji icons, or generic SaaS/crypto-dashboard look; simple CSS shield mark, no emoji logo. (explicit)
• No horizontal scroll at 320/360/390px, tablet, or desktop. (explicit)
• Disable all motion for prefers-reduced-motion. (explicit)
• Never show raw errors; wrap analysis in try/catch. (explicit)
• localStorage optional, in try/catch. (explicit)
• India Cyber Crime Portal link must open in a new tab with rel="noopener noreferrer". (explicit)
• Scoring formula: score = round(100 × (1 − e^(−sum/45))), cap 100; +12 bonus to sum when urgency AND payment rules both match; levels 0–24 LOW, 25–47 MEDIUM, 48–71 HIGH, 72–100 CRITICAL. (explicit)
• Sample level targets: Giveaway, Guaranteed Profit, Fake Support = CRITICAL; Withdrawal Fee = HIGH; Normal = LOW. (explicit)

12. Glossary

• BITSHIELD: The product name for the Bitcoin Scam Risk Detector.
• Risk Score: A 0–100 number computed from matched rule weights using the exponential formula.
• Risk Level: One of LOW, MEDIUM, HIGH, CRITICAL, derived from the Risk Score thresholds.
• Rule Engine: The local JS array of 18–20 rules, each with id, label, weight, regex, explanation, tip, family, and stage.
• Weight: The numeric contribution of a matched rule to the sum.
• Bonus: The +12 addition to the sum when urgency AND payment rules both match.
• Evidence Tape: The visual styling applied to matched phrases in the original message.
• Finding: A warning sign entry with severity, rule name, matched evidence, why risky, and what to check.
• Scam Type: The strongest family from Investment, Giveaway, Impersonation, Credential Theft, Phishing, Pressure, Advance Fee, Recovery, Device Takeover, Payment.
• Stage Tracker: The HOOK > TRUST > PRESSURE > PAYMENT > EXIT progression with active stages from matched rules.
• Reality Check: The compounded yearly return computed from a detected "X% daily/weekly/monthly" claim.
• Checked and Clear: The list of rules that did not match, with a check mark and the note that no matched rule is not proof that a message is legitimate.
• Practice Mode: The 6-scenario scam-versus-safe learning exercise.
• Self-Test: The button that runs the analyzer on all 5 samples and reports pass/fail.