Merge pull request #6 from madijonovsardorbek544-cmyk/refactor-app-architecture-and-improve-features

Move MVP toward evaluation-driven pilot platform

Author: madijonovsardorbek544-cmyk

README.md

@@ -0,0 +1,34 @@
+# Counselor Interview Guide
+
+## Interview principles
+- Ask about recent workflows before showing product screens.
+- Avoid asking “Would this be useful?” first; ask what they currently do and where it fails.
+- Do not lead with desired answers such as “Does the analyst view help?”
+- Collect concrete examples as redacted patterns, not raw student messages.
+
+## Questions for counselors
+1. What scam or confusing-message patterns do international students bring to you most often?
+2. How do you currently decide whether to escalate a message?
+3. Which official channels do you want students to use before paying, clicking, or sending documents?
+4. Which result wording would reduce panic while still encouraging action?
+5. What would make a dashboard report credible enough for monthly awareness planning?
+
+## Questions for education centers
+1. How do you verify agents, payment instructions, scholarship offers, and admissions portals?
+2. What countries, platforms, and languages create the most confusion?
+3. What kinds of false alarms would damage trust with students or partner institutions?
+4. What documentation would you need before recommending the tool?
+
+## Questions for students and parents
+1. When you receive an urgent study-abroad message, what do you usually do first?
+2. Which parts of the result are clear or confusing?
+3. Would you know which official office or website to contact after seeing the script?
+4. What private data would you worry about entering?
+5. Did the score feel too low, accurate, or too high?
+
+## Evidence to collect
+- Screen-level confusion points.
+- Misunderstood terms or icons.
+- Missing official verification channels.
+- False-positive and missed-risk categories.
+- Confidence in next action, not certainty of fraud.

docs/COUNSELOR_INTERVIEW_GUIDE.md

@@ -0,0 +1,53 @@
+# Institution Pilot Playbook
+
+## 30-day process
+
+### Week 1 — Setup
+- Confirm official payment, admissions, visa, housing, testing, and agent-verification resources.
+- Name counselor/staff owners for escalations.
+- Review privacy language and decide whether Firebase is configured or local/sample mode is used.
+- Define pilot success and stopping criteria.
+
+### Week 2 — Awareness launch
+- Share the checker link with a limited student group.
+- Run a short awareness session using synthetic examples from the case library.
+- Explain that the product detects risk indicators, not certainty.
+- Remind students never to paste passports, card numbers, passwords, OTPs, or private document images.
+
+### Week 3 — Review and adjust
+- Review anonymized dashboard categories, channels, claimed authorities, and feedback trends.
+- Identify top false-positive and missed-risk categories.
+- Update warnings and resource links if counselors find confusing wording.
+- Do not collect raw messages through informal channels.
+
+### Week 4 — Export and decision
+- Export the Markdown report from the dashboard.
+- Compare success metrics to pilot goals.
+- Decide whether to continue, revise, expand, or stop.
+
+## Data collected
+- Redacted report payloads only after consent.
+- Risk score, level, context, platform, country/region, and claimed authority if provided.
+- Anonymous feedback fields: helpfulness, official verification status, calibration, optional category.
+
+## Data never collected by default
+- Raw suspicious messages.
+- Passport scans, student IDs, bank/card details, passwords, OTPs, screenshots with personal data, or legal case files.
+- Certainty labels that claim a person or organization committed fraud.
+
+## Awareness session structure
+- Start with common cross-border pressure tactics.
+- Show synthetic examples and resource packs.
+- Demonstrate official verification scripts.
+- Close with escalation contacts and “pause before paying/clicking/sharing” guidance.
+
+## Exporting reports
+- Open Dashboard.
+- Select sample/local/Firebase source mode and date range.
+- Confirm the source label is accurate.
+- Click “Download Markdown report.”
+
+## Success/failure criteria
+- Continue if students and counselors find next steps clear, privacy concerns are manageable, and benchmark checks remain stable.
+- Revise if false positives cluster around legitimate deadlines or payment reminders.
+- Stop or narrow scope if users misunderstand scores as certainty or if privacy expectations cannot be met.

docs/PILOT_PLAYBOOK.md

@@ -0,0 +1,40 @@
+# Privacy Threat Model
+
+## Assets
+- Student messages and contextual metadata.
+- Redacted report payloads.
+- Anonymous feedback records.
+- Institution dashboard trend exports.
+- Official resource links and verification scripts.
+
+## Threat actors
+- Scammers attempting to learn detection patterns.
+- Curious insiders or misconfigured Firebase readers.
+- Users accidentally pasting sensitive documents.
+- Institutions over-interpreting scores as proof.
+- Attackers trying to inject malicious links into shared examples.
+
+## Privacy risks
+- Raw messages may contain passports, card details, login codes, addresses, or immigration identifiers.
+- Trend reports could expose small-group patterns if a pilot group is tiny.
+- Feedback could become sensitive if free-text raw messages were allowed.
+
+## Misuse risks
+- Treating scores as certainty or legal findings.
+- Blocking legitimate institutional communications solely because of a score.
+- Collecting raw scam reports outside the redacted consent flow.
+- Using the tool for populations outside its validated scope without retesting.
+
+## Mitigations
+- Local analysis by default.
+- No raw message storage in feedback.
+- Redacted report preview plus consent.
+- Clear false-positive warning and “risk indicators detected” language.
+- Dashboard source labels for sample/local/Firebase data.
+- Documentation for pilot privacy boundaries and validation needs.
+
+## Remaining limitations
+- Redaction is best effort and can miss unusual identifiers.
+- Rule-based scoring can miss new adversarial language.
+- Firebase deployment requires project-specific security rules, authentication, retention, and access review.
+- Small pilots need aggregation thresholds before sharing institution-wide conclusions.

docs/PRIVACY_THREAT_MODEL.md

@@ -0,0 +1,40 @@
+# Product Requirements
+
+## Target users
+- International students and families.
+- School counselors, international offices, admissions, housing, testing, and financial-aid staff.
+- Education centers and verified advisers.
+- Institutions running pre-arrival scam-awareness pilots.
+
+## Problem
+International students receive cross-border messages involving visas, admissions, scholarships, housing, testing, payments, documents, and agents. Scammers exploit unfamiliar bureaucracy, urgency, language gaps, and family pressure. Students need safe verification steps before paying, clicking, or sharing documents.
+
+## Non-goals
+- Do not claim certainty or make legal findings.
+- Do not replace immigration, legal, financial, emergency, or law-enforcement advice.
+- Do not collect raw sensitive messages by default.
+- Do not market as AI if the system is rules/evaluation driven.
+
+## MVP features
+- Local-first scam checker.
+- Transparent analyzer rules and combination boosts.
+- Counselor / Analyst View.
+- Case library and resource packs.
+- Redacted reporting flow.
+- Anonymous feedback loop.
+- Institution dashboard with Markdown export.
+- Benchmark evaluation dataset and tests.
+
+## Future features
+- Institution-specific verified resource configuration.
+- Aggregation thresholds and retention controls.
+- Multilingual UX validation.
+- Counselor review queue for consented, redacted cases.
+- Secure authenticated institution dashboards.
+
+## Success metrics
+- High-risk benchmark examples do not score low.
+- Low-risk legitimate examples remain low/medium.
+- Students can identify official next steps.
+- Counselors trust explanations enough for advising.
+- Feedback produces actionable false-positive and missed-risk categories without raw message collection.

docs/PRODUCT_REQUIREMENTS.md

@@ -0,0 +1,39 @@
+# Validation Plan
+
+## What needs to be validated
+- Analyzer calibration: high-risk examples should not be missed as low risk, and normal university reminders should not be pushed into high/critical without strong indicators.
+- Counselor usefulness: explanations, evidence, and verification scripts must support real advising conversations.
+- Student usability: international students and parents should understand “risk indicators detected” without panic or certainty claims.
+- Privacy comfort: users must understand that checker input is local by default and feedback does not store raw messages.
+- Pilot dashboard value: institutions need actionable categories, channels, authorities, feedback insights, and recommended interventions.
+
+## Target users
+- International students before arrival and during first year.
+- Parents and guardians supporting cross-border decisions.
+- School counselors, admissions staff, international student offices, housing offices, and financial-aid teams.
+- Education centers and verified advisers who help students apply abroad.
+
+## Success metrics
+- 90%+ of seeded high-risk benchmark examples are not scored low.
+- Legitimate low-risk reminders remain low/medium in benchmark checks.
+- Students can identify at least one official verification step after using a result.
+- Counselors rate analyst explanations as usable for advising sessions.
+- Feedback submission rate is sufficient to identify false-positive and missed-risk patterns without raw message collection.
+
+## False-positive / false-negative tracking
+- False positives: collect anonymous category, context, platform, level, and “too high” calibration signals.
+- False negatives: collect anonymous category, context, platform, level, and “too low” or “missed risk” signals.
+- Review weekly during pilots; update rules only when evidence appears across multiple users or counselor review.
+- Keep raw messages out of feedback; if a real case needs review, use a separate consented and redacted workflow.
+
+## Counselor interview goals
+- Learn whether the risk-area language matches how counselors explain scams.
+- Identify missing institution workflows, escalation paths, and country-specific resource needs.
+- Test whether false-positive warnings reduce overreaction.
+- Ask what would make the dashboard useful enough for a 30-day pilot.
+
+## Student usability testing
+- Observe whether students know what to do after a high, medium, or low result.
+- Test comprehension of “risk indicators detected” vs. certainty claims.
+- Confirm students can copy and adapt verification scripts.
+- Confirm students know not to paste passports, cards, OTPs, or private documents.

docs/VALIDATION_PLAN.md

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import { analyzeMessage } from './analyzer';
 import { redactSensitiveText } from './redaction';
 import { createAnonymizedReportPayload, payloadContainsRawSensitiveData } from './lib/privacy/reportSchema';
+import { createAnonymousFeedbackRecord, feedbackContainsRawMessage } from './lib/feedback/feedbackSchema';
 import type { CheckInput } from './types';
 
 const base: CheckInput = { language: 'English', countryRegion: 'India', destinationCountry: 'Canada', platform: 'email', context: 'visa', message: '' };
@@ -129,6 +130,14 @@ describe('redactSensitiveText', () => {
     expect(result.highRiskMarkers).toContain('bank/account words near numbers');
   });
 
+  it('keeps raw messages out of anonymous feedback records', () => {
+    const input = { ...base, message: 'We detected unauthorized login activity on your account. Your card is temporarily locked. Click here immediately to verify your identity.' };
+    const result = analyzeMessage(input);
+    const feedback = createAnonymousFeedbackRecord({ helpful: 'yes', verifiedOfficialChannel: 'not yet', calibration: 'accurate', category: 'useful' }, result, input.context, input.platform);
+    expect(feedbackContainsRawMessage(feedback)).toBe(false);
+    expect(JSON.stringify(feedback)).not.toContain(input.message);
+  });
+
   it('keeps raw sensitive data out of report payload creation', () => {
     const input = { ...base, message: 'Email student@example.com passport A1234567 card 4111111111111111 Telegram @visa_agent_now https://bad.test' };
     const result = analyzeMessage(input);

src/analyzer.test.ts

@@ -0,0 +1,21 @@
+import { packsForText } from '../data/resourcePacks';
+import type { ScamCase } from '../types';
+
+export function CaseCard({ item }: { item: ScamCase }) {
+  const relatedPacks = packsForText(`${item.scamType} ${item.messageSample}`, item.tags);
+  return (
+    <article className="case-card">
+      <p className="eyebrow">{item.sourceType} case · {item.platform}</p>
+      <h2>{item.title}</h2>
+      <p className="case-summary">{item.shortSummary}</p>
+      <p><strong>Target:</strong> {item.targetGroup}</p>
+      <p><strong>Claimed authority:</strong> {item.fakeAuthority}</p>
+      <blockquote>{item.messageSample}</blockquote>
+      <h3>Risk indicators detected</h3>
+      <ul className="red-flags">{item.redFlags.map((flag) => <li key={flag}>{flag}</li>)}</ul>
+      <h3>Safe response</h3><p>{item.safeResponse}</p>
+      {relatedPacks.length > 0 && <><h3>Relevant resource packs</h3><div className="tags">{relatedPacks.map((pack) => <span key={pack.id}>{pack.title}</span>)}</div></>}
+      <div className="tags">{item.tags.map((tag) => <span key={tag}>{tag}</span>)}</div>
+    </article>
+  );
+}

src/components/CaseCard.tsx

@@ -0,0 +1,4 @@
+export function Chart({ title, data }: { title: string; data: Record<string, number> }) {
+  const max = Math.max(1, ...Object.values(data));
+  return <section className="panel"><h2>{title}</h2><div className="bars">{Object.entries(data).sort((a, b) => b[1] - a[1]).map(([label, value]) => <div className="bar" key={label}><span>{label}</span><div aria-hidden="true"><i style={{ width: `${(value / max) * 100}%` }} /></div><strong>{value}</strong></div>)}</div></section>;
+}

src/components/Chart.tsx

@@ -0,0 +1,13 @@
+import { demoMessages } from '../data/demoMessages';
+
+export function DemoMessageSelector({ demoId, onSelect }: { demoId: string; onSelect: (id: string) => void }) {
+  return (
+    <section className="demo-box" aria-labelledby="sample-heading">
+      <h2 id="sample-heading">Try a sample message</h2>
+      <p className="muted">Synthetic samples help counselors and students understand common risk indicators without entering private data.</p>
+      <div className="chip-row">
+        {demoMessages.map((demo) => <button key={demo.id} type="button" className={demoId === demo.id ? 'active-chip' : 'chip'} onClick={() => onSelect(demo.id)}>{demo.label}</button>)}
+      </div>
+    </section>
+  );
+}